HTTP API reference

The hosted client wraps the worker HTTP API. You can call the API directly from trusted server-side code, or point @agntz/client / Python AgntzClient at your own worker.

Endpoint groups

Health and authoring

Agents and sessions

Some self-hosted app/server deployments also expose create/update/delete agent routes and version/alias administration. The public clients use the import and run surfaces first, so those are the portable routes.

Managed artifacts

Uploads are limited to 50 MiB. The public clients automatically upload local files and replace them with artifactId content blocks.

Runs and streams

Traces

Memory and namespace roots

Namespace-root administration is app/server owned. The worker enforces bounded grants when roots are available, and self-hosted deployments decide which admin route shape they expose.

Datasets and evals

Provider-native batches

Batch runs are provider-native asynchronous jobs and do not create ordinary runs, sessions, or traces. See Provider-native batches for manifests, status semantics, version pinning, callbacks, and client examples.

System agents and webhooks

Authentication

The worker accepts two auth modes.

External bearer token

Authorization: Bearer ar_live_<token>

The worker hashes the key, looks it up in the API-key store, resolves the tenant, and bounds namespace grants to that tenant's roots. This is what hosted clients send.

Internal app-to-worker secret

X-Internal-Secret: <WORKER_INTERNAL_SECRET>

The product app uses this when calling the worker for a signed-in user. Current deployments sign and forward tenant context rather than trusting browser-provided tenant data. Do not expose this secret to clients.

Run request shape

{
  "agentId": "support",
  "input": { "customerId": "cus_123" },
  "content": [
    { "type": "text", "text": "Explain this invoice" },
    {
      "type": "image",
      "artifactId": "artifact_...",
      "mediaType": "image/png",
      "detail": "high"
    }
  ],
  "sessionId": "optional-session-id",
  "context": ["app/user/u_123"],
  "retention": {
    "mode": "result",
    "ttlSeconds": 86400,
    "artifactTtlSeconds": 3600
  }
}

input accepts a plain string, an object matching the agent schema, or rich content for compatibility. Prefer the independent ordered content array for text/image/audio messages. Content sources are url, base64, artifactId, or client-only file; raw HTTP callers cannot send a local file path.

context is a namespace grant array minted by trusted server-side code and passed to resource providers such as memory. retention defaults to the manifest policy or session. A caller can tighten a manifest default but cannot loosen it. none is synchronous-only.

Run endpoints accept the same core fields. Async runs also accept callback and webhook fields when webhook delivery is configured.

The active manifest kind selects ordinary LLM execution, transcription, image generation, or a composed workflow. No provider-specific route is required.

Run response shape

{
  "output": { "answer": "..." },
  "state": {},
  "runId": "run_...",
  "traceId": "trace_...",
  "sessionId": "session_...",
  "status": "completed",
  "requestedAgentVersion": "production",
  "resolvedAgentVersion": "2026-07-28T18:30:00.000Z",
  "provider": "openai",
  "model": "gpt-5.4-2026-07-15",
  "usage": {
    "inputTokens": 412,
    "outputTokens": 87,
    "totalTokens": 499
  },
  "finishReason": "stop",
  "responseId": "resp_...",
  "warnings": [],
  "retention": { "mode": "session" }
}

traceId and sessionId are omitted for none and result retention. runId remains a correlation id even when no durable run record is created. See Results, streaming, and errors.

Stream format

/run/stream, /runs/:id/stream, and /traces/:id/stream emit Server-Sent Events.

event: stream
data: {"type": "text-delta", "text": "Hello"}

event: stream
data: {"type": "complete", "output": "Hello, world!", "state": {...}}

Reconnect with Last-Event-ID or ?since=<seq> where supported. Servers may send keepalive comments to avoid proxy idle timeouts.

Errors

The worker returns JSON error bodies with stable codes:

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "No agent with id 'unknown'",
    "status": 404
  }
}

The clients map these to typed errors. See Hosted client → Errors.