Claude Platform Docs

Sessions

Create Session
beta.sessions.create(SessionCreateParams**kwargs) -> BetaManagedAgentsSession
POST/v1/sessions
List Sessions
beta.sessions.list(SessionListParams**kwargs) -> SyncBidirectionalPageCursor[BetaManagedAgentsSession]
GET/v1/sessions
Get Session
beta.sessions.retrieve(strsession_id, SessionRetrieveParams**kwargs) -> BetaManagedAgentsSession
GET/v1/sessions/{session_id}
Update Session
beta.sessions.update(strsession_id, SessionUpdateParams**kwargs) -> BetaManagedAgentsSession
POST/v1/sessions/{session_id}
Delete Session
beta.sessions.delete(strsession_id, SessionDeleteParams**kwargs) -> BetaManagedAgentsDeletedSession
DELETE/v1/sessions/{session_id}
Archive Session
beta.sessions.archive(strsession_id, SessionArchiveParams**kwargs) -> BetaManagedAgentsSession
POST/v1/sessions/{session_id}/archive
Models
class BetaManagedAgentsAdvisorParams: …

Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name anthropic.advisor.

model: str

A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.

minLength1
maxLength256
type: Literal["advisor"]
class BetaManagedAgentsAgentMessagePreview: …
id: str

The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.

type: Literal["agent.message"]
class BetaManagedAgentsAgentParams: …

Specification for an Agent. Provide a specific version or use the short-form agent="agent_id" for the most recent version

id: str

The agent ID.

minLength1
maxLength128
type: Literal["agent"]
version: Optional[int]

The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

formatint32
class BetaManagedAgentsAgentThinkingPreview: …
id: str

The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.

type: Literal["agent.thinking"]
class BetaManagedAgentsAgentWithOverridesParams: …

Reference to an agent plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.

class BetaManagedAgentsBranchCheckout: …
name: str

Branch name to check out.

minLength1
maxLength255
type: Literal["branch"]
class BetaManagedAgentsBudgetLimit: …

A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

max_list_cost: BetaMonetaryAmount

A monetary amount in a specific currency.

amount: str

Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

currency: BetaCurrency

Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

type: Literal["limit"]
class BetaManagedAgentsCacheCreationUsage: …

Prompt-cache creation token usage broken down by cache lifetime.

ephemeral_1h_input_tokens: Optional[int]

Tokens used to create 1-hour ephemeral cache entries.

formatint32
ephemeral_5m_input_tokens: Optional[int]

Tokens used to create 5-minute ephemeral cache entries.

formatint32
class BetaManagedAgentsCommitCheckout: …
sha: str

Full commit SHA to check out.

minLength7
maxLength64
type: Literal["commit"]
class BetaManagedAgentsDeletedSession: …

Confirmation that a session has been permanently deleted.

id: str
type: Literal["session_deleted"]
class BetaManagedAgentsDeltaContent: …
content: BetaManagedAgentsTextBlock

Regular text content.

text: str

The text content.

minLength1
type: Literal["text"]
type: Literal["content_delta"]
index: Optional[int]

Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.

formatuint32
class BetaManagedAgentsDeltaEvent: …

An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

delta: BetaManagedAgentsDeltaContent

One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.

content: BetaManagedAgentsTextBlock

Regular text content.

text: str

The text content.

minLength1
type: Literal["text"]
type: Literal["content_delta"]
index: Optional[int]

Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.

formatuint32
event_id: str

The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.

type: Literal["event_delta"]
Literal["agent.message", "agent.thinking"]

EventDeltaType enum

One of the following:
"agent.message"
"agent.thinking"
class BetaManagedAgentsFileResourceParams: …

Mount a file uploaded via the Files API into the session.

file_id: str

ID of a previously uploaded file.

minLength1
maxLength128
type: Literal["file"]
mount_path: Optional[str]

Mount path in the container. Defaults to /mnt/session/uploads/<file_id>.

minLength1
maxLength4096
class BetaManagedAgentsGitHubRepositoryResourceParams: …

Mount a GitHub repository into the session's container.

class BetaManagedAgentsMemoryStoreResourceParam: …

Parameters for attaching a memory store to an agent session.

memory_store_id: str

