Create a durable activation or review observer

POST

/v1/agent-tasks

• Production
• Local

Uses the existing activation or review attention state without verifying, acknowledging, revising, approving or sending. A worker is not created. Status polls reconcile the durable source with fresh authorization. Optional connection selection is frozen at creation. Agent keys retain their existing project ceiling; query selectors never widen it.

Authorizations

• AgentKey

Parameters

Query Parameters

project_id

string

<= 256 characters

Optional review connection selection within the current grant. Not accepted for activation.

org_id

string

<= 256 characters

Optional review connection organization selection. Not accepted for activation.

Request Body ^required

Create an observation only. Activation requires signup:verify and excludes review_id and limit. Review requires mailbox:read. Assistant-profile connections may observe reviews only. No credentials are retained.

object

kind

required

string

Allowed values: activation review

review_id

Optional review filter; omit to observe the calling composer’s accessible queue.

string

<= 256 characters

limit

Review event page size; omit for activation.

integer

default: 100 >= 1 <= 100

ttl_seconds

Observer lifetime; expiration never cancels a review or extends an activation reservation.

integer

default: 3600 >= 60 <= 86400

client_id

Retry key within this credential family. Reusing it with different selectors or TTL returns 409.

string

<= 128 characters

Responses

200

Observer created or idempotently resumed; may already be completed.

Durable observer bound to the exact connection grant or agent key and its immutable capability profile and selection. Each request rechecks current access. Completion means an observation is available, not that an account was verified or email was sent. Terminal results are immutable. Up to 100 unexpired handles, including completed handles, are retained per owner.

object

id

required

string

kind

required

string

Allowed values: activation review

status

required

string

Allowed values: working completed cancelled

created_at

required

string format: date-time

last_updated_at

required

string format: date-time

expires_at

required

string format: date-time

poll_interval_ms

required

Suggested status-poll interval in milliseconds; normal polling needs no model invocation.

integer

>= 1

result

One of:

object

object

agent_id

required

string

address

required

string format: email

human_email

required

string format: email

created_ms

required

integer format: int64

expires_ms

required

integer format: int64

revision

required

integer format: int64

state

required

string

Allowed values: pending proven activated expired

object

Durable attention for reviews the caller may access, including feedback and rule/category changes. Omit review_id for one shared wait. Reconnect with the same identity to replay unhandled events; waiting never acknowledges work. Events are FIFO per review, with persisted cursors. Delegated observations survive composer acknowledgements.

object

pending_reviews

Remaining active reviews within this wait’s authorized resource and optional review_id boundary; legacy keys retain their composer ceiling. Included on an empty wait.

integer

events

required

Array<object>

One durable review nudge (ndg_…) as drained from the authoritative liveness queue (spec §11). seq is the per-review monotonic ordinal the ack cursor advances against (0 for a broadcast nudge). Opaque typed ids only (D10).

object

seq

required

integer

id

required

string

reason

required

The work-item kind. sent / send_failed / cancelled are TERMINAL: the LAST event a review ever produces is one of these; ack it and stop polling that review. (Almost every review emits exactly one; a failed send the agent then closes out emits send_failed and then cancelled.) sent covers both delivery flavors; payload.state distinguishes sent from auto_sent. approved and staleness are RESERVED and never emitted (kept so the enum is never narrowed). Treat an unrecognized reason as ack-and-ignore: this enum is additive across 0.x releases.

string

Allowed values: redraft_requested feedback_added recheck_category staleness approved rejected front_run_next rule_changed propagate_general_rule sent send_failed cancelled

review_id

string

category_id

string

payload

object

key

additional properties

any

created_at

required

string format: date-time

cursors

Array<object>

The agent’s per-(agent, review) ack frontier; its strict-FIFO position for one review.

object

review_id

required

string

last_acked_seq

required

integer

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

404

Resource not found.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

409

Retry key has different immutable parameters.

413

Observed result exceeds 1 MiB; use a narrower review selector or limit.

429

Per-owner observer retention or request rate limit reached; honor Retry-After.

503

Durable observer storage is unavailable.