Skip to main content

Documentation Index

Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt

Use this file to discover all available pages before exploring further.

Unkey APIs prioritize developer experience, consistency, and clarity. This document outlines core design decisions and how to work with the API.

​
Core principles

  • Clear communication: structured responses make success and failure equally informative
  • Practical over purist: pragmatic choices over rigid adherence to a single paradigm
  • Predictable patterns: consistent endpoint behavior

​
Response structure

All responses share a consistent envelope: 
{
  "meta": {
    "requestId": "req_abc123xyz789"
  },
  "data": {}
}
Paginated responses include a pagination object: 
{
  "meta": {
    "requestId": "req_abc123xyz789",
    "timestamp": "2023-11-08T15:22:30Z"
  },
  "data": [],
  "pagination": {
    "cursor": "cursor_xyz123",
    "hasMore": true
  }
}

​
Working with the API

​
Always use the request ID

Every response includes a unique requestId. Include it when debugging or requesting support. You can also search for the request ID in logs.

​
Handling pagination

  1. Make your initial request.
  2. Check pagination.hasMore.
  3. Use pagination.cursor for the next request.
const response = await fetch("https://api.unkey.com/v2/keys.listKeys", {
  method: "POST",
  headers: { Authorization: `Bearer ${rootKey}` },
  body: JSON.stringify({ apiId: "api_123" })
});

if (response.pagination?.hasMore) {
  await fetch("https://api.unkey.com/v2/keys.listKeys", {
    method: "POST",
    headers: { Authorization: `Bearer ${rootKey}` },
    body: JSON.stringify({
      apiId: "api_123",
      cursor: response.pagination.cursor
    })
  });
}

​
Versioning

APIs use a major version in the URL, for example /v2/. Breaking changes increment the major version.