API Reference
ANTS Platform has a public REST API for sending trace data, for reading and managing observability, evaluation and administration data, and for reading and changing governance, inventory and policy records. The SDKs use the same API.
Base path and OpenAPI spec
All public endpoints live under /api/public on your ANTS Platform host. Use the same host your SDKs are configured with (ANTS_PLATFORM_HOST in Python, ANTS_PLATFORM_BASE_URL in JS/TS and Java).
The full OpenAPI specification, with request and response schemas for every endpoint below, is served by the platform at:
Authentication
Use HTTP Basic auth with your public key as the username and your secret key as the password. Create keys under API Keys.
There are two kinds of keys:
- Project keys give access to one project's data. Most endpoints use them.
- Organization keys are required for the organization management endpoints: projects, memberships, project API keys and SCIM.
See Authentication for details.
Resources
Paths are relative to /api/public.
Tracing and ingestion
| Resource | Endpoints |
|---|---|
| Ingestion | POST /ingestion accepts a batch of events such as trace-create, span-create, generation-create and score-create. |
| OpenTelemetry | POST /otel/v1/traces accepts OTLP/HTTP traces as application/x-protobuf or application/json. |
| Traces | GET /traces, GET /traces/{traceId}, DELETE /traces/{traceId}, DELETE /traces |
| Observations | GET /observations, GET /observations/{observationId} |
| Sessions | GET /sessions, GET /sessions/{sessionId} |
| Media | POST /media, GET /media/{mediaId}, PATCH /media/{mediaId} |
| Comments | POST /comments, GET /comments, GET /comments/{commentId} |
| Metrics | GET /metrics takes a JSON query to aggregate traces, observations or scores (for example count, latency or cost, grouped and filtered). |
Evaluation
| Resource | Endpoints |
|---|---|
| Scores | POST /scores, DELETE /scores/{scoreId}, GET /v2/scores, GET /v2/scores/{scoreId} |
| Score configs | POST /score-configs, GET /score-configs, GET /score-configs/{configId} |
| Datasets | POST /v2/datasets, GET /v2/datasets, GET /v2/datasets/{datasetName} |
| Dataset items | POST /dataset-items, GET /dataset-items, GET /dataset-items/{id}, DELETE /dataset-items/{id} |
| Dataset runs | GET /datasets/{datasetName}/runs, GET /datasets/{datasetName}/runs/{runName}, DELETE /datasets/{datasetName}/runs/{runName} |
| Dataset run items | POST /dataset-run-items, GET /dataset-run-items |
| Annotation queues | Create and list queues, and add, update, list and remove queue items and assignments under /annotation-queues |
Prompts and models
| Resource | Endpoints |
|---|---|
| Prompts | POST /v2/prompts, GET /v2/prompts, GET /v2/prompts/{promptName}, PATCH /v2/prompts/{name}/versions/{version} (update labels) |
| Models | POST /models, GET /models, GET /models/{id}, DELETE /models/{id}. These are model definitions used to match usage and calculate cost. |
| LLM connections | GET /llm-connections, PUT /llm-connections (create or update a provider connection; secrets are never returned) |
Governance, inventory and policy
The governance API is off by default. It needs the deployment to allow it and an administrator to turn on Governance public API in Organization Settings → Features. See Governance API for setup, every endpoint, examples and errors.
| Resource | Read | Write | Key |
|---|---|---|---|
| Agents | List a project's agents and get one agent | - | Project or organization key |
| Governance profiles | Get an agent's governance profile | Update governance profile fields | Reads: project or organization key. Writes: organization key |
| Framework coverage | Coverage per framework for a project's agents | - | Project or organization key |
| Guardrail policy | Get an agent's guardrail policy | Create and update an agent's guardrail policy | Reads: project or organization key. Writes: organization key |
| AI tool registry | List the Discover AI tool registry | - | Organization key |
| Sanction status | Get the sanction status of each AI tool | Set an AI tool's sanction status | Organization key |
| Model approvals | List AI Inventory models with their organization approval status | - | Organization key |
Every write needs an organization key with Governance write turned on, and the organization's access set to Read and write. A project key reads only its own project. Writes go through the same validation as the app, and every read and write is recorded in the audit log. See Agent profiles, Tool Registry and AI Guardrails for what each record means.
Organization and access management
| Resource | Endpoints | Key |
|---|---|---|
| Projects | GET /projects returns the key's project. POST /projects, PUT /projects/{projectId}, DELETE /projects/{projectId}, GET /organizations/projects | Project key for GET /projects, organization key for the rest |
| Memberships | GET /organizations/memberships, PUT /organizations/memberships, GET /projects/{projectId}/memberships, PUT /projects/{projectId}/memberships | Organization key |
| Project API keys | GET /projects/{projectId}/apiKeys, POST /projects/{projectId}/apiKeys, DELETE /projects/{projectId}/apiKeys/{apiKeyId} | Organization key |
| SCIM users | GET /scim/Users, POST /scim/Users, GET /scim/Users/{userId}, PUT /scim/Users/{userId}, PATCH /scim/Users/{userId}, DELETE /scim/Users/{userId}, plus ServiceProviderConfig, ResourceTypes and Schemas | Organization key |
| SCIM groups | GET /scim/Groups, POST /scim/Groups, GET /scim/Groups/{groupId}, PATCH /scim/Groups/{groupId}, DELETE /scim/Groups/{groupId} | Organization key |
Automations
Manage a project's automation rules with a project key.
| Endpoint | What it does |
|---|---|
GET /automations | Lists the project's rules, each with its paths, actions, action health (consecutiveFailures, disabledReason), version, lastRunAt and lastRunStatus |
POST /automations | Creates a rule. Returns 201 with the rule, and webhookSecrets (signing secrets keyed by action ID, shown once) when the rule has new webhooks. |
GET /automations/{ruleId} | Gets one rule |
PUT /automations/{ruleId} | Replaces a rule. Keep the path and action id values to keep their webhook secrets and health. |
DELETE /automations/{ruleId} | Deletes a rule and its runs. Returns 204. |
The request body is the rule JSON, the same as the rule object of an exported rule: name, eventType (an event key such as guardrail.violation), conditions, matchMode (FIRST or ALL), paths with their actions, and the optional description, enabled, throttle, dedupe, aggregation, digest and activeHours. Secret header values are never returned.
Rules go through the same validation and limits as in the app, and every change is written to the audit log. A key cannot:
- add platform responses (suspend agent, block a Budget AI key, set a tool sanction, add to a case),
- use events that carry admin or device data (
audit.event,api_key.created,api_key.revoked,api_key.expiring,access.user_deprovisioned,device.alert,device.certificate_expiring), - delete a rule that a person created in the app.
Set those up in the app. Errors return message and an issues list of path and message: 400 for an invalid rule, 403 for a refused event or response, 404 for an unknown rule, 409 for a name already used in the project, and 422 when the project already has 100 rules. On a deployment where project keys are limited to trace ingestion, these endpoints return 403.
Health
GET /health reports API health.
Example: send a trace
The endpoint returns 207 with a successes list and an errors list, one entry per event. Use a new event id for every event. Reuse the same body.id to update a trace.
Not available in the public API
These features are managed in the app only. There are no public REST endpoints for them:
- Changing model approvals in the AI Inventory, and the framework catalog
- Agent evidence, compliance requests and risk scores
- Discover AI usage reporting, users and devices
- Gateway keys, budgets and limits
- Dashboards and reports
Planned capabilities are listed on the roadmap.
Errors
Errors return a standard HTTP status code and a JSON body with a message field:
| Status | Meaning |
|---|---|
400 | Invalid request |
401 | Missing or invalid API key |
402 | Ingestion blocked by the organization's plan or credit status |
403 | The key does not have access to this operation |
404 | Resource not found |
405 | Method not allowed |
429 | Rate limit exceeded |
500 | Server error |
Rate limits
Requests can be rate limited per organization and per resource, for example ingestion, datasets or metrics. A limited request returns 429 with these headers:
Retry after the number of seconds in Retry-After.
Webhooks
Outbound webhooks are the Webhook action of an automation rule. Set rules up in Project Settings → Automations, or with the Automations endpoints. A rule can send a webhook for any of its 30 events, such as guardrail violations, drift alerts, Discover AI and device alerts, Budget AI thresholds, exports, audit log entries and prompt version changes.
Each webhook is an HTTP POST with a JSON body. New webhooks send the v2 event envelope with content-type: application/json; ants-api-version=v2. A prompt version change looks like this:
Prompt webhooks moved from the old automations keep their v1 body ("type": "prompt-version", "apiVersion": "v1"), which carries the full prompt version. The envelope fields and the v1 policy-violation body are documented in Policy Violation Webhooks.
Verifying the signature
Each delivery includes a signature header:
To verify it, compute HMAC-SHA256(secret, "<t>.<raw request body>") as a lowercase hex string, where <t> is the timestamp from the header and secret is the webhook action's signing secret, and compare it with the v1 value. Use t to reject old deliveries. x-langfuse-signature is no longer sent. See Headers and signature.
SDKs
The Python, JS/TS and Java SDKs handle authentication and call this API for you.