Update a conversation.

PATCH

/conversations/{conversation_id}

const url = 'https://shiftagent.example.com/conversations/example';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"example","status":"active","selected_skill_ids":["example"],"runtime":{"mode":"sticky","sticky_ttl_seconds":1},"filler":{"enabled":true},"metadata":{"additionalProperty":"example"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://shiftagent.example.com/conversations/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "status": "active", "selected_skill_ids": [ "example" ], "runtime": { "mode": "sticky", "sticky_ttl_seconds": 1 }, "filler": { "enabled": true }, "metadata": { "additionalProperty": "example" } }'

Partial update of title, selected_skill_ids (narrowing within context.skill_ids; null clears the narrowing), status ("archived" archives — same as archiveConversation; "active" un-archives), filler, metadata, and the runtime lease:

runtime.sticky_ttl_seconds — extend or shorten a sticky lease (capped by tenant settings; 422 beyond the cap).
runtime.mode: "pooled" — release a sticky sandbox early.
runtime.mode: "sticky" — upgrade a pooled conversation (subject to capacity; 429 capacity-exhausted when no sandbox is free).

Authorizations

integrationKey
platformJwt

Parameters

Path Parameters

conversation_id

required

string

/^con_[A-Za-z0-9]+$/

Internal conversation ID.

Request Body^required

application/json

Partial update for updateConversation. Provided → replaced, omitted → unchanged, null → cleared.

object

title

Display title; null clears.

string | null

<= 255 characters

status

archived archives (same as archiveConversation); active un-archives (vaulted secrets are not restored).

string

Allowed values: active archived

selected_skill_ids

Narrowing within context.skill_ids; null clears.

Array<string> | null

runtime

Runtime lease management via updateConversation. agent_type is immutable and therefore absent here.

object

mode

pooled releases a sticky sandbox early; sticky upgrades a pooled conversation (subject to capacity — 429 when none free).

string

Allowed values: sticky pooled

sticky_ttl_seconds

Extend or shorten the sticky lease (capped by tenant settings).

integer

>= 60 <= 86400

filler

One of:

object
null

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

metadata

Replaces the metadata map wholesale when provided.

object

<= 50 properties

key

additional properties

string

<= 500 characters

Responses

200

Updated conversation.

application/json

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

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:

object
null

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": "conversation",
  "status": "active",
  "runtime": {
    "mode": "sticky",
    "sandbox_state": "warm"
  },
  "storage": {
    "provider": "platform"
  }
}

401

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

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

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"
}

404

Not found — the resource does not exist, was deprovisioned, or lies outside the integration key’s subtree (indistinguishable by design).

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

not_found

Unknown resource

{
  "type": "https://shiftagent.example.com/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No tenant with external_id acme:tenant:999999.",
  "request_id": "req_01hzx8nf001"
}

422

Unprocessable — validation-error (schema/semantic validation failed; errors[] lists JSON-pointer details) or role-required (user has multiple roles and no role_id was given).

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

Field-level validation failure

{
  "type": "https://shiftagent.example.com/problems/validation-error",
  "title": "Validation error",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "errors": [
    {
      "pointer": "/skill_access/skill_ids/0",
      "message": "skl_01hzx8unknown does not belong to the effective repository."
    }
  ],
  "request_id": "req_01hzx8val001"
}

Ambiguous role at conversation creation

{
  "type": "https://shiftagent.example.com/problems/role-required",
  "title": "Role required",
  "status": 422,
  "detail": "User usr_01hzx8jane001 holds 2 roles; pass role_id explicitly.",
  "request_id": "req_01hzx8role01"
}

429

Too many requests — capacity-exhausted (no sandbox available, or the maximum hold time elapsed under on_capacity=hold) or rate-limited. Honor Retry-After.

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

capacity_exhausted

Sandbox pool exhausted (on_capacity=reject)

{
  "type": "https://shiftagent.example.com/problems/capacity-exhausted",
  "title": "Capacity exhausted",
  "status": 429,
  "detail": "No sandbox available; retry after the indicated delay or use on_capacity=hold.",
  "request_id": "req_01hzx8cap001"
}

Headers

Retry-After

integer

Seconds to wait before retrying.

Update a conversation.

Authorizations

Parameters

Path Parameters

Request Body required

Responses

200

Example

401

Examples

404

Examples

422

Examples

429

Examples

Headers

Request Body^required