Verdictan API Overview

Verdictan has two HTTP APIs. Use the control-plane API to manage agents, configurations, access, and recorded evidence from your code. Use the gateway API to send model requests through your gateway.

Available APIs

API	Base URL	Credential	Use it for
Control-plane API	https://api.eu.verdictan.com or https://api.us.verdictan.com	API token or OAuth access token	Manage agents, gateways, tokens, events, and evidence exports
Gateway API	Your central agent URL, or http://127.0.0.1:41002 for a local test	Client API token	Send chat, embeddings, audio, and moderation requests to a model
Gateway MCP endpoint	https://<your-published-hostname>/mcp	Access Key or Gateway Key	Connect an MCP client to the tools of a published gateway

Control-plane API

EndpointsFind the control-plane routes for tokens, agents, gateways, events, and exports.OAuth clientsGet user consent with PKCE. Exchange, refresh, and revoke OAuth tokens.PermissionsFind the IAM action that a token must have for each operation.

Gateway API

Request familiesFind the gateway routes for text, embeddings, audio, and moderation, and their policy stages.Streaming and SSEStream text responses with Server-Sent Events. Learn when the gateway buffers a stream.WebSocket gatewayOpen a WebSocket session. Learn how the gateway applies policy to each text frame.Format translationFind the request and response formats that the gateway translates for each provider.MCP endpointConnect an MCP client to the /mcp endpoint of a published agent hostname.Central agent URLSend requests to a local gateway through its published HTTPS agent URL.

Make your first API request

Create an API token with the agents:list permission. Select the API host for your organization:

Region	Base URL
EU	https://api.eu.verdictan.com
US	https://api.us.verdictan.com

Run these commands in your terminal. They set the URL and token, then list the agents that you can access:

export VERDICTAN_API_URL="https://api.eu.verdictan.com"
export VERDICTAN_API_TOKEN="replace-with-your-api-token"

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $VERDICTAN_API_TOKEN" \
  --header "Accept: application/json" \
  "$VERDICTAN_API_URL/v1/agents"

Result: a 200 response contains the agents that the token can access. An empty list is correct if the token has no accessible agents. For 401, examine the credential. For 403, examine its role permissions.

Keep the token in server-side code or a secret store. Do not put it in a public webpage or a URL.

To send a model request through the gateway API, use the structured output example.

Base URL and region

Use the API base URL for the requested region of your organization. The CLI shows the available regions and the resolved endpoint:

verdictan regions list
verdictan regions current

API locality and gateway provider locality are different settings. A CLI profile region does not change provider routing in policy-config.yaml. See Regions Overview.

The gateway API uses a different base URL. Open the agent in Agents in the Console and copy its central agent URL. For a direct local test, use http://127.0.0.1:41002. Gateway routes start with /v1/, for example POST /v1/chat/completions. See Use Your Central Agent URL.

Authentication

Organization-scoped /v1 routes use a bearer token:

Authorization: Bearer <api-token>

Each principal uses one credential type:

Principal	Credential
Human Console or CLI administrator	Browser session or verdictan auth login profile
Control-plane automation	API token with a scoped role
Connected gateway	Gateway runtime token on the machine-only /v1/gateway/... routes
Application that sends model traffic	Client API token at the gateway, not at the control-plane API
Third-party delegated application	OAuth access token with approved scopes

Do not send a human API token to a machine-only /v1/gateway/... route. Do not copy a browser cookie flow into a server integration. Public discovery routes and authentication callbacks have different contracts. This also applies to the Google and GitHub sign-in routes at /v1/auth/google/start and /v1/auth/github/start.

Request format

Item	Rule
Base path	/v1/ is the major-version boundary
Authorization header	Bearer <api-token> on organization-scoped routes
Accept header	application/json
Content-Type header	application/json on JSON writes
X-Request-Id header	Optional. 1 to 128 characters from ASCII letters, digits, -, _, ., and :
traceparent header	Optional W3C trace context
Query string	Do not put a token in a query string

Verdictan removes whitespace from the start and end of X-Request-Id. If the value follows the rule, Verdictan returns the same value in the response. If the value is missing or invalid, Verdictan generates an ID. Error bodies contain the same ID as request_id. Verdictan sends a correctly formatted traceparent to related services. It generates this header if it is missing.

Versioning and OpenAPI

The /v1/ path prefix is the major-version boundary. Each response contains the contract version header:

x-verdictan-api-version: 1.0

The active API publishes an OpenAPI 3.1 document at GET /v1/openapi.json. Use it for request fields, response schemas, permissions, and endpoint-specific pagination. If the OpenAPI document and the customer docs do not contain a path, do not use the path. Do not infer an endpoint from a Console URL or a generated client name.

Error envelope

API errors use this envelope:

{
  "error": {
    "status": 422,
    "code": "validation.failed",
    "message": "Validation failed.",
    "request_id": "0123456789abcdef0123456789abcdef",
    "error_id": "err_example",
    "details": {
      "fields": {
        "name": [
          {
            "code": "required",
            "message": "Name is required."
          }
        ]
      }
    }
  }
}

Field	When included	Meaning
status	Always	HTTP status code
code	Always	Stable machine-readable error code
message	Always	Safe client-facing message
request_id	Always	Correlation ID of the request
error_id	Always	Unique ID of this error occurrence
details	Only with structured details	Field validation errors in details.fields

A client must:

1. Select the application action from the HTTP status and the stable code.
2. Show the message only when a safe message is useful.
3. Map field errors from details.fields.
4. Log request_id and error_id.
5. Not parse the message text as a machine contract.

Class	Status codes
Validation	400, 422
Authentication	401
Authorization	403
Not found	404
Conflict	409
Rate limit	429
Internal error	500
Upstream dependency failure	502

The gateway API uses a different error envelope for policy blocks and provider failures. See Handle Policy Blocks and Gateway Errors.

Rate limits

When the control-plane API rejects a request because of a rate limit, it returns 429. If the response contains Retry-After, wait for that time before the next request. Then apply the retry rules.

The gateway applies the request limits in its policy configuration. When a gateway limit stops a request, the gateway returns 429 with Retry-After. See Rate Limit Configuration. On a connected gateway, an access policy's per-minute limit (rpm_per_token or tpm_per_token) returns 503 with usage_authorization_rate_limited instead. Retry-After may be present.

Pagination

Pagination formats are different for some routes. Many list routes accept limit and cursor and return next_cursor. Other routes use a different documented result wrapper. Follow the schema of the selected route.

For cursor pagination:

1. Set a bounded limit.
2. Process the returned items.
3. Pass the returned next_cursor to the next request.
4. If the response has no next cursor, stop.
5. Keep the same filters and sort parameters on each page.

The cursor format is not a contract. Do not decode, change, or store a cursor as a durable resource ID.

Retries and idempotency

• On 429, wait for the value in Retry-After when the response contains the header.
• For 429, 502, 503, and network failures, use bounded exponential backoff with jitter.
• You can retry a read automatically. Retry a write only if its route supports idempotency or the caller can verify the operation state.
• Do not retry invitations, payments, role mutations, deletes, or other non-idempotent actions automatically.
• The API has no idempotency header that applies to all routes. Follow the schema of the selected route.
• If the result of a write is uncertain after a timeout, read the resource or search with a client-controlled identifier.

Before a destructive mutation:

1. Read the active resource.
2. Compare the identifier, the version, or the update time that the route returns.
3. Show the planned change.
4. Execute the change one time.
5. Read the resource again.
6. Examine Trail.

Health endpoints

Endpoint	Meaning
/healthz	Process liveness and health
/readyz	Service readiness

These endpoints show the condition of the process. They do not verify provider access, policy execution, or evidence delivery. To verify these operations, send an authenticated test request through the gateway.

Limits and failure behavior

• A 401 response shows that the credential is missing, invalid, expired, or revoked.
• A 403 response with the code auth.insufficient_permissions shows that the role of the token does not allow the action. See the Permissions Reference.
• A 403 response with the code oauth.insufficient_scope shows that the OAuth access token does not have the necessary scope.
• Store tokens in a secret manager. Rotate a token after exposure or a change of owner. Then revoke the previous token.
• Validate TLS. Do not turn off certificate verification in production.
• Redact authorization headers and secret fields from logs. Log request IDs, not credentials or sensitive bodies.
• Use different API tokens for production and non-production environments.
• Review Trail after administrative writes.

Next steps

• Control-Plane API Endpoints: find the documented route for each control-plane task.
• Runtime Request Families: select the gateway route for your client.
• Permissions Reference: find the permission for each route.
• Manage API Tokens: create and rotate API tokens.
• Debug AI Requests: trace a request with its request ID.