Capability API recipes

These examples use current capability names and versions for documentation release 2026-08-11.3. Fetch /docs/openapi.json or /docs/reference/capabilities.md before implementation and treat the generated schema as authoritative.

Safe shell setup

Store the bearer token outside source code:

export DOMINO_TOKEN='YOUR_TOKEN_FROM_AGENT_ACCESS'
export DOMINO_API='https://letsdomino.io/api/v2'

Do not paste the real token into an AI conversation or commit it to a shell script.

Shared headers:

-H "Authorization: Bearer $DOMINO_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Domino-Client: my-integration"

Writes additionally require a caller-stable Idempotency-Key header.

Read calendar connection status

curl -sS "$DOMINO_API/capabilities/calendar.status.get" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Domino-Client: my-integration" \
  -d '{"version":"1.0","input":{}}'

Check status, facts, disclosures, and management resources. The API can report connection state; Google OAuth and calendar-feed management remain web experiences.

List people

curl -sS "$DOMINO_API/capabilities/relationships.people.query" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"version":"1.0","input":{"classification":"all","limit":25}}'

Use returned opaque person handles for later operations. For another page, pass the returned snapshot handle and cursor exactly. Never execute an internal numeric ID.

Create an Ideas List

Read first with ideas.lists.query@1.0 to avoid accidental duplicates. Then create:

curl -sS "$DOMINO_API/capabilities/ideas.lists.create" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: ideas-list-create-20260811-001" \
  -d '{
    "version":"2.0",
    "input":{
      "name":"North Side Weekends",
      "person_handles":["PERSON_HANDLE_FROM_DOMINO"],
      "neighborhood_names":["Lincoln Square"],
      "activity_names":["free things to do"],
      "directions":["Prefer places reachable by transit"],
      "apply_matching_likes":true
    }
  }'

Reuse the idempotency key only for an exact transport retry. If the user changes the name or defaults, use a new key.

Search for a known object

ideas.search requires non-empty query or q:

curl -sS "$DOMINO_API/capabilities/ideas.search" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "version":"1.0",
    "input":{
      "query":"Lula Cafe",
      "scopes":["places","ideas"],
      "limit":10
    }
  }'

Use recommendations rather than lexical search for open-ended “what should we do?” requests.

Get recommendations and continue a collection

Call ideas.recommendations.get@2.1 with explicit people, required activities, neighborhoods, and user-supplied timing. Preserve qualitative modifiers in preference_terms rather than turning them into hard search terms.

If the outcome contains has_more and next_cursor, call the same capability with the returned cursor exactly. Do not reconstruct the prior constraints or rediscover solely to rebuild numbered options.

Capture an idea and poll

Submit:

curl -sS "$DOMINO_API/capabilities/ideas.capture" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: capture-20260811-001" \
  -d '{
    "version":"2.0",
    "input":{
      "source_url":"https://example.com/place",
      "target_ideas_list_handle":"IDEAS_LIST_HANDLE_FROM_DOMINO"
    }
  }'

If the result is accepted, retain the returned capture public identifier and polling cursor. Observe it with ideas.capture.get@1.0 or the returned status action. Do not create a second capture while the first is running.

If status is needs_input, present the exact question, obtain an answer, then make a new intentional call using the protected capture reference and current schema. Never guess identity details.

Find availability

curl -sS "$DOMINO_API/capabilities/availability.query" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "version":"2.0",
    "input":{
      "when_preset":"this-weekend",
      "daily_start":"18:00",
      "daily_end":"22:00",
      "person_handles":["PERSON_HANDLE_FROM_DOMINO"],
      "limit":10
    }
  }'

Availability is privacy-safe free/busy output. Preserve unknown, partial, stale, and not-shared disclosures. Never infer event content.

Create and prepare an invitation

1. Create the private draft

Use a candidate or place handle returned by authorized discovery:

