Sign in

v2

OpenAPI 3.0.02026-08-051996591.2 MB
Agent Aliases

Create session via alias

Creates a session by routing through an alias. The alias's policy selects the underlying agent that owns the session. Subsequent operations on the session can use this alias or the direct path /v2/agents/{resolved_agent_key}/sessions/{session_key}.

post/v2/agent_aliases/{alias_key}/sessions

Path parameters

alias_keystring required

The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to /v2/agent_aliases/{key}/... target the alias. Calls to /v2/agents/{key}/... target the agent.

Example:support

The alias whose routing policy decides which agent owns the session.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

keystring

A unique key that identifies an agent session.

namestring

Human-readable name for the session.

descriptionstring

A short description of the session's purpose. If omitted, the platform generates one after the session produces events. Pass an empty string to suppress auto-generation.

metadataobject

Arbitrary metadata associated with the session.

enabledboolean

Whether the session should be enabled upon creation.

tti_minutesinteger

Time-to-idle in minutes for the session. If no events occur in the session for this duration, the session is deleted automatically. If set to 0, the session does not expire.

secretsobject

Session-scoped secrets to store on the new session. Map of secret name to plaintext value. Encrypted at rest with the owning agent's encryption key. Referenced from tool argument_override via {"$ref": "session.secrets.<name>"}. Returned masked (****) on reads.

Example request

{
  "key": "customer_support_chat",
  "name": "Customer Support Session",
  "description": "Helping customer troubleshoot issues",
  "metadata": {
    "customer_id": "12345",
    "priority": "medium",
    "channel": "web_chat"
  },
  "enabled": true,
  "tti_minutes": 60,
  "secrets": {
    "slack_user_token": "xoxp-your-token-here"
  }
}

Response

The newly created session, owned by the agent the alias's policy resolved to.

keystring required

A unique key that identifies an agent session.

agent_keystring required

A unique key that identifies an agent.

namestring required

Human-readable name for the session.

descriptionstring

A short description of the session's purpose. If omitted at creation, the platform generates one after the agent produces events. An empty string indicates auto-generation is disabled for this session.

metadataobject

Arbitrary metadata associated with the session.

current_step_namestring nullable

The step name the session will resume at on the next user message. If null, the session starts at the agent's first_step.

enabledboolean required

Whether the session is currently active and can accept new messages.

status'unstarted' | 'running' | 'stopped'

Lifecycle status of the session. unstarted before the session receives any event, running while the agent is producing events, and stopped when the session is idle with no event in flight. stopped implies no terminating action — the session returns to running on the next request.

created_by_agent_keystring

A unique key that identifies an agent.

created_by_session_keystring

A unique key that identifies an agent session.

tti_minutesinteger

Time-to-idle in minutes for the session. If no events occur in the session for this duration, the session is deleted automatically. If not specified, the session does not expire.

created_atstring date-time required

Timestamp when the session was created.

alias_keystring nullable

If this session was created through an alias (POST /v2/agent_aliases/{alias_key}/sessions), the alias key the caller used. The agent_key field above is the resolved agent the alias's policy picked. Null when the session was created directly under an agent (POST /v2/agents/{agent_key}/sessions).

secretsobject

Session-scoped secrets, with values masked as "****". Plaintext is never returned on read; tools resolve the real value via argument_override with {"$ref": "session.secrets.<name>"}. Set or rotate via the session create or update request.

Example response

{
  "key": "customer_support_chat",
  "agent_key": "customer_support",
  "name": "Customer Support Session",
  "description": "Helping customer troubleshoot widget installation issues",
  "metadata": {
    "customer_id": "12345",
    "priority": "high",
    "channel": "web_chat"
  },
  "current_step_name": "billing",
  "enabled": true,
  "status": "stopped",
  "created_by_agent_key": "customer_support",
  "created_by_session_key": "customer_support_chat",
  "tti_minutes": 60,
  "created_at": "2024-01-15T10:30:00Z",
  "session_context_usage": {
    "input_tokens": {
      "count": 120,
      "cached_tokens": 100
    },
    "output_tokens": {
      "count": 30
    },
    "total_tokens": 150,
    "model_context_window": 200000
  },
  "effective_compaction": {
    "enabled": true,
    "threshold_percent": 80,
    "keep_recent_inputs": 1
  },
  "alias_key": "support",
  "secrets": {
    "slack_user_token": "****"
  }
}