Docs
Connections

OpenAPI

Import an OpenAPI 3.0, 3.1 or 3.2 specification, bind GET operations with pagination and field selection, and use the GitHub, Stripe and Docker Hub presets.

An OpenAPI connection reads JSON from GET operations that you select from an API's specification. Requests go through the shared egress policy (HTTPS only, verified TLS, pinned address, redirects refused). See Connections.

Set up the connection

Open Connections, choose New connection, then OpenAPI. Optionally pick a preset.
Give the specification's URL, or upload the file (JSON or YAML). Xentropy parses it on the server and shows its operations. The full document is never sent to your browser.
Choose the server URL and the authentication option. Enter any credential headers that option requires.
Select operations. For each one, set the collection path, the pagination and the fields.
Save. Xentropy stores only the selected operations and the schemas they reference.

How the import works

  • The specification URL is fetched over HTTPS through the egress policy, with a 30 s limit and no redirects. Uploaded and fetched specifications can be up to 32 MiB.
  • OpenAPI 3.0, 3.1 and 3.2 are accepted, as JSON or YAML. YAML aliases are capped, so alias-expansion documents are refused. Features new in 3.2, such as the query method and additionalOperations, are ignored rather than rejected.
  • The parsed specification is kept on the server for 15 minutes (at most 10 per user), so that the save can use it. When you save, the specification is pruned to the selected operations and every schema they reference. That pruned copy must be 1 MiB or smaller, and it is what Xentropy stores, along with the source URL and a SHA-256 digest. The original document is not stored.
  • Path-level parameters are merged into each operation. Where both define a parameter, the operation's definition wins.
  • Schema normalization:
    • allOf of objects merges into one object.
    • anyOf or oneOf with null becomes a nullable field.
    • Expandable fields, such as anyOf [string, object], use the string arm (the ID).
    • Any other union is offered as JSON text, or excluded.
    • A union as the collection item itself is rejected.

Authentication

The specification's security requirements are alternatives. A connection picks one of them:

  • anonymous, when the specification allows unauthenticated access, or
  • a scheme name, with schemes combined as a+b.

Only the headers that option requires are needed, and each must be configured before saving. These header names cannot be set: Host, Connection, Content-Length, Transfer-Encoding and any Proxy-* header.

Bindings

Each selected operation has a binding:

SettingMeaning
collectionPathPath to the array of records in the response, such as data. Empty means the response is the array
fieldsDotted field paths (up to 6 segments, up to 100 fields), such as user.login. By default, top-level scalars plus the scalars of first-level objects, up to 100 fields. Objects and arrays you select become JSON text of up to 10,000 characters
paginationHow to walk the pages (see below). Without it, one response is the whole collection, and only if you set completeCollection
acceptResponse media type: application/json, or an application/*+json type the operation declares

Array query parameters are supported for scalar items, in form style with or without explode. Optional deepObject, object, header and cookie parameters are skipped. A required parameter of one of those kinds makes the operation unbindable.

Pagination kinds

Every kind can send a fixed page size with sizeParam and pageSize (1–1000).

KindRequired settingsNext pageEnds when
cursornextPath, parameterPuts the body cursor at nextPath into the query parameterThe cursor is null or empty, or missing with absentMeansEnd
offsetnextPath, parameterPuts the body offset into parameter. The offset must increaseThe offset is null or empty
next-linknextPathFollows the URL in the body at nextPathThe link is null or empty, or missing with absentMeansEnd
link-header—Follows the Link: <…>; rel="next" header (RFC 8288)There is no next link
page-numberpageParam, sizeParam, pageSizeIncrements pageParam, starting at startPage (0 or 1, default 1)There is no next link, the totalPath total is reached, or a page is short
last-item-cursorcursorParam, itemCursorPath, hasMorePathSends the last item's cursor (such as Stripe's starting_after = id)hasMorePath is false

Completeness rules:

  • Every page must stay on the operation's origin and path. With linkQueryOnly, only the next link's query is applied, and the link must stay on the same origin.
  • A field missing from the termination path, a repeated page or cursor, or an offset that does not advance fails the read with INCOMPLETE_DATA. The exception is cursor and next-link with absentMeansEnd: true: there a missing value ends the read, for APIs such as Google's that leave nextPageToken out of the last page.
  • The parameter of cursor and offset (like cursorParam, pageParam and sizeParam) must be a query parameter that the operation declares.
  • totalPath is checked against the number of rows read. snapshotPath must stay the same on every page.
  • page-number stops on a short page only if a totalPath exists or you acknowledged completeCollection. A source that returns more rows than the page size fails.
  • last-item-cursor requires the boolean hasMorePath on every page.

Automatic list and pagination detection

When you choose an operation, Xentropy reads its response schema and declared parameters, and suggests the list and the pagination. Nothing is sent to the API to do this.

The list. The response's arrays of records, up to two levels deep, are ranked:

  • A response that is itself an array is the list.
  • A conventional name (data, items, results, records, entries, values, rows, list, edges, nodes), or the resource in the operation's path (users for /users), ranks first.
  • Then the only array of records, then one at the top level rather than nested.

The List in the response field always shows the pick and why it was made. You can choose another list.

Pagination. Each kind pairs a property of the response with a query parameter of the request:

KindResponseRequest
cursornextPageToken, next_cursor, cursor, response_metadata.next_cursor and similarpageToken, cursor, after and similar
next-linknext, next_url, links.next, _links.next.href, or a URL property named like next—
last-item-cursorboolean has_more or hasMorestarting_after, after or since_id
offsetnext_offset or nextOffsetoffset, skip or start, plus limit
page-numbertotal, total_count or meta.totalpage, page_number or pageNumber
link-headera declared Link response headerpage and per_page

The page size parameter is the first of per_page, page_size, pageSize, limit, maxResults and max_results. Its size is the parameter's maximum, else its default, up to 1000.

  • When both sides match, the suggestion is filled in for you, marked Inferred from the API description. It stays editable.
  • When only one side matches, the form offers a Use suggestion button and says what is missing.
  • If you picked a preset or changed a pagination field, your choice is kept; a suggestion is only offered.
  • Suggested cursor and next-link pagination sets absentMeansEnd, so a missing token on the last page ends the read.

Agents can ask for the same inference: in connections_create, with openapi.specUrl or openapi.source, give a binding "pagination": "infer". The server then uses the suggestion, and the ranked list when collectionPath is left out. If the specification is not conclusive, the call fails with the reason, and any partial suggestion is in details.suggestion. Give the pagination explicitly in that case.

Presets

Presets fill in defaults only. Everything stays editable and is validated like manual input. Agents can list presets with GET /api/v1/data/openapi/presets.

PresetServerAuthenticationCollection and paginationSuggested operationsHeaders
GitHub REST APIhttps://api.github.comThe specification's own options (anonymous or a token)link-header, per_page = 100, following only the next link's queryissues/list-for-repo, repos/list-releases, pulls/listX-GitHub-Api-Version: 2022-11-28
Stripe APIhttps://api.stripe.combearerAuthCollection data. last-item-cursor with starting_after from id, ending on has_more, limit = 100GetCustomers, GetCharges, GetInvoicesStripe-Version from the specification's info.version
Docker Hub APIhttps://hub.docker.combearerAuthCollection results. next-link on next, total count, page_size = 100listNamespaceRepositories—

For GitHub data, use a Git connection first: it reads repositories, commits, pull requests, issues and workflow runs into typed tables with a read-only token. The GitHub preset stays for other GitHub API endpoints.

Each preset fetches the provider's published specification. Use a read-only token wherever the provider offers one: for Stripe, a restricted key with read access only.

Limits

LimitValue
Specification upload or fetch32 MiB, 30 s
Stored, pruned specification1 MiB
Operations in a specification1,000
Bound operations per connection100
Document complexity50,000 nodes, nesting depth 40
Pages per readFree 50, Pro 500. Previews read up to 2 pages
Read deadline120 s for all pages. Each request is limited to 30 s, or 10 s for previews
Decoded data / rows / fields5 MiB / 50,000 / 100

Rate limits and errors

A 429 answer, or a 403 with X-RateLimit-Remaining: 0 or Retry-After, becomes RATE_LIMITED, with details.retryAt taken from Retry-After or X-RateLimit-Reset. Without either header, retry after 60 s. Retries are never scheduled more than 24 hours ahead. Scheduled refreshes wait until retryAt.

CodeCauseWhat to do
RATE_LIMITEDThe API's rate limit was reachedWait for retryAt. Use a token with a higher limit
PROVIDER_UNAVAILABLEAnother non-2xx answer (details.httpStatus) or a transport failureRetry later. If it persists, check the credentials
INCOMPLETE_DATAPagination could not be proven complete, or the page budget ran outFix the pagination settings, or narrow the query
BUDGET_EXCEEDEDThe 120 s read deadline was exceededNarrow the query, or page with larger pages
LIMIT_EXCEEDEDThe specification, pruned specification, operation count, response bytes, rows or a JSON field exceeded its limitSelect fewer operations or fields, or narrow the query
SCHEMA_CHANGEDThe response no longer matches the stored schema, for example a required field is missing or a scalar became an objectRe-import the specification, and save the binding again
VALIDATION_FAILEDInvalid specification, binding, parameter or header. A required credential header is missingFollow the message
VALIDATION_EXPIREDThe connection changed while pages were being readRetry the read
PERMISSION_DENIEDThe operation is not selected, pagination tried to leave the operation, or the source redirectedSelect the operation. Use the final URL
OPENAPI_REQUIREDAn agent tried to create a legacy REST JSON connectionCreate an OpenAPI connection

On this page