Skip to main content

Public API Basics

The Verdictan API is the control plane and audit plane for organizations. It owns identity, configuration, evidence, billing, and connected-gateway coordination.

Gateway model traffic uses the gateway runtime routes that are in other guides.

Get the contract​

The active API publishes an OpenAPI 3.1 document at:

GET /v1/openapi.json

Use that document for specified request fields, response schemas, permissions, and endpoint-specific pagination. The /v1/ path is the major-version boundary.

Each response also contains this header:

x-verdictan-api-version: 1.0

Do not infer an endpoint from a console URL or a generated client name. The public OpenAPI document and customer docs must contain the path.

Until Verdictan documents the path, identify it as unsupported.

Select the correct base URL and region​

Use the API base URL for the organization and requested region. To find available regions, use these commands:

verdictan regions list
verdictan regions current

Keep API locality different from gateway provider locality. A CLI profile API region does not change provider routing in policy-config.yaml.

Authenticate​

Most organization-scoped /v1 calls use:

Authorization: Bearer <scoped-token>

Public discovery, authentication callbacks, and machine-gateway routes have their own contracts. Do not send a human API token to a machine-only /v1/gateway/... route.

Use a human credential for console or CLI administration.

Use a control-plane credential for automation.

Use a machine credential for a connected gateway.

Use a client credential for application requests through the model gateway.

Browser sessions and API tokens are different authentication methods. Do not copy a browser cookie flow into a server integration.

Some documented browser protocols start at an API URL. Google and GitHub sign-in start at /v1/auth/google/start and /v1/auth/github/start.

Make a request​

Use this example to read data:

curl --fail-with-body \
  --header "Authorization: Bearer $VERDICTAN_API_TOKEN" \
  --header "Accept: application/json" \
  --header "X-Request-Id: evidence-review-request-01" \
  "$VERDICTAN_API_URL/v1/agents"

For JSON writes, add:

Content-Type: application/json

Do not put tokens in query strings. Redact authorization fields and secret fields from logs.

Correlate requests​

Verdictan removes whitespace from the start and end of X-Request-Id. The result must contain 1–128 permitted characters.

Use ASCII letters, digits, or -, _, ., and :. If the value follows these rules, Verdictan returns the caller value.

It replaces a missing or invalid value with a generated ID.

Responses contain X-Request-Id. Error bodies include request_id.

Verdictan also accepts and propagates traceparent. If traceparent is missing, Verdictan generates one.

Log request IDs, not credentials or sensitive bodies.

Handle the canonical error envelope​

Errors use:

{
  "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."
          }
        ]
      }
    }
  }
}

An error body always contains status, code, message, request_id, and error_id.

The error body contains details only when the error has structured details. If not, it does not contain this field.

The client must:

  1. Use the HTTP status and stable error.code to select the application action.
  2. When applicable, display a safe message.
  3. Map field errors from details.fields.
  4. Log request_id and error_id.
  5. Do not parse human message text as a machine contract.

Client-error classes include validation 400 or 422, authentication 401, and authorization 403.

They also include not found 404, conflict 409, and rate limit 429. Server-error classes include internal error 500 and upstream dependency failure 502.

Paginate according to the endpoint​

Pagination does not have one universal format. The public schema can use limit, cursor, and a returned next_cursor. An endpoint can also use a different documented result wrapper.

Use this procedure for cursor pagination:

  1. Set a bounded limit.
  2. Process the returned items.
  3. Pass the specified next_cursor to the next request.
  4. When the response has no next cursor, stop.
  5. Preserve filters and sort parameters across pages.

The cursor format is not specified. Do not decode cursors. Do not change them. Do not keep them as durable resource IDs.

Retry safely​

On 429, use the value in Retry-After when the response contains this field. Use bounded exponential backoff with jitter for temporary failures.

These failures include 429, 502, 503, and network failures.

If the operation is safe, retry automatically:

  • Reads are usually safe.
  • A write is safe only if the endpoint documents idempotency.
  • A write is also safe if the caller can prove the active operation state.
  • Do not automatically retry invitations, payments, role mutations, deletes, or other non-idempotent actions.

The API has no universal idempotency-header contract. Follow the schema for the selected endpoint.

When the result of a write is uncertain after a timeout, examine the active state. Use a resource read or client-controlled identifier search.

Concurrency and stale state​

Before a destructive mutation:

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

After multiple minutes, verify the active state. Do not use a console page as proof of the active state.

Health and readiness​

EndpointMeaning
/healthzThis endpoint reports process liveness and health.
/readyzThis endpoint reports service readiness.

The two endpoints do not prove that a model request can traverse a gateway or resolve a provider credential.

They do not prove policy execution or evidence delivery.

For that proof, send a representative request through the gateway.

Security checklist​

  • Grant the token only necessary roles and actions.
  • If Verdictan supports a scope, apply it to resources and the region.
  • Store tokens in a secret manager.
  • After exposure or an ownership change, rotate the token.
  • Revoke the previous token.
  • Validate TLS.
  • Do not disable certificate verification in production.
  • Keep data in request and response logs to a minimum.
  • Use different clients for production and non-production environments.
  • Review Trail for administrative writes.

Next steps​