Documentation
OpenAPIAgent index

API and SDK

The customer API is organization-scoped and served from https://www.dharma-ai.io. Customer credentials authenticate only to Dharma. Responses never return GCP identities, provider keys, service-account keys, private worker addresses, or unrestricted local paths.

Authoritative contract

  • Agent Fabric OpenAPI 3.1
  • TypeScript client: @dharma-ai-labs/agent-fabric-sdk
  • Python client: dharma-agent-fabric-sdk
  • CLI: @dharma-ai-labs/agent-fabric

The OpenAPI contract is authoritative for paths, payload schemas, status codes, and operation IDs. Examples in this guide explain the workflow but do not replace schema validation.

Authentication

Authorization: Bearer <organization-token>

Create tokens in Portal -> Developer API -> Keys. Select the minimum scopes needed. A token is bound to one organization and must not be reused across tenants.

| Scope | Purpose | | --- | --- | | agents:read | Agents, endpoints, tasks, instructions, control-agent history | | agents:run | Agent runs, tasks, handoffs, control-agent messages | | evals:read | Evaluations, contracts, Failure Atlas | | evals:run | Analysis windows and evaluation campaigns | | traces:read | Trajectories, traces, bounded evidence requests | | skills:read | Remediation and signed release state | | skills:write | GitHub writes, release transitions, rollout, rollback | | usage:read | Customer-visible usage and credits |

Idempotency

Every intended mutation uses an Idempotency-Key header between 8 and 200 characters. Reuse the same key only when retrying the same semantic operation.

Idempotency-Key: run-order-1847-attempt-1

Asynchronous work

Run and evaluation submissions return 202 Accepted when durable work has been queued. Store the returned identifier, poll its status resource, and consume ordered events. Retry reads freely; retry writes only with the original idempotency key.

Error envelope

Errors use a stable non-enumerating shape:

{
  "ok": false,
  "error": {
    "code": "stable_machine_code",
    "message": "Actionable customer-safe explanation",
    "correlationId": "audit-correlation-id"
  }
}

Do not parse human messages for control flow. Log the correlation ID without recording the bearer token or request content.

Main API groups

  • onboarding, GitHub access, devices, instructions, repository agents, workspaces, and endpoints;
  • evidence policy, trajectories, evaluations, evaluation contracts, and Failure Atlas;
  • remediation campaigns, action decisions, signed tasks, A2A handoffs, skills, and usage;
  • control-agent sessions, messages, events, approvals, and rejections;
  • managed agents, asynchronous runs, evaluation campaigns, traces, and remediation candidates;
  • GCP Vertex BYOK configuration and verification.

Open the full OpenAPI JSON for exact request schemas.

Browser boundary

Public browser clients call Dharma APIs only. Long-running execution, model providers, GCP resources, relay services, and internal workers stay behind the server control plane. Never embed an organization token in frontend JavaScript.