The memory store ID (memstore_...). Must belong to the caller's organization and workspace.

type: Literal["memory_store"]
access: Optional[Literal["read_write", "read_only"]]

Access mode for an attached memory store.

One of the following:
"read_write"
"read_only"
instructions: Optional[str]

Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.

maxLength4096
class BetaManagedAgentsMultiagent: …

Resolved coordinator topology with a concrete agent roster.

agents: List[Agent]

Agents the coordinator may spawn as session threads, each resolved to a specific version.

One of the following:
class BetaManagedAgentsAgentReference: …

A resolved agent reference with a concrete version.

id: str
type: Literal["agent"]
version: int
formatint32
class BetaManagedAgentsAdvisor: …

Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

model: str

The advisor model id.

type: Literal["advisor"]
type: Literal["coordinator"]
class BetaManagedAgentsMultiagentParams: …

A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the agents roster.

BetaManagedAgentsMultiagentRosterEntryParams

An entry in a multiagent roster: an agent ID string, a versioned agent reference, or self.

One of the following:
str
class BetaManagedAgentsAgentParams: …

Specification for an Agent. Provide a specific version or use the short-form agent="agent_id" for the most recent version

id: str

The agent ID.

minLength1
maxLength128
type: Literal["agent"]
version: Optional[int]

The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

formatint32
class BetaManagedAgentsMultiagentSelfParams: …

Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.

type: Literal["self"]
class BetaManagedAgentsAdvisorParams: …

Platform advisor roster entry: a model the session's primary thread may consult mid-turn. At most one per roster; the entry occupies the roster name anthropic.advisor.

model: str

A Claude model id. The model must be permitted as an advisor for this agent's model — see the sessions/threads/advisor spec.

minLength1
maxLength256
type: Literal["advisor"]
class BetaManagedAgentsOutcomeEvaluationResource: …

Evaluation state for a single outcome defined via a define_outcome event.

completed_at: Optional[datetime]

A timestamp in RFC 3339 format

formatdate-time
description: str

What the agent should produce.

explanation: Optional[str]

Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.

iteration: int

0-indexed revision cycle the outcome is currently on.

formatint32
outcome_id: str

Server-generated outc_ ID for this outcome.

result: str

Current evaluation state. pending before the agent begins work; running while producing or revising; evaluating while the grader scores; satisfied/max_iterations_reached/failed/interrupted are terminal.

type: Literal["outcome_evaluation"]
class BetaManagedAgentsServerToolUsage: …

Cumulative count of server-executed tool invocations, broken down by tool.

web_fetch_requests: Optional[int]

Number of server-executed web fetch requests.

formatint32
web_search_requests: Optional[int]

Number of server-executed web search requests.

formatint32
class BetaManagedAgentsSession: …

A Managed Agents session.

class BetaManagedAgentsSessionAgent: …

Resolved agent definition for a session. Snapshot of the agent at session creation time.

class BetaManagedAgentsSessionAgentUpdate: …

Mid-session agent configuration update. Only tools and mcp_servers are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back.

class BetaManagedAgentsSessionMultiagentCoordinator: …

Resolved coordinator topology with full agent definitions for each roster member.

agents: List[Agent]

Full agent definitions the coordinator may spawn as session threads.

One of the following:
class BetaManagedAgentsSessionThreadAgent: …

Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.

class BetaManagedAgentsAdvisor: …

Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

model: str

The advisor model id.

type: Literal["advisor"]
type: Literal["coordinator"]
class BetaManagedAgentsSessionStats: …

Timing statistics for a session.

active_seconds: Optional[float]

Cumulative time in seconds the session spent in running status. Excludes idle time.

formatdouble
duration_seconds: Optional[float]

Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

formatdouble
class BetaManagedAgentsSessionUpdatedEvent: …

Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

class BetaManagedAgentsSessionUsage: …

Cumulative token usage for a session across all turns.

class BetaManagedAgentsSessionUsageEvent: …

Periodic snapshot of the session's cumulative usage and tracked list cost.

id: str

Unique identifier for this event.

processed_at: datetime

A timestamp in RFC 3339 format

formatdate-time
type: Literal["session.usage"]
usage: BetaManagedAgentsSessionUsageSnapshot

Point-in-time snapshot of a session's cumulative usage.

budget: Optional[BetaManagedAgentsBudgetLimit]

A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

max_list_cost: BetaMonetaryAmount

A monetary amount in a specific currency.

amount: str

Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

currency: BetaCurrency

Uppercase ISO-4217 currency code. USD is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

type: Literal["limit"]
class BetaManagedAgentsStartEvent: …

Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

event: BetaManagedAgentsStartEventPreview

The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.

One of the following:
class BetaManagedAgentsAgentMessagePreview: …
id: str

The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.

type: Literal["agent.message"]
class BetaManagedAgentsAgentThinkingPreview: …
id: str

The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.

type: Literal["agent.thinking"]
type: Literal["event_start"]
BetaManagedAgentsStartEventPreview
One of the following:
class BetaManagedAgentsAgentMessagePreview: …
id: str

The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.

type: Literal["agent.message"]
class BetaManagedAgentsAgentThinkingPreview: …
id: str

The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.

type: Literal["agent.thinking"]
class BetaManagedAgentsSystemContentBlock: …

Regular text content.

text: str

The text content.

minLength1
type: Literal["text"]
class BetaManagedAgentsSystemMessageEvent: …

A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.

id: str

Unique identifier for this event.

content: List[BetaManagedAgentsSystemContentBlock]

System content blocks. Text-only.

text: str

The text content.

minLength1
type: Literal["text"]
type: Literal["system.message"]
processed_at: Optional[datetime]

A timestamp in RFC 3339 format

formatdate-time
class BetaManagedAgentsUserToolResultEvent: …

Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.

SessionsEvents

List Events
beta.sessions.events.list(strsession_id, EventListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionEvent]
GET/v1/sessions/{session_id}/events
Send Events
beta.sessions.events.send(strsession_id, EventSendParams**kwargs) -> BetaManagedAgentsSendSessionEvents
POST/v1/sessions/{session_id}/events
Stream Events
beta.sessions.events.stream(strsession_id, EventStreamParams**kwargs) -> BetaManagedAgentsStreamSessionEvents
GET/v1/sessions/{session_id}/events/stream

SessionsResources

Add Session Resource
beta.sessions.resources.add(strsession_id, ResourceAddParams**kwargs) -> BetaManagedAgentsFileResource
POST/v1/sessions/{session_id}/resources
List Session Resources
beta.sessions.resources.list(strsession_id, ResourceListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionResource]
GET/v1/sessions/{session_id}/resources
Get Session Resource
beta.sessions.resources.retrieve(strresource_id, ResourceRetrieveParams**kwargs) -> ResourceRetrieveResponse
GET/v1/sessions/{session_id}/resources/{resource_id}
Update Session Resource
beta.sessions.resources.update(strresource_id, ResourceUpdateParams**kwargs) -> ResourceUpdateResponse
POST/v1/sessions/{session_id}/resources/{resource_id}
Delete Session Resource
beta.sessions.resources.delete(strresource_id, ResourceDeleteParams**kwargs) -> BetaManagedAgentsDeleteSessionResource
DELETE/v1/sessions/{session_id}/resources/{resource_id}

SessionsThreads

List Session Threads
beta.sessions.threads.list(strsession_id, ThreadListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionThread]
GET/v1/sessions/{session_id}/threads
Get Session Thread
beta.sessions.threads.retrieve(strthread_id, ThreadRetrieveParams**kwargs) -> BetaManagedAgentsSessionThread
GET/v1/sessions/{session_id}/threads/{thread_id}
Archive Session Thread
beta.sessions.threads.archive(strthread_id, ThreadArchiveParams**kwargs) -> BetaManagedAgentsSessionThread
POST/v1/sessions/{session_id}/threads/{thread_id}/archive

SessionsThreadsEvents

List Session Thread Events
beta.sessions.threads.events.list(strthread_id, EventListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsSessionEvent]
GET/v1/sessions/{session_id}/threads/{thread_id}/events
Stream Session Thread Events
beta.sessions.threads.events.stream(strthread_id, EventStreamParams**kwargs) -> BetaManagedAgentsStreamSessionThreadEvents
GET/v1/sessions/{session_id}/threads/{thread_id}/stream