Start a conversation.

POST

/conversations

const url = 'https://shiftagent.example.com/conversations';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"user_id":"usr_01hzx8jane001","external_id":"acme:conversation:ticket-4521","title":"Invoice questions","metadata":{"host_ref":"ticket-4521"}}'
};

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

curl --request POST \
  --url https://shiftagent.example.com/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "user_id": "usr_01hzx8jane001", "external_id": "acme:conversation:ticket-4521", "title": "Invoice questions", "metadata": { "host_ref": "ticket-4521" } }'

Creates a conversation for a user, resolving and snapshotting its context at creation: the user’s role plus the tenant’s repository and the role’s effective skills, recorded in context {role_id, repository_id, skill_ids} so history is self-explaining.

The user’s assigned role resolves the context; a user with no role responds 422 role-required.
The repository is the tenant’s (inherited by every conversation and message — there are no per-conversation overrides).
runtime selects the agent runtime (agent_type, open enum) and placement: pooled (default) or warm with idle_ttl_seconds (sliding idle timeout, default 300, capped by tenant settings).
filler {enabled} overrides the tenant’s filler-agent default for this conversation.
on_capacity chooses the capacity strategy for the initial message (reject default; hold queues with queued platform notices).
A per-conversation storage bucket is auto-attached.

external_id optionally records the host system’s conversation ID (unique per tenant). If taken, responds 409 external-id-conflict with conflicting_resource_id pointing at the existing conversation — the guarded-explicit style (getConversationByExternalId to check, POST to create), complementing the deterministic upsertConversationByExternalId upsert. For host-mapped conversations prefer the upsert.

Response shape depends on initial_message: without it, 201 with the conversation JSON; with it, 200 streaming application/x-ndjson — the conversation id rides in the X-Shiftagent-Conversation-Id response header plus a leading {"object":"platform.event","type":"conversation"} line, then the assistant reply streams as the native agent event stream (see createMessage for the full protocol).

Authorizations

integrationKey
platformJwt

Parameters

Header Parameters

Idempotency-Key

string

<= 255 characters

Optional idempotency key (any unique string, e.g. a UUID; max 255 chars). Responses are cached 24h per (key principal, operation, key); replays return the original status and body with Idempotency-Replayed: true. Reusing a key with a different payload responds 409 idempotency-key-conflict.

Request Body^required

application/json

Body for createConversation.

object

user_id

required

Owning user.

string

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

external_id

Optional host mapping (unique per tenant). If taken, responds 409 external-id-conflict with conflicting_resource_id pointing at the existing conversation. For host-mapped conversations prefer upsertConversationByExternalId.

string

<= 255 characters

title

Display title.

string

<= 255 characters

selected_skill_ids

Narrowing within the resolved context skills (the user’s role resolves the context; a user with no role → 422 role-required).

Array<string>

runtime

Runtime knobs at conversation creation.

object

agent_type

Agent runtime (open enum — e.g. claude-agent-sdk, codex, deepagent). Defaults from tenant settings. Immutable afterwards.

string

mode

Placement mode.

string

default: pooled

Allowed values: warm pooled

idle_ttl_seconds

Sliding idle timeout for warm mode. Capped by tenant.settings.max_idle_ttl_seconds (422 beyond the cap). Defaults to 300 when mode is warm.

integer

>= 60 <= 86400

filler

Conversation-level filler override.

object

enabled

required

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

boolean

on_capacity

Capacity strategy for the initial message: reject → 429 capacity-exhausted + Retry-After; hold → queue with queued platform notices (bounded by the deployment’s max hold time).

string

default: reject

Allowed values: reject hold

metadata

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

initial_message

When present, the response is the NDJSON agent event stream (200) instead of the conversation JSON (201); the conversation id rides in the X-Shiftagent-Conversation-Id header and a leading platform notice line.

object

content

required

The user’s message text.

string

>= 1 characters

parts

Optional typed blocks (extensibility).

Array<object>

Typed content block — the extensibility seam for richer runs. Known types: text, tool_call, tool_result; unknown types must be ignored by clients.

object

type

required

Block type (open enum).

string

text

Text content (for text blocks).

string

key

additional properties

any

skill_ids

Per-message skill narrowing — keeps the agent context lean. Must be within the conversation’s effective skills.

Array<string>

env

Plaintext, non-secret run parameters, visible to the agent verbatim. Never place secret material here — use secrets.

object

key

additional properties

string

secrets

Write-only alias → value map, scoped to this message’s run (ephemeral — resolved before conversation-, user-, and tenant-scoped secrets). Never echoed anywhere; the agent sees only {{secret:ALIAS}} placeholders resolved by the egress proxy.

object

>= 1 properties

key

additional properties

string

filler

Per-message filler override (most specific wins).

object

enabled

required

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

boolean

on_capacity

reject → 429 capacity-exhausted + Retry-After when no sandbox is available; hold → the stream first emits queued platform notices until one frees (bounded by the deployment’s max hold time).

string

default: reject

Allowed values: reject hold

metadata

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

Examples

Start a conversation (no initial message)

{
  "user_id": "usr_01hzx8jane001",
  "external_id": "acme:conversation:ticket-4521",
  "title": "Invoice questions",
  "metadata": {
    "host_ref": "ticket-4521"
  }
}

Warm runtime + initial message (streams)

{
  "user_id": "usr_01hzx8jane001",
  "runtime": {
    "agent_type": "claude-agent-sdk",
    "mode": "warm",
    "idle_ttl_seconds": 300
  },
  "filler": {
    "enabled": true
  },
  "on_capacity": "hold",
  "initial_message": {
    "content": "Summarize today's open jobs."
  }
}

Responses

200

Streaming response (only when initial_message is present): the native agent event stream. The created conversation’s id rides in the X-Shiftagent-Conversation-Id header and a leading platform notice line; the protocol is identical to createMessage.

application/x-ndjson

One NDJSON stream line. The stream is the platform’s native agent event stream — raw Claude Agent SDK events passed through verbatim (vocabulary versioned by the X-Shiftagent-Stream-Format response header, currently claude-sdk/1) — interleaved with platform lines:

Agent events carry a top-level type — system, stream_event, assistant, user, and the terminal result.
{"event":"ping"} — keepalive.
{"object":"platform.event","type":"queued","position":n, "retry_hint_seconds":n} — capacity hold notice.
{"object":"platform.event","type":"conversation", "conversation":{…}} — leading line on create/upsert-with- initial_message streams, carrying the conversation.
{"object":"platform.event","type":"error","problem":{…}} — terminal platform abort carrying an RFC 9457 problem (e.g. missing-secret).

Clients MUST ignore unknown line shapes (new event types are additive). Exactly one terminal line (result or platform error) ends every complete stream; a stream that closes without one is truncated — reconcile via listMessages.

object

key

additional properties

any

Example ^generated

{}

201

Conversation created (no initial message).

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]+$/

external_id

required

Host system’s conversation ID (namespaced by the adapter). Unique per tenant; natural key for upsertConversationByExternalId — the continue-vs-create decision. Null for conversations created via plain createConversation without one.

string | null

<= 255 characters

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

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 and releases it; warm — the conversation keeps its sandbox alive between messages under a sliding idle timeout (idle_ttl_seconds, reset on every message). The most recent message’s settings govern what happens next.

string

Allowed values: warm pooled

idle_ttl_seconds

required

Sliding idle timeout of the warm sandbox; null for pooled conversations.

integer | null

sandbox_state

required

warm — a sandbox is currently held for this conversation (fast next message); cold — none held (pooled, warm-before-first- message, or the idle timer lapsed and the sandbox was recycled — the next message cold-starts and resumes the same session).

string

Allowed values: warm cold

expires_at

required

When the warm hold lapses (moves forward on every message); null when sandbox_state is cold.

string | null format: date-time

filler

required

One of:

object
null

Filler-agent enablement. Cascade: tenant settings → conversation → message; most specific wins. Filler output is part of the reply stream and the persisted message — indistinguishable from agent output by design.

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

Examples

created

Context snapshot resolved at creation

{
  "object": "conversation",
  "id": "con_01hzx8conv001",
  "external_id": "acme:conversation:ticket-4521",
  "tenant_id": "tnt_01hzx8acme001",
  "user_id": "usr_01hzx8jane001",
  "title": "Invoice questions",
  "status": "active",
  "context": {
    "role_id": "rol_01hzx8csr001",
    "repository_id": "rep_01hzx8fieldops",
    "skill_ids": [
      "skl_01hzx8dispatch",
      "skl_01hzx8invoice"
    ]
  },
  "selected_skill_ids": null,
  "runtime": {
    "agent_type": "claude-agent-sdk",
    "mode": "pooled",
    "idle_ttl_seconds": null,
    "sandbox_state": "cold",
    "expires_at": null
  },
  "filler": null,
  "storage": {
    "provider": "platform",
    "bucket_uri": "s3://shiftagent-tenant-acme/con_01hzx8conv001"
  },
  "message_count": 0,
  "last_message_at": null,
  "metadata": {
    "host_ref": "ticket-4521"
  },
  "created_at": "2026-07-02T10:00:00Z",
  "updated_at": "2026-07-02T10:00:00Z"
}

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

403

Forbidden — tenant-suspended (writes to a suspended tenant) or insufficient-scope (key/token lacks the scope or a platform JWT reaches beyond its user).

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

tenant_suspended

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

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

409

Conflict — name-conflict / external-id-conflict (unique name or external ID taken; conflicting_resource_id names the holder — fetch it and continue), resource-in-use (guarded delete refused), cross-tenant (referenced resource belongs to another tenant), conversation-archived (write to an archived conversation), or idempotency-key-conflict (same key, different payload).

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

Named sub-resource already exists — recoverable

{
  "type": "https://shiftagent.example.com/problems/name-conflict",
  "title": "Name conflict",
  "status": 409,
  "detail": "A role named \"csr\" already exists in this tenant.",
  "conflicting_resource_id": "rol_01hzx8csr001",
  "request_id": "req_01hzx8conf01"
}

Guarded delete refused

{
  "type": "https://shiftagent.example.com/problems/resource-in-use",
  "title": "Resource in use",
  "status": 409,
  "detail": "Repository is attached to 1 tenant and pinned by 2 roles.",
  "conflicting_resource_id": "tnt_01hzx8acme001",
  "request_id": "req_01hzx8used01"
}

422

Unprocessable — validation-error (schema/semantic validation failed; errors[] lists JSON-pointer details), role-required (the user has no role assigned, so no conversation context can resolve), or missing-secret (a referenced alias is vaulted at no scope).

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 tenant's repository."
    }
  ],
  "request_id": "req_01hzx8val001"
}

User has no role at conversation creation

{
  "type": "https://shiftagent.example.com/problems/role-required",
  "title": "Role required",
  "status": 422,
  "detail": "User usr_01hzx8jane001 has no role assigned; assign one before starting conversations.",
  "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.

Start a conversation.

Authorizations

Parameters

Header Parameters

Request Body required

Examples

Responses

200

Example generated

201

Examples

401

Examples

403

Examples

404

Examples

409

Examples

422

Examples

429

Examples

Headers

Request Body^required

Example ^generated