Skip to main content

Public API Fundamentals

The Keeptrusts API is the control and audit plane for organizations, identity, configuration, evidence, billing, and connected-gateway coordination. Gateway model traffic uses the gateway runtime routes documented separately.

Discover the contract​

The active API publishes an OpenAPI 3.1 document at:

GET /v1/openapi.json

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

x-keeptrusts-api-version: 1.0

Do not infer an endpoint from a console URL or an internal source name. If a path is absent from the public OpenAPI document and customer docs, treat it as unsupported until Keeptrusts documents it.

Choose the correct base URL and region​

Use the API base URL for the organization and requested region. Discover available regions with:

kt regions list
kt regions current

Keep API locality separate from gateway provider locality. A CLI profile's API region does not rewrite 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 separate credentials for:

  • human console or CLI administration;
  • control-plane automation;
  • connected gateway machines; and
  • application requests sent through the model gateway.

The browser console uses API-owned cookie sessions, CORS, and CSRF protection. Do not copy its cookie flow into a server integration.

Make a request​

Example read:

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

For JSON writes, add:

Content-Type: application/json

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

Correlate requests​

After surrounding whitespace is trimmed, an X-Request-Id must contain 1–128 ASCII letters, digits, or the characters -, _, ., and :. Keeptrusts echoes a valid caller-provided value; a missing or invalid value is replaced with a generated ID.

Responses expose X-Request-Id, and error bodies include request_id. Keeptrusts also accepts and propagates traceparent, generating one when it is absent.

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

status, code, message, request_id, and error_id are always present. details is present only when the error has structured details; otherwise the field is omitted.

Client behavior should:

  1. branch on HTTP status and stable error.code;
  2. display a safe message when appropriate;
  3. map field errors from details.fields;
  4. log request_id and error_id; and
  5. avoid parsing human message text as a machine contract.

Common classes include validation 400/422, authentication 401, authorization 403, not found 404, conflict 409, rate limit 429, internal error 500, and upstream dependency failure 502.

Paginate according to the endpoint​

Pagination is not one universal shape. Depending on the endpoint, the public schema can use limit, a cursor, and a returned next_cursor, or another documented result wrapper.

For cursor pagination:

  1. set a bounded limit;
  2. process the returned items;
  3. pass the exact next_cursor to the next request;
  4. stop when no next cursor is returned; and
  5. preserve filters and sort parameters across pages.

Treat cursors as opaque. Do not decode, alter, or persist them as durable resource IDs.

Retry safely​

On 429, honor Retry-After when present. Use bounded exponential backoff with jitter for retryable 429, 502, 503, and network failures.

Retry automatically only when the operation is safe:

  • reads are usually safe;
  • a write is safe only when the endpoint documents idempotency or the caller can prove the operation's current state;
  • never blindly retry invitations, payments, role mutations, deletes, or other non-idempotent actions.

The API has no universal idempotency-header contract. Follow the selected endpoint's schema. When a timeout leaves a write uncertain, read current state or search by its client-controlled identifier before trying again.

Concurrency and stale state​

Before a destructive mutation:

  1. read the current resource;
  2. compare the identifier, version, or updated time exposed by that endpoint;
  3. present the exact planned change;
  4. execute once; and
  5. read back and inspect Trail.

Do not assume a console page loaded several minutes ago still represents current state.

Health and readiness​

EndpointMeaning
/healthzProcess liveness/health
/readyzService readiness

Neither endpoint proves that a model request can traverse a gateway, resolve a provider credential, execute policies, or deliver evidence. Send a representative request through the gateway for that proof.

Security checklist​

  • Grant the token only required roles and actions.
  • Scope resources and region where supported.
  • Store tokens in a secret manager.
  • Rotate and revoke on exposure or ownership change.
  • Validate TLS and never disable certificate checks in production.
  • Keep request/response logging data-minimized.
  • Separate production and non-production clients.
  • Review Trail for administrative writes.

Next steps​