LicenseKit Docs

Appearance

API Reference ​

Use this page to find the machine-readable contract, reference entry points, and the most important adjacent reference pages.

Who This Is For ​

  • developers reading the API directly from OpenAPI
  • SDK maintainers and code generators
  • AI agents that need precise route, scope, and schema references

When To Use This ​

Read this page when you need the canonical contract or when you want to pivot from a task guide to a reference source.

How It Works ​

Primary contract source ​

The machine-readable contract source of truth is:

  • openapi.yaml

Use it for:

  • routes and methods
  • operationIds
  • request and response schemas
  • security requirements
  • operation-level x-required-scopes

Human-readable reference pages ​

Use these alongside OpenAPI:

Machine-readable assets ​

The public reference surface should include:

  • /openapi.yaml
  • /llms.txt
  • /llms-full.txt

These assets complement, not replace, the human-readable docs.

How to read the API quickly ​

For most integrations:

  1. find the operation by operationId
  2. confirm the auth surface
  3. confirm x-required-scopes if it is a management route
  4. check the envelope shape
  5. review adjacent contract notes for semantics not obvious from schema alone

Example ​

Typical reference workflow:

text
Need: create a frozen usage export
OpenAPI route: POST /api/v1/reports/exports
operationId: createReportExport
auth: bearer
x-required-scopes: ["report:export"]
body: { report_kind, format?, filters? }
follow-up: GET /api/v1/reports/exports/{id}
download: GET /api/v1/reports/exports/{id}/download

Common Mistakes ​

  • treating README examples as more authoritative than OpenAPI
  • inferring scopes from route naming instead of reading x-required-scopes
  • using reference pages as a substitute for checking actual request and response schemas

Prototype docs shell for the rewrite workspace.

LicenseKit