Platform API

Operate Constal through the authenticated, single-version HTTP API while using the SDK only for executable runtime definitions.

The Platform API is the control and invocation interface for tenant users and automation. Every public platform endpoint begins with /v1 at https://platform.constal.ai. @constal/sdk does not wrap these administrative routes: it authors code that runs inside managed Agent, Channel, Auth Provider, Policy, Credential Provider, and integration packages.

Request conventions

Authorization: Bearer <Constal API key>
Content-Type: application/json

Central authentication derives the tenant, principal, roles, scopes, expiry, revocation, customer context, and namespace Policy. Most resource families put the namespace in the path. Supported administrative contexts may accept the documented tenant or namespace header; never let an untrusted caller choose either header.

Mutations use a caller-stable eventId in JSON or an Idempotency-Key header where documented. Keep the identifier until the operation reaches a known outcome. A retry with the same identifier should retrieve the recorded result rather than duplicate the mutation.

Response conventions

Collections normally return { "data": [...], "next": ... }. Bounded snapshots may return before, after, more, truncated, or another cursor. A limit is not automatically pagination: follow only the cursor documented by that endpoint. Error responses use an HTTP status and JSON error; authorization failures identify the required action without revealing secret state.

Use Deployments and discovery, Agents, sessions, and Runs, Run controls, Resources and bindings, Customers and identity, Channels, Credentials, and Analytics and data as the endpoint map.