Skip to content
shiftagent Integration API

Start a conversation.

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

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

  • If the user holds exactly one role it is used; multiple roles without an explicit role_id respond 422 role-required (no silent guessing).
  • repository_id pins a conversation-level override in the resolution cascade (message → conversation → user → role → tenant default).
  • runtime selects the agent runtime (agent_type, open enum) and placement: pooled (default) or sticky with sticky_ttl_seconds (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 stream events).
  • A per-conversation storage bucket is auto-attached.

Response shape depends on initial_message: without it, 201 with the conversation JSON; with it, 200 streaming application/x-ndjson — the conversation object rides in message_start.data.conversation, then the assistant reply streams as usual (see createMessage for the full event protocol).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “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

Section titled “Request Body required ”
Media type application/json

Body for createConversation.

object
user_id
required

Owning user.

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

Display title.

string
<= 255 characters
role_id

Role to resolve the context under. Optional when the user holds exactly one role; required otherwise (422 role-required).

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

Conversation-level repository override.

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

Narrowing within the resolved context skills.

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: sticky pooled
sticky_ttl_seconds

Sticky lease TTL. Capped by tenant.settings.max_sticky_ttl_seconds (422 beyond the cap). Defaults to 300 when mode is sticky.

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 stream events (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 event stream (200) instead of the conversation JSON (201); the conversation rides in message_start.data.conversation.

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
repository_id

One-shot repository override for this run only (top of the resolution cascade).

string
/^rep_[A-Za-z0-9]+$/
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. Vaulted at the boundary, conversation-scoped, 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 events 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",
  "title": "Invoice questions",
  "metadata": {
    "host_ref": "ticket-4521"
  }
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Streaming response (only when initial_message is present): the NDJSON event stream. The created conversation is embedded in message_start.data.conversation; the protocol is identical to createMessage.

Media type application/x-ndjson
One of: discriminator: type

The assistant message has opened; deltas follow.

object
object
required
string
Allowed value: conversation.event
type
required

Event discriminator.

string
conversation_id
required
string
/^con_[A-Za-z0-9]+$/
message_id
required

The assistant message this event belongs to; null on queued events emitted before the run starts.

string | null
seq
required

Monotonic per-response counter — gap ⇒ truncation.

integer
created_at
required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time
type
required
string
Allowed value: message_start
data
required
object
role
required
string
Allowed value: assistant
conversation

Present only on streams initiated by createConversation with initial_message — the just-created conversation.

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": "conversation.event",
  "type": "message_start",
  "data": {
    "role": "assistant",
    "conversation": {
      "object": "conversation",
      "status": "active",
      "runtime": {
        "mode": "sticky",
        "sandbox_state": "warm"
      },
      "storage": {
        "provider": "platform"
      }
    }
  }
}

201

Section titled “201 ”

Conversation created (no initial message).

Media type 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
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
Examples
Example created

Context snapshot resolved at creation

{
  "object": "conversation",
  "id": "con_01hzx8conv001",
  "tenant_id": "tnt_01hzx8acme001",
  "user_id": "usr_01hzx8jane001",
  "title": "Invoice questions",
  "status": "active",
  "repository_id": null,
  "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",
    "sticky_ttl_seconds": null,
    "sandbox_state": "warm",
    "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

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

404

Section titled “404 ”

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

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

Section titled “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).

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

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

429

Section titled “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.

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

Section titled “Headers ”
Retry-After
integer

Seconds to wait before retrying.