curl -sS "$DOMINO_API/capabilities/plans.draft.create" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: plan-draft-20260811-001" \
  -d '{
    "version":"2.0",
    "input":{
      "candidate_id":"CANDIDATE_HANDLE_FROM_DOMINO",
      "scheduled_at":"2026-08-20T19:00:00-05:00",
      "rsvp_deadline":"2026-08-18T12:00:00-05:00",
      "capacity_min":2,
      "audience_selection":{
        "person_handles":["PERSON_HANDLE_FROM_DOMINO"]
      }
    }
  }'

This is a private write. Nobody has been invited.

2. Preview the draft

Call plans.draft.preview@2.0 with the returned plan handle and a new idempotency key. Present all facts, recipients, and delivery disclosures.

3. Prepare sending

curl -sS "$DOMINO_API/capabilities/plans.prepare_send" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: plan-prepare-20260811-001" \
  -d '{
    "version":"2.0",
    "input":{
      "plan_handle":"PLAN_HANDLE_FROM_DOMINO",
      "action":"send_invites",
      "send_person_handles":["PERSON_HANDLE_FROM_DOMINO"]
    }
  }'

Present the exact prepared action and stop. Do not commit based on the original draft request.

4. Commit after later explicit approval

Use the exact prepared action handle with actions.commit@1.0 from the same token/principal:

curl -sS "$DOMINO_API/capabilities/actions.commit" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: plan-commit-20260811-001" \
  -d '{
    "version":"1.0",
    "input":{"action_handle":"PREPARED_ACTION_HANDLE_FROM_DOMINO"}
  }'

Report only the terminal effects.confirmed. Preserve recipient-specific manual-share boundaries.

Inspect, edit, or cancel an active plan

1. Use plans.query@2.0.
2. Inspect the selected returned plan with plans.get@2.0.
3. Use plans.update.prepare@2.0 or plans.cancel.prepare@2.0.
4. Present the exact preparation.
5. Obtain later approval.
6. Commit with actions.commit.

On revision, recipient, or delivery-eligibility conflict, re-read current state and prepare again. Never commit a stale action handle.

List invitations and RSVP

List current invitations with invites.list@1.0, optionally filtering pending, accepted, declined, or removed. Resolve the exact invite handle, then write the response:

curl -sS "$DOMINO_API/capabilities/invites.rsvp" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: invite-rsvp-20260811-001" \
  -d '{
    "version":"2.0",
    "input":{
      "invite_handle":"INVITE_HANDLE_FROM_DOMINO",
      "response":"accepted"
    }
  }'

Confirm the returned invitation state.

Assistant API conversation

For natural-language interpretation, call:

curl -sS "$DOMINO_API/assistant/turns" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "message":"Find coffee with Andrew in the West Loop",
    "request_key":"turn-001",
    "channel_identity":"conversation-123"
  }'

Reuse a stable channel_identity for the same durable conversation. Use a unique request key for each intentional turn.

If the Assistant API returns a prepared action, ordinary text such as SEND cannot commit it. Present it, obtain later approval, then call:

export ACTION_HANDLE='PREPARED_ACTION_HANDLE_FROM_DOMINO'

curl -sS -X POST "$DOMINO_API/assistant/prepared-actions/$ACTION_HANDLE/commit" \
  -H "Authorization: Bearer $DOMINO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "request_key":"turn-002-commit",
    "channel_identity":"conversation-123"
  }'

Use the same channel identity as the preparation and a unique request_key.

Status and error handling

• completed: present terminal confirmed facts.
• unchanged: explain that no new change was needed.
• accepted: poll the returned execution or status action.
• needs_input: obtain the missing decision and use a new intentional request.
• failed: follow normalized recovery guidance.
• HTTP 409: inspect the conflict; do not blindly retry changed input under the same idempotency key.
• HTTP 429: respect Retry-After.

LLM and integration guidance

• Never embed secrets or internal IDs in examples shown to end users.
• Validate against generated schemas in CI.
• Log correlation and execution references securely, but base user-visible claims only on the canonical typed outcome.
• Separate plan drafting, preparation, approval, commit, and confirmed delivery in both code and UI.