Skip to main content

Calling endpoints

What a program sends to call a published endpoint, and what it gets back.

URL​

{base}/api/{workspace}/{path}

For example https://opendbapi.example.com/api/demo/v1/customers/3. The api prefix is opendbapi.serving.context. Each workspace publishes an OpenAPI document of its live endpoints at /api/{workspace}/openapi.json, browsable at /api/{workspace}/docs.html.

Get a token​

Private endpoints need a bearer token. Exchange a client's id and secret for one with the OAuth2 client-credentials grant, authenticating with HTTP Basic (or client_id and client_secret form fields):

curl -s -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials https://opendbapi.example.com/oauth2/token
{"access_token": "eyJraWQiOiJi…", "token_type": "Bearer", "expires_in": 900}

Tokens last 15 minutes (opendbapi.tokens.ttl); get a new one when it expires. A wrong id or secret answers 401 invalid_client.

Call​

curl -s -H "Authorization: Bearer $TOKEN" "https://opendbapi.example.com/api/demo/v1/customers?tier=gold"

Public endpoints need no Authorization header.

Parameters​

Pass parameters where the endpoint declares them: in the path, the query string, a header, or a JSON body (Content-Type: application/json, at most 1 MB). Arrays in the query string repeat the name or separate values with commas: ?ids=1&ids=2 and ?ids=1,2 are the same.

The response​

{
"data": [{"id": 1, "name": "Ada Lovelace", "tier": "gold"}],
"meta": {
"version": 3,
"cached": false,
"page": 1, "size": 20, "total": 2, "hasNext": false,
"requestId": "cfbf7475-0d34-4002-bfc0-a20e6dbdd64f"
}
}
FieldMeaning
dataA list, an object or a value, depending on the endpoint's output shape. A write answers {"affectedRows": n}
meta.versionThe published version that answered (also the X-OpenDBAPI-Version header)
meta.cachedWhether the cache answered
meta.page, size, total, hasNextOffset pagination (total only when the endpoint counts)
meta.nextCursorKeyset pagination: pass it as after for the next page
meta.truncatedtrue when more rows existed than the endpoint returns
meta.requestIdQuote it when reporting a problem; it is in Activity too (also the X-Request-Id header)

A deprecated endpoint adds Deprecation, Sunset and Link headers; see Major versions and deprecation.

Pages​

?page=2&size=50          offset pagination
?size=50&after=<cursor> keyset pagination

Streaming​

When the endpoint allows it, ask for ?format=ndjson (one JSON object per line) or ?format=csv, or send the matching Accept header. Streams are not paginated; a stream cut short ends with a {"_meta": …} line.

Errors​

Errors are RFC 9457 problems with a stable code:

{
"type": "about:blank",
"title": "Unauthorized",
"status": 401,
"detail": "This endpoint needs an access token: Authorization: Bearer <token>.",
"code": "unauthenticated",
"requestId": "dccc29a5-b40d-4a88-b1fc-f6ad41263471"
}

The error reference lists every code. 429 answers carry Retry-After, and 401 answers carry WWW-Authenticate.