Upsert conversation-scoped secrets (write-only).

PUT

/conversations/{conversation_id}/secrets

const url = 'https://shiftagent.example.com/conversations/example/secrets';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"secrets":{"CRM_API_KEY":"example-value-vaulted-never-echoed","WAREHOUSE_PASSWORD":"example-value-vaulted-never-echoed"}}'
};

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

curl --request PUT \
  --url https://shiftagent.example.com/conversations/example/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "secrets": { "CRM_API_KEY": "example-value-vaulted-never-echoed", "WAREHOUSE_PASSWORD": "example-value-vaulted-never-echoed" } }'

Vaults alias → value pairs scoped to this conversation. Idempotent merge-upsert per alias: existing aliases are overwritten, others are untouched.

Write-only contract: values are vaulted at the boundary and never appear in any response, message, event, or log. The agent runtime receives only {{secret:ALIAS}} placeholders; the egress proxy resolves them on outbound network calls. The response lists the conversation’s aliases and metadata — never values.

Authorizations

integrationKey

Parameters

Path Parameters

conversation_id

required

string

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

Internal conversation ID.

Request Body^required

application/json

Body for putConversationSecrets — write-only upsert.

object

secrets

required

alias → value pairs to vault. Existing aliases are overwritten; others untouched. Values never appear in any response.

object

>= 1 properties <= 50 properties

key

additional properties

string

Examples

vault_two

Vault two secrets for this conversation

{
  "secrets": {
    "CRM_API_KEY": "example-value-vaulted-never-echoed",
    "WAREHOUSE_PASSWORD": "example-value-vaulted-never-echoed"
  }
}

Responses

200

Aliases now vaulted for this conversation — values are never returned.

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>

A vaulted secret alias for a conversation. Values are never represented in any schema — write-only at every entry point.

object

object

required

string

Allowed value: conversation.secret

alias

required

The alias the agent references as {{secret:ALIAS}}.

string

/^[A-Z][A-Z0-9_]{0,63}$/

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

aliases_only

Response carries aliases and metadata only

{
  "object": "list",
  "data": [
    {
      "object": "conversation.secret",
      "alias": "CRM_API_KEY",
      "created_at": "2026-07-02T10:01:00Z",
      "updated_at": "2026-07-02T10:01:00Z"
    },
    {
      "object": "conversation.secret",
      "alias": "WAREHOUSE_PASSWORD",
      "created_at": "2026-07-02T10:01:00Z",
      "updated_at": "2026-07-02T10:01:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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

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), approval-expired (approval already resolved or expired), 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) 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"
}

Upsert conversation-scoped secrets (write-only).

Authorizations

Parameters

Path Parameters

Request Body required

Examples

Responses

200

Examples

401

Examples

404

Examples

409

Examples

422

Examples

Request Body^required