Companion activation history

GET /api/v1/identities/{agent_handle}/companion/activations/{activation_id}/messages

Read a finite, chronological initialization snapshot for an activation UUID obtained from conversation state or a verified received webhook. This endpoint supplies retained authorized history plus exactly one sponsor trigger. It is not a live-message feed. The sponsor is the actual author of the entry marked is_trigger: true. Their qualifying authenticated group message must meet the exact bidirectional-allow requirements. Other eligible senders do not replace that author or restart the active snapshot. Current authorization still depends on the original sponsor’s rules and membership. Admin-scoped API keys and human sessions may request an activation belonging to an identity in their organization. Claimed identity-scoped keys may request only their own identity. All callers still need a currently available activation. Unclaimed keys are not supported. Authorization is checked on every page; possession of an activation ID or cursor does not grant access.

Query parameters

Parameter	Type	Default	Meaning
`limit`	integer	`100`	Entries per page, `1` through `200`.
`cursor`	string	None	Opaque `next_cursor` from this activation’s previous page, at most 1024 characters.

Response

Field	Type	Meaning
`scope_id`	UUID	Conversation-and-cohort scope.
`activation_id`	UUID	Initialization activation.
`conversation_id`	UUID	Canonical channel conversation.
`channel`	string	`mail`, `phone`, or `imessage`.
`items`	array	Ordered source entries for this page.
`history_complete`	boolean	`true` only at the end of the authorized snapshot.
`next_cursor`	string or null	Continue while non-null. The final page has `null`.
`reply_context`	object	Canonical conversation and email reply audience where applicable.
`notices`	array, optional	Advisory notices; `history_unavailable` can report earlier messages that are no longer available.

Source entry

Field	Type	Meaning
`id`	UUID	Source message ID for deduplication.
`author`	string	Message author, not necessarily the sponsor.
`sender_access`	`"direct"` or `"sponsored"`, optional	Receipt-time admission of this inbound message; absent when unknown or inapplicable, including outbound entries. Not sender trust or command permission.
`occurred_at`	timestamp	Source message time.
`text`	string	Message content; can be empty for an attachment-only message.
`historical`	boolean	Earlier context rather than a new live instruction.
`is_trigger`	boolean	Whether this is the sponsor message that activated the snapshot. Exactly one across the full snapshot.
`attachments`	object[]	Authorized attachment metadata/references, not inline attachment bodies.

See per-message sender access for semantics and legacy/system exceptions. Inline history and every paginated page use the same field. Preserve it through full snapshot loading; never default missing evidence to direct.

Reply context

Field	Type	Meaning
`channel`	string	Same channel as the snapshot.
`conversation_id`	UUID	Use this for an existing phone/iMessage conversation reply.
`reply_to_message_id`	UUID or null	Stored email parent message ID for reply-all, not its RFC `Message-ID`.
`to` / `cc`	string[] or null	Exact permitted email audience. Not a grant for a raw recipient-only send.

Phone/iMessage reply contexts can omit or return null for email-specific fields. Keep the context associated with the current activation and turn; do not infer a private reply target from the last author.

Read a page

These SDK examples assume an authenticated client and an activation ID from a verified event or state response. They fetch one page, not a complete initialization.

page = client.companion.activation_messages("xyz", activation_id, limit=100)
print(page.history_complete, page.next_cursor)

const page = await client.companion.activationMessages("xyz", activationId, { limit: 100 });
console.log(page.historyComplete, page.nextCursor);

use inkbox::companion::CompanionActivationOptions;
use inkbox::Inkbox;

fn page(client: &Inkbox, activation_id: &str) -> inkbox::Result<()> {
    let page = client.companion().activation_messages(
        "xyz", activation_id, &CompanionActivationOptions::default(),
    )?;
    println!("{} {:?}", page.history_complete, page.next_cursor);
    Ok(())
}

inkbox identity companion history xyz "$ACTIVATION_ID" --limit 100 --json
inkbox identity companion history xyz "$ACTIVATION_ID" --limit 100 --cursor "$NEXT_CURSOR" --json

For manual pagination, pass the returned next_cursor as Python cursor, TypeScript cursor, or Rust CompanionActivationOptions.cursor on the next request. Continue until history_complete is true and the cursor is null. Retain the entries from every page before constructing context. For an agent receiver, prefer the complete initialization helpers, which retain entries, validate consistent scope and cursor progress, deduplicate sources, enforce byte/page bounds, and revalidate before returning. CLI JSON uses historyComplete, nextCursor, and replyContext; raw API JSON uses snake_case.

Initialization rules

Finish every page before submitting one combined agent input. Never wake the host once per page, source message, or attachment.
Preserve authors, times, per-message sender access, historical markers, attachment references, notices, and the trigger exactly once. Historical commands are context, not new control messages.
Buffer live events during initialization and persist a durable activation/host-turn checkpoint before releasing them. Recover missing initialization even when the first event observed is live.
The snapshot contains only retained authorized messages delivered to this identity in this scope. Completion does not promise history from before the agent joined or messages that are no longer available.
New arrivals do not extend this snapshot. Read them through received events or ordinary channel history, deduplicating against initialized source IDs.
Recheck current authorization before a delayed submission. If access ends, discard pending Companion-only context rather than submitting a partial initialization.

An API page supports up to 32 MiB of message content. A 413 requires a smaller limit; an individually oversized message still fails. SDK initialization has a separate default 8 MiB total bound and does not automatically reduce the page size after 413. Use the page API for a custom bounded, lossless context-loading path.

Errors

Status	Meaning
`403`	The caller is not authorized for the requested identity.
`404`	The activation is unavailable to this identity/caller.
`409`	Initialization is not currently available, a required message is unavailable, or history changed. Refresh state before retrying.
`413`	A page or individual message is too large. No truncated successful snapshot is returned.
`422`	Invalid activation ID, limit, or cursor, including a cursor from another activation.
`503`	Message content or current group membership is temporarily unavailable. Retry later without submitting partial context.

See webhook recovery and response notices. Notices never replace error handling or grant permission.

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Companion activation history

Query parameters

Response

Source entry

Reply context

Read a page

Initialization rules

Errors

​Query parameters

​Response

​Source entry

​Reply context

​Read a page

​Initialization rules

​Errors

Query parameters

Response

Source entry

Reply context

Read a page

Initialization rules

Errors