Skip to content
shiftagent Integration API

List conversations by user or by tenant.

GET
/conversations
 
curl --request GET \
  --url 'https://shiftagent.example.com/conversations?limit=20&status=active' \
  --header 'Authorization: Bearer <token>'

Service-principal listing: exactly one of ?user_id= or ?tenant_id= is required (400 otherwise — neither or both). Sorted by last_message_at descending. Under a platformJwt, only ?user_id= matching the token’s user is permitted (403 insufficient-scope otherwise).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
limit
integer
default: 20 >= 1 <= 100

Page size (1–100).

starting_after
string

Cursor: return items after this object ID (forward pagination). Use the id of the last item of the previous page.

ending_before
string

Cursor: return items before this object ID (backward pagination). Mutually exclusive with starting_after.

user_id
string
/^usr_[A-Za-z0-9]+$/

List one user’s conversations. Mutually exclusive with tenant_id.

tenant_id
string
/^tnt_[A-Za-z0-9]+$/

List a whole tenant’s conversations. Mutually exclusive with user_id.

status
string
Allowed values: active archived

Filter by conversation status.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A page of conversations.

Media type application/json
object
object
required

Envelope discriminator.

string
Allowed value: list
data
required

The page of items.

Array
has_more
required

Whether more items exist beyond this page.

boolean
next_cursor

Opaque cursor for the next page (pass as starting_after). Null when has_more is false.

string | null
data
required
Array<object>

An agent conversation owned by a user within a tenant. Snapshots its resolution context at creation and carries live runtime state.

object
object
required
string
Allowed value: conversation
id
required
string
/^con_[A-Za-z0-9]+$/
tenant_id
required
string
/^tnt_[A-Za-z0-9]+$/
user_id
required
string
/^usr_[A-Za-z0-9]+$/
title
required

Display title; auto-derivable from the first message.

string | null
<= 255 characters
status
required

Archived conversations keep readable history but reject message writes with 409 conversation-archived.

string
Allowed values: active archived
repository_id
required

Conversation-level repository override in the cascade.

string | null
/^rep_[A-Za-z0-9]+$/
context
required

Resolution snapshot taken at conversation creation (user → role → repository → skills) — makes history self-explaining even after roles or repositories change.

object
role_id
required

The role the conversation was resolved under.

string
/^rol_[A-Za-z0-9]+$/
repository_id
required

The effective repository at creation.

string
/^rep_[A-Za-z0-9]+$/
skill_ids
required

The effective skills at creation.

Array<string>
selected_skill_ids
required

Optional narrowing within context.skill_ids; null means no narrowing.

Array<string> | null
runtime
required

Runtime placement state of a conversation. agent_type selects the agent runtime behind the platform’s runtime abstraction — each type runs in its own isolated sandbox.

object
agent_type
required

Agent runtime — open enum so new runtimes are non-breaking. Known values: claude-agent-sdk, codex, deepagent. Defaults from tenant settings. Immutable after creation.

string
mode
required

pooled — each message claims a warm-pool sandbox; sticky — a dedicated sandbox is leased for sticky_ttl_seconds (refreshed per message).

string
Allowed values: sticky pooled
sticky_ttl_seconds
required

Lease TTL; null for pooled conversations.

integer | null
sandbox_state
required

warm — no dedicated sandbox held (pooled, or sticky before first message); active — sticky lease held; expired — sticky lease lapsed (next message re-acquires, subject to capacity).

string
Allowed values: warm active expired
expires_at
required

Sticky lease expiry; null for pooled conversations.

string | null format: date-time
filler
required
One of:

Filler-agent enablement. Cascade: tenant settings → conversation → message; most specific wins. When enabled, filler output arrives as content_delta events flagged data.filler: true.

object
enabled
required

Whether the low-latency filler agent runs for this scope.

boolean
storage
required

S3-style storage bucket attached to a user or conversation. Platform-assigned automatically at creation; host-owned buckets can be linked via update (provider: "external").

object
provider
required

platform — bucket provisioned and owned by the deployment; external — host-linked BYO bucket.

string
Allowed values: platform external
bucket_uri
required

S3-style URI of the bucket root (e.g. s3://bucket/prefix).

string
message_count
required

Persisted message count (all roles).

integer
last_message_at
required

Timestamp of the newest message; null when empty.

string | null format: date-time
metadata
required

Free-form string key–value map for host/adapter bookkeeping (e.g. a host-side reference ID). Max 50 keys; values max 500 chars. Replaced wholesale when provided in updates.

object
<= 50 properties
key
additional properties
string
<= 500 characters
created_at
required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time
updated_at
required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time
Example 
{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "status": "active",
      "runtime": {
        "mode": "sticky",
        "sandbox_state": "warm"
      },
      "storage": {
        "provider": "platform"
      }
    }
  ]
}

400

Section titled “400 ”

Bad request — malformed body/parameters or an invalid parameter combination (e.g. neither or both of user_id/tenant_id on listConversations, or both pagination cursors).

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples
Example bad_request

Invalid parameter combination

{
  "type": "https://shiftagent.example.com/problems/validation-error",
  "title": "Invalid request",
  "status": 400,
  "detail": "Exactly one of user_id or tenant_id is required.",
  "request_id": "req_01hzx8bad001"
}

401

Section titled “401 ”

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples
Example unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}

403

Section titled “403 ”

Forbidden — tenant-suspended (writes to a suspended tenant), insufficient-scope (key/token lacks the scope or a platform JWT reaches beyond its user), or approval-signature-invalid (approval assertion failed verification).

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples

Suspended tenant rejects conversation writes

{
  "type": "https://shiftagent.example.com/problems/tenant-suspended",
  "title": "Tenant suspended",
  "status": 403,
  "detail": "Tenant tnt_01hzx8acme001 is suspended; conversation writes are rejected.",
  "request_id": "req_01hzx8sus001"
}