Documentation
OpenAPIAgent index

Agent integration reference

Base URL: https://www.dharma-ai.io

Evaluation Runs OpenAPI: https://www.dharma-ai.io/api/v1/evaluation-runs/openapi.json

Agent Fabric OpenAPI: https://www.dharma-ai.io/api/v1/agent-fabric/openapi.json

Agent Fabric CLI: npm install --global @dharma-ai-labs/agent-fabric@0.2.50

Authentication: organization bearer token for API reads and scoped mutations; browser-confirmed Ed25519 device enrollment for local CLI; authenticated Clerk organization session for human approvals.

Required mutation header: Idempotency-Key with 8-200 characters.

Select the product first

  • For controlled testing, paired runs, scorer evidence, Failure Atlas, remediation candidates, held-out proof, and reports, use Evaluation Runs and follow https://www.dharma-ai.io/docs/evaluations.
  • For repository enrollment, local coding agents, relay, signed tasks, Agent Fabric trajectories, skills, rollout, and rollback receipts, use Agent Fabric.
  • Do not run Agent Fabric login, enrollment, workspace, relay, task, or skill commands during an Evaluation Runs workflow.
  • Existing-runtime evaluation is provider-preserving by default. Production migration requires a separate explicit decision, fallback, smoke test, canary, and rollback.

Safe Agent Fabric bootstrap

  1. Ask the human to open https://www.dharma-ai.io/portal?section=agent-fabric&tab=Instructions.
  2. Use only the organization-specific command they provide.
  3. Run dharma login; wait for browser approval.
  4. Discover only the human-approved root.
  5. Present repositories before connecting them.
  6. Connect one selected repository and run provider verification.
  7. Preview evidence before synchronization.
  8. Do not place tokens, local paths, raw evidence, or provider credentials in chat.

Tool selection

  • inspect state: read-scoped API, CLI status command, or control-agent read;
  • submit managed work: asynchronous agent-run API with agents:run;
  • run evaluation: scoped analysis or managed campaign with evals:run;
  • inspect failures: Failure Atlas with evals:read;
  • release or roll back: remediation/skills API with skills:write plus required human approval;
  • ask another agent: signed task or structured A2A handoff with agents:run;
  • inspect cost: usage API with usage:read.

Do not infer

  • organization creation does not imply runtime readiness;
  • provider discovery does not imply task, activation, or rollback support;
  • 202 Accepted does not imply completion;
  • metadata does not prove semantic correctness;
  • a generated remediation is not an approved improvement;
  • a copied approval URL is not approval authority.

Error handling

Branch on HTTP status and error.code. Preserve correlationId. Retry reads with bounded backoff. Retry mutations only with the original idempotency key. Fail closed on expired authority, missing scope, stale evidence, unsupported provider, unavailable judge, budget rejection, or unknown rollout state.