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
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
querymethod andadditionalOperations, 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:
allOfof objects merges into one object.anyOforoneOfwithnullbecomes 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:
| Setting | Meaning |
|---|---|
collectionPath | Path to the array of records in the response, such as data. Empty means the response is the array |
fields | Dotted 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 |
pagination | How to walk the pages (see below). Without it, one response is the whole collection, and only if you set completeCollection |
accept | Response 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).
| Kind | Required settings | Next page | Ends when |
|---|---|---|---|
cursor | nextPath, parameter | Puts the body cursor at nextPath into the query parameter | The cursor is null or empty, or missing with absentMeansEnd |
offset | nextPath, parameter | Puts the body offset into parameter. The offset must increase | The offset is null or empty |
next-link | nextPath | Follows the URL in the body at nextPath | The 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-number | pageParam, sizeParam, pageSize | Increments 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-cursor | cursorParam, itemCursorPath, hasMorePath | Sends 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 iscursorandnext-linkwithabsentMeansEnd: true: there a missing value ends the read, for APIs such as Google's that leavenextPageTokenout of the last page. - The
parameterofcursorandoffset(likecursorParam,pageParamandsizeParam) must be a query parameter that the operation declares. totalPathis checked against the number of rows read.snapshotPathmust stay the same on every page.page-numberstops on a short page only if atotalPathexists or you acknowledgedcompleteCollection. A source that returns more rows than the page size fails.last-item-cursorrequires the booleanhasMorePathon 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 (usersfor/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:
| Kind | Response | Request |
|---|---|---|
cursor | nextPageToken, next_cursor, cursor, response_metadata.next_cursor and similar | pageToken, cursor, after and similar |
next-link | next, next_url, links.next, _links.next.href, or a URL property named like next | — |
last-item-cursor | boolean has_more or hasMore | starting_after, after or since_id |
offset | next_offset or nextOffset | offset, skip or start, plus limit |
page-number | total, total_count or meta.total | page, page_number or pageNumber |
link-header | a declared Link response header | page 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
cursorandnext-linkpagination setsabsentMeansEnd, 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.
| Preset | Server | Authentication | Collection and pagination | Suggested operations | Headers |
|---|---|---|---|---|---|
| GitHub REST API | https://api.github.com | The specification's own options (anonymous or a token) | link-header, per_page = 100, following only the next link's query | issues/list-for-repo, repos/list-releases, pulls/list | X-GitHub-Api-Version: 2022-11-28 |
| Stripe API | https://api.stripe.com | bearerAuth | Collection data. last-item-cursor with starting_after from id, ending on has_more, limit = 100 | GetCustomers, GetCharges, GetInvoices | Stripe-Version from the specification's info.version |
| Docker Hub API | https://hub.docker.com | bearerAuth | Collection results. next-link on next, total count, page_size = 100 | listNamespaceRepositories | — |
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
| Limit | Value |
|---|---|
| Specification upload or fetch | 32 MiB, 30 s |
| Stored, pruned specification | 1 MiB |
| Operations in a specification | 1,000 |
| Bound operations per connection | 100 |
| Document complexity | 50,000 nodes, nesting depth 40 |
| Pages per read | Free 50, Pro 500. Previews read up to 2 pages |
| Read deadline | 120 s for all pages. Each request is limited to 30 s, or 10 s for previews |
| Decoded data / rows / fields | 5 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.
| Code | Cause | What to do |
|---|---|---|
RATE_LIMITED | The API's rate limit was reached | Wait for retryAt. Use a token with a higher limit |
PROVIDER_UNAVAILABLE | Another non-2xx answer (details.httpStatus) or a transport failure | Retry later. If it persists, check the credentials |
INCOMPLETE_DATA | Pagination could not be proven complete, or the page budget ran out | Fix the pagination settings, or narrow the query |
BUDGET_EXCEEDED | The 120 s read deadline was exceeded | Narrow the query, or page with larger pages |
LIMIT_EXCEEDED | The specification, pruned specification, operation count, response bytes, rows or a JSON field exceeded its limit | Select fewer operations or fields, or narrow the query |
SCHEMA_CHANGED | The response no longer matches the stored schema, for example a required field is missing or a scalar became an object | Re-import the specification, and save the binding again |
VALIDATION_FAILED | Invalid specification, binding, parameter or header. A required credential header is missing | Follow the message |
VALIDATION_EXPIRED | The connection changed while pages were being read | Retry the read |
PERMISSION_DENIED | The operation is not selected, pagination tried to leave the operation, or the source redirected | Select the operation. Use the final URL |
OPENAPI_REQUIRED | An agent tried to create a legacy REST JSON connection | Create an OpenAPI connection |
Shopify
Connect a Shopify store with a Dev Dashboard app or an existing Admin API token, choose read scopes, and read orders, customers, products and inventory.
Git overview
Chart repositories, commits, pull requests, issues, releases, tags, branches, contributors and pipeline runs from GitHub, GitLab, Gitea, Bitbucket and Azure DevOps, read-only, in one set of columns.