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 bearer token in Domino's Agent Access settings. 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.

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.

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.