# 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:

```http
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](/docs/agent-access/create-and-manage-tokens.md) for exact web instructions and least-privilege examples.

## Capability API

Execute a current capability using:

```text
POST /api/v2/capabilities/{capability}
```

Recommended request envelope:

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

Fetch [the generated OpenAPI document](/docs/openapi.json) or [generated capability reference](/docs/reference/capabilities.md) for exact names and schemas.

## Request headers

Use:

```http
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:

```http
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:

```text
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:

```text
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:

```text
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:

```text
POST /api/v2/assistant/turns
```

Example:

```json
{
  "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](/docs/api/task-recipes.md) for complete request sequences, polling, invitation preparation, RSVP, and Assistant API commit behavior.