Skip to content
Olivares AI docs

Lists the handoff offers addressed to the authenticated recipient without opening their content.

GET
/v1/m/sessions/inbox/handoffs
 
curl --request GET \
  --url 'https://example.com/v1/m/sessions/inbox/handoffs?workspace_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&state=offered&limit=50' \
  --header 'Authorization: Bearer <token>'

Lists the handoff offers addressed to the authenticated recipient without opening their content.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “ Header Parameters ”
X-Olivares-Tenant
string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Query Parameters

Section titled “ Query Parameters ”
workspace_id
required
string format: uuid
/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/

Canonical stored workspace UUID selected for this personal collection; it is revalidated and never grants authority.

state
string
default: offered
Allowed values: offered accepted rejected withdrawn expired

Exactly one Handoff state to list: offered (default), accepted, rejected, withdrawn or expired. Repeated, unknown or comma-joined selectors are refused.

continuation
string
>= 1 characters <= 2048 characters

Authenticated h3n1 continuation returned by the preceding page, anchored to the last offer it returned. Its own token family and filter domain: an inbox c2n1 or catalog c3n1 token is refused, and so is a token minted for another state filter. Its claims are base64-readable and MAC-authenticated, not encrypted, and it conveys no authority.

limit
integer
default: 50 >= 1 <= 200

Visible page size from 1 through 200; default 50.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Visible page of handoff offers addressed to the authenticated recipient, without content

Media type application/json
object
continuation

Authenticated h3n1 token anchored to the last returned offer; present only when has_more is true.

string
has_more
required

True exactly when a visible limit+1th offer was authorized in the same bound transaction; never a hidden-row fact and never a total.

boolean
items
required
Array<object>
object
carrier
required
object
channel_id
required
string format: uuid
delivery_id
required
string format: uuid
delivery_version
required
integer format: int64
message_id
required
string format: uuid
deadline_elapsed
required

Response window measured against database time. A row may still be persisted as offered after its deadline; this read never runs the reaper.

boolean
handoff
required
object
ack_deadline
required
string format: date-time
created_at
required
string format: date-time
etag
required
string
/^\"v[0-9]+\"$/
from
required
object
kind
required
string
Allowed values: user agent session
ref
required
string
>= 1 characters <= 1024 characters
id
required
string format: uuid
state
required
string
Allowed values: offered accepted rejected withdrawn expired
terminal_at
Any of:
string format: date-time
terminal_code
string
to
required
object
kind
required
string
Allowed values: user agent session
ref
required
string
>= 1 characters <= 1024 characters
version
required
integer format: int64
observed_at
required
string format: date-time
work_item
required
object
id
required
string format: uuid
presentation
required
string
Allowed values: handoff_context
Example 
{
  "items": [
    {
      "handoff": {
        "from": {
          "kind": "user"
        },
        "state": "offered",
        "to": {
          "kind": "user"
        }
      },
      "work_item": {
        "presentation": "handoff_context"
      }
    }
  ]
}

400

Section titled “ 400 ”

Bad request

Media type application/json
object
Example generated 
{}

401

Section titled “ 401 ”

Unauthenticated

Media type application/json
object
Example generated 
{}

403

Section titled “ 403 ”

Forbidden

Media type application/json
object
Example generated 
{}

404

Section titled “ 404 ”

Not found

Media type application/json
object
Example generated 
{}

429

Section titled “ 429 ”

Rate limited

Media type application/json
object
Example generated 
{}

503

Section titled “ 503 ”

Current authority, custody or store evidence is unavailable; or, with code commit_outcome_unknown, the write was issued and its outcome was never learned, so it may be durable and must not be retried automatically

Media type application/json
object
Example generated 
{}