HTTP API basics

Compute and API Management share one HTTP API. Here’s how to make a request, read the response, and page through lists.

Make a request

Send a POST with a JSON body to https://api.unkey.com/v2/{service}.{procedure}. There are no path or query parameters. The only GET routes are /v2/liveness, the health check, and /openapi.yaml and /reference, which serve the OpenAPI document and a browsable reference. See RPC naming convention for how endpoints are named.

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer <root key>" \
  -H "Content-Type: application/json" \
  -d '{"key": "sk_live_..."}'

Put a root key in the Authorization: Bearer header. See API authentication.

Read the response

Every response is a JSON object with meta. A success adds data, and a failure adds error instead.

object

required

Present on every response.

Show properties

string

required

A unique ID for this request, prefixed req_. It’s the only field in meta, and it isn’t sent as a response header. Log it with every call and include it when you contact support, so we can find the exact request.

object | array

The endpoint’s result. Its shape is documented per endpoint in each product’s API reference. List endpoints return an array here.

object

Present instead of data when the request failed. Its fields are on API error envelope.

object

Present only on list endpoints. See Page through lists.

A successful response

{
  "meta": { "requestId": "req_2c9a0jf23l4k567" },
  "data": { "keyId": "key_1234abcd" }
}

Page through lists

List endpoints use a cursor instead of page numbers. Each request takes an optional limit and cursor, and each response has a pagination object next to data. The example uses apis.listKeys, but every list endpoint works the same way.

integer

Maximum items to return. For apis.listKeys it’s 1 to 100, default 100. Most list endpoints default to 100, but ratelimit.listOverrides defaults to 50. Send limit if the page size matters to you.

string

The pagination.cursor value from the previous response, sent back unchanged. Leave it out for the first page. Cursors can expire, so don’t store them long term or build them yourself.

boolean

required

true when there’s another page. When false, you have everything and cursor may be missing or null.

string

The value to send as cursor on the next request. Only use it while hasMore is true.

Request the first page

curl -X POST https://api.unkey.com/v2/apis.listKeys \
  -H "Authorization: Bearer <root key>" \
  -H "Content-Type: application/json" \
  -d '{"apiId": "api_1234abcd", "limit": 50}'

Read the cursor

{
  "meta": { "requestId": "req_5678efgh" },
  "data": [ { "keyId": "key_1111aaaa" }, { "keyId": "key_2222bbbb" } ],
  "pagination": { "cursor": "key_3333cccc", "hasMore": true }
}

Send it back until hasMore is false

curl -X POST https://api.unkey.com/v2/apis.listKeys \
  -H "Authorization: Bearer <root key>" \
  -H "Content-Type: application/json" \
  -d '{"apiId": "api_1234abcd", "limit": 50, "cursor": "key_3333cccc"}'

Keep the other request fields the same on every page. If you change a filter partway through, the cursor no longer works.

Get started

Workspace

Billing

Root keys

API

CLI

AI coding

Security

Errors

Make a request

Read the response

Page through lists

Request the first page

Read the cursor

Send it back until hasMore is false

​Make a request

​Read the response

​Page through lists

Request the first page

Read the cursor

Send it back until hasMore is false

Make a request

Read the response

Page through lists