Connect over REST

The versioned REST base path is /api/v1. Examples below assume:

export ALCARTA_URL=https://gateway.example
export ALCARTA_TOKEN='token shown once'

Discover identity and permissions

curl --fail-with-body \
  --header "Authorization: Bearer $ALCARTA_TOKEN" \
  "$ALCARTA_URL/api/v1/identity"

Use the returned mailbox IDs, folder roles, effective tools, and limits rather than hard-coding what a token should be able to do.

Read a page of messages

curl --fail-with-body --get \
  --header "Authorization: Bearer $ALCARTA_TOKEN" \
  --data-urlencode 'folder=inbox' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'include_body=none' \
  "$ALCARTA_URL/api/v1/mailboxes/$MAILBOX_ID/messages"

Collections use opaque forward-only cursors. Send page.next_cursor back as cursor; do not decode or edit it. Message IDs are also opaque and become stale when a message moves.

Use the declarative query route

The declarative REST route uses a dotted URL segment:

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $ALCARTA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "select": {
      "filter": {"seen": false, "subject_contains": "invoice"},
      "order_by": "received_desc",
      "limit": 10
    },
    "view": "summary"
  }' \
  "$ALCARTA_URL/api/v1/mailboxes/$MAILBOX_ID/email.query"

File an action safely

Writes that require idempotency use the Idempotency-Key header. Reuse a key only for the exact same operation and body.

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $ALCARTA_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: triage-$JOB_ID-$MESSAGE_ID" \
  --data "{
    \"operation\": {
      \"type\": \"message_actions\",
      \"select\": {\"message_ids\": [\"$MESSAGE_ID\"]},
      \"actions\": [{\"type\": \"archive\"}]
    },
    \"authorization\": {
      \"mode\": \"execute_or_request_approval\",
      \"reason\": \"Resolved support thread\"
    },
    \"cardinality\": {\"min\": 1, \"max\": 1}
  }" \
  "$ALCARTA_URL/api/v1/mailboxes/$MAILBOX_ID/email.act"

The response status is completed, pending_commit, awaiting_approval, or preview. Branch on that field. Do not assume a call created an approval or executed directly.

Response and error shapes

A single resource is returned directly. A collection is { "items": [], "page": { … } }. Errors use:

{
  "error": {
    "code": "insufficient_scope",
    "status": 403,
    "message": "…",
    "request_id": "req_…",
    "retryable": false,
    "details": {}
  }
}

Use error.code, retryable, retry_after_seconds when present, and request_id. Do not branch on prose in message.