# API

The rules that apply on every route (address, authentication, errors, throttling, paging, stability) and the guide through the reference.

> **Type:** area
> **For:** Anyone who builds calls against /v1, has to interpret an error response, or wants to find their way around the reference.

![The portal dialog “Create API key” with a filled-in name field, the six permission classes (“Read only” is selected, with 19 permissions), and the selection fields for the validity of the new and the old key](/api/bilder/d5a9585e-overview.png)

*The rules of this area apply to calls made with an `ak_…` key. Keys are issued, rotated, and revoked in the portal under Settings › API keys.*

## Basics

| Page | When you need it |
|---|---|
| [Base URL, /v1, and stability](/api/base-url-and-stability) | Where the base URL comes from, why almost every route carries /v1, which paths lie outside it, and what x-stability promises per operation. |
| [Authentication: keys and sessions](/api/authentication) | Bearer header, key prefixes, permission scope, expiry and rotation of a key, and when a session makes more sense than a key. |
| [The error format](/api/error-format) | The error body with code, message, and traceId, the RFC 9457 form, and the rule by which a code becomes the HTTP status. |
| [Concurrent changes: ETag and If-Match](/api/etag-and-if-match) | Read a versioned resource, send the version back as If-Match, and resolve a 409 conflict cleanly. |
| [Throttling and rate-limit headers](/api/rate-limits) | Which routes have a limit of their own, which rate limit is attached to a key, what the four headers mean, and how a client reacts to 429. |
| [Paging: limit, cursor, items, nextCursor](/api/pagination) | Cursor paging on all lists, the limits 50/200 and 25/100, the four routes with page, and how the CLI follows all pages with --all. |

## Access methods and resources

| Page | When you need it |
|---|---|
| [Delegated access with OAuth 2.1](/api/oauth-delegated-access) | Your application runs at other customers’ sites: register, have users consent with PKCE, exchange the oat_ token, renew, revoke. |
| [Provisioning with SCIM 2.0](/api/scim-provisioning) | A directory service should create accounts, suspend them, and set roles: token sct_, endpoints under /scim/v2, mapping, and errors. |
| [The MCP service for AI assistants](/api/mcp-service) | An assistant should work with your inventory: address, authentication, tool list, confirmation requirement, limits, and errors. |
| [Locations](/api/locations) | Mirror a branch structure: fields of a location, its routes, assigning a display, and analytics by location. |
| [Web displays](/api/web-displays) | Create a display with no device behind it: routes, connection URL, the two states, deletion, and the limits compared with a device. |

## Error codes

| Page | When you need it |
|---|---|
| [Error codes: possible on any route](/api/error-codes-general) | The platform-wide codes for authentication, permissions, validation, conflicts, throttling, payload, HTTP, events, caching, jobs, and resources. |
| [Error codes: accounts and sessions](/api/error-codes-accounts) | The codes of the areas Identity and Sessions: user accounts, keys, invitations, sign-in, second factor, sessions. |
| [Error codes: organization, access, joining](/api/error-codes-organization) | The codes of the areas Tenancy, Access, Onboarding, and Cloud-Connections: master data, domain, roles, grants, registration, storage connections. |
| [Error codes: billing](/api/error-codes-billing) | The codes of the area Billing: package, licenses, add-ons, payment method, invoices, and why 402 appears here. |
| [Error codes: media, scenes, programs, apps](/api/error-codes-content) | The codes of the areas Media-Library, Composition, Scheduling, App-Catalog, Marketplace, App-Runtime, and Advertising. |
| [Error codes: devices, playback, notifications, operations](/api/error-codes-devices-operations) | The codes of the areas Fleet, Playback, Realtime, Notifications, Analytics, Audit, and Ops-Console, the latter only on operator routes. |
| [Error codes: server errors (5xx)](/api/error-codes-server) | The 119 codes to which a client cannot react in a domain-specific way: invariants, startup, database, downstream services. Retry or report. |

## Guide to the reference

| Page | When you need it |
|---|---|
| [Read the reference](/api/read-reference) | Find an operation at /api/reference, read off permission, security scheme, example, and stability, and download the specification. |
| [The areas of the reference](/api/reference-areas) | The 19 tags of the specification in their 7 groups with one sentence of purpose each, and why the operator surface is not part of it. |
| [Generate your own client from the specification](/api/generate-client) | There is currently no published client. Here is how you generate your own from openapi.json and map the conventions of the API into it. |