# API reference and contracts

Find runtime endpoints, customer management operations, and downloadable schemas.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/reference/api

## Start with the runtime contract

- [Evaluation API](https://docs.kastra.ai/reference/evaluate): action context, decisions, HOLD negotiation, and limits.
- [Proxy](https://docs.kastra.ai/proxy/overview): provider routes and upstream credentials.
- [Proxy approvals](https://docs.kastra.ai/proxy/approvals): async HOLD and request-bound replay.
- [Approval lifecycle](https://docs.kastra.ai/approvals/overview): status, resolution, and credential boundaries.
- [Signed webhooks](https://docs.kastra.ai/approvals/webhooks): event signatures and retry handling.

## Native response conventions

Read the envelope as well as HTTP status: a `403` with `success: true` and `data.decision: "DENY"` is a policy result; `success: false` is an error. Native errors carry human-readable `error` and, on the documented routes, a stable `code`. Provider and MCP errors retain their protocol-specific envelopes. Unknown output is never permission.

Decision history uses `ALLOW`, `DENY` and `PENDING_REVIEW`; native asynchronous evaluation uses `HOLD`. Environment IDs in console selectors are not names in policy predicates or MCP arguments. Checkpoint listing supports opt-in cursor pagination; see [the lifecycle guide](https://docs.kastra.ai/approvals/overview).

## Schema downloads

[OpenAPI JSON](https://docs.kastra.ai/openapi.json) and [OpenAPI YAML](https://docs.kastra.ai/api/openapi.yaml) preserve a local schema entry point. The schema covers the reviewed public runtime contract; it is not a claim that every internal administration route is a supported external API. Endpoint guides carry behavior that a schema alone cannot express.

## Management surfaces

Use the [customer management API reference](https://docs.kastra.ai/reference/management-api) for credentials, decision filters, pagination, policy bodies, validation, revision activation, and errors.

Customer management routes live under `/api/v1`: policies, async AI jobs, environments, devices, keys, agents, checkpoints, usage limits, evidence, integrations, and identity settings. They use user or appropriate operator credentials and route-specific roles. Avoid copying an internal `/admin` service route into a customer integration.

## Compatibility

Synchronous AI drafting routes are deprecated; use the job equivalents. A returned field may be additive across releases. Preserve unknown nested job-result fields, and fail visibly on an unknown authorization outcome rather than treating it as ALLOW.

## Source and deployment

These guides were reconciled against the local application source on the stated review date. Before a production integration depends on a recently added behavior, confirm that the deployed server release includes it. Examples use synthetic context and do not execute real user actions.

## Optional trusted-evidence capability

`GET /v1/trusted-evidence` accepts the native evaluation credentials and returns `data.protocol` (currently `1`) and `data.enabled`. This reports configured capability, not permission to execute. There is no public evidence-write HTTP API.

The custody integration is optional and is not enabled by default in the hosted service. Where configured, a trusted broker supplies bound evidence and custody-dependent policies reject missing or invalid evidence. Caller-supplied scalar attributes are not a substitute. Agree on the broker and deployment trust boundary before using this integration.