Browse documentation
Agent-first documentation · 2026-09-08.1 · Updated 2026-09-08 View as Markdown

Domino Capability API guide

Domino provides a deterministic Capability API for strict callers and an Assistant API for clients that want Domino's hosted natural-language runtime.

Authentication and abilities

Create a static bearer token in Domino's Agent Access settings. claude.ai OAuth access tokens are bound to the MCP resource and are not Capability API or Assistant API credentials. Grant only the required abilities:

  • planning:read;
  • planning:write;
  • planning:rsvp;
  • planning:commit.

Send the token using:

Authorization: Bearer YOUR_TOKEN

Never place the token in URLs, documentation prompts, logs, or user-visible assistant replies.

Use Create, test, rotate, and revoke Agent Access tokens for exact web instructions and least-privilege examples.

Discovery access is open to authenticated Capability API callers for ideas.discover, ideas.discover.refine, ideas.discover.save, and owned Discovery status reads, subject to token abilities, ownership, usage limits, and the global pause switch. Other beta API operations, including the Assistant API and downstream Plan operations, retain their existing access restrictions and may return 403. Discovery eligibility does not grant access to every step of a combined workflow; follow returned outcomes and Web handoffs. See current surface support.

Capability API

Execute a current capability using:

POST /api/v2/capabilities/{capability}

Recommended request envelope:

{
  "version": "CURRENT_CAPABILITY_VERSION",
  "input": {
    "field": "value"
  }
}

Fetch the generated OpenAPI document or generated capability reference for exact names and schemas.

Request headers

Use:

Content-Type: application/json
Accept: application/json
X-Domino-Client: your-client-name
X-Request-Id: optional-correlation-id

Writes and external-effect commits require:

Idempotency-Key: caller-stable-intent-key

Reuse the same key only for an exact replay of the same intended mutation. Use a new key for intentionally changed input.

Typed outcome contract

Capability responses use:

domino.capability-outcome.v1

Important fields include:

  • status;
  • outcome.kind;
  • outcome.facts;
  • outcome.resources;
  • outcome.collection;
  • outcome.disclosures;
  • outcome.next_actions;
  • outcome.confirmation;
  • effects.confirmed and effects.unconfirmed;
  • normalized errors;
  • execution_id and replayed when applicable.

Use the structured fields for control flow. outcome.fallback_text is safe presentation fallback, not a replacement for checking status and confirmed effects.

For asynchronous singular capture, clarification continuation, and generation-safe multi-item roundups, read Idea capture and roundup workflows with the Capability API.

Status handling

  • completed — the capability reached its terminal result.
  • unchanged — the requested state already held; no new effect was needed.
  • accepted — work started but is not terminal. Follow the returned next action or poll.
  • needs_input — obtain the missing information and make an intentional follow-up request.
  • failed — inspect normalized errors and recovery guidance.

Poll a returned execution when instructed:

GET /api/v2/capability-executions/{executionId}

Do not resubmit a new write merely because accepted work has not finished.

Prepared actions and commit

Direct consequential capabilities cannot be called through the v2 endpoint. They must use the centralized prepared-action protocol:

  1. Create or update the private draft.
  2. Invoke the relevant prepare capability.
  3. Present the exact action, disclosures, recipients, and confirmation state.
  4. Stop and obtain later explicit approval.
  5. Commit actions.commit with the prepared handle from the same API token/principal and a stable idempotency key.

For the hosted Assistant API, commit a returned prepared handle through:

POST /api/v2/assistant/prepared-actions/{handle}/commit

with a unique request_key and the same channel identity when one was supplied.

Assistant API

Use Domino's hosted conversational runtime through:

POST /api/v2/assistant/turns

Example:

{
  "message": "Find coffee with Andrew in the West Loop",
  "request_key": "turn-001",
  "channel_identity": "optional-stable-conversation-key"
}

The Assistant API owns natural-language interpretation and durable conversation state. The Capability API does not.

HTTP recovery

  • 401: authenticate again.
  • 403: the token lacks the required ability or access.
  • 404: capability or current authorized reference is unavailable.
  • 409: conflict, in-progress execution, reference revision, or confirmation safety issue.
  • 422: the structured input is invalid.
  • 429: wait for Retry-After.
  • 503: a required dependency is unavailable; retry according to returned guidance.

LLM and integration guidance

  • Never guess request fields. Fetch the generated schema.
  • Never send numeric internal resource IDs when the public schema expects handles or selectors.
  • Never claim an effect from HTTP success alone; inspect status and effects.confirmed.
  • Keep Capability API and Assistant API reasoning boundaries distinct.
  • Use Capability API recipes for complete request sequences, polling, invitation preparation, RSVP, and Assistant API commit behavior.

Retained Discovery result to private Plan

When the connected runtime returns selection_contract: "domino.discovery-selection.v1", use its returned inputs for the whole handoff. These fields are additive; deployments without this contract need their returned Web handoff. Discovery enablement and token abilities still apply separately.

  1. Read GET /api/v2/discovery-runs/{run_handle} with the authenticated owner's returned run handle. Choose from choices, inspecting actionability, evidence, requirements and expiry. candidate_handle identifies corpus research; it is not a Plan selection.
  2. After an explicit Save request, copy choice.actions.save into POST /api/v2/capabilities/{capability} with { "version": action.version, "input": action.input } and a stable Idempotency-Key. For several choices, use exactly their returned snapshot_ref values in candidate_refs, with one common run/contract/version envelope. Read-only selections are rejected together; never silently narrow a set.
  3. Save returns outcome.facts.ideas_list and outcome.facts.readback. Execute that readback descriptor to retrieve the persisted list. A saved item's actions.plan uses the returned candidate_id and idea_list_handle and keeps the saved research source after conversational expiry.
  4. After an explicit Plan request, copy the selected actions.plan into the same capability request envelope. Direct result entry includes research_selection; keep all its fields. The result includes a private Plan, draft_created, and a plans.status.get descriptor in outcome.next_actions. Read it in a fresh request to verify the pinned research_source, research_requirements and actual scheduled_at (which may be null).

A retry with the same key and input returns the stored receipt; changed input needs a new key. A new write from an expired, superseded or stale selection fails without partial effects. Reopening an authorized saved idea or existing private Plan preserves its original research and later Plan edits. Recording, Save and private Plan creation do not invite anyone, verify venue availability or make an outside commitment.