> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryreplicas.com/llms.txt > Use this file to discover all available pages before exploring further. # Stream Events > Opens a Server-Sent Events (SSE) stream for real-time events from a replica. The connection remains open and events are pushed as they occur. Each event is delivered as an SSE message in the format `data: \n\n`. A heartbeat ping is sent every 15 seconds to keep the connection alive. Clients should reconnect automatically on disconnect. All events share a common envelope structure with `id` (unique event ID), `ts` (ISO 8601 timestamp), `type` (event type discriminator), and `payload` (type-specific data). See the `EngineEvent` schema for all possible event types. ## OpenAPI ````yaml /openapi.json get /v1/replica/{id}/events openapi: 3.1.0 info: title: Replica API version: 2.0.0 description: >- The Replica API allows you to programmatically manage cloud workspaces for AI agents. Use this API to manage environments (the org-scoped primitive workspaces are created from — including variables, files, skills, MCPs, warm hooks, start hooks, and warm pools), create and manage replicas, send messages, manage chats, stream events, read connected repositories and repository sets, and configure automations. servers: - url: https://api.tryreplicas.com description: Production API security: - apiKey: [] tags: - name: Environments description: >- Manage environments — the primitive that workspaces are created from. Variables, files, skills, MCPs, warm-hooks, and warm-pools are all scoped to an environment. Every organization has a singleton Global environment whose values apply to every workspace. Personal environments are scoped to the authenticated user and can be standalone or source-backed by a team environment. - name: Repository description: >- Read repositories and repository sets connected to your organization. Repositories are the underlying GitHub-connection layer; bind them to an environment to use them in workspaces. - name: Replica description: Manage replicas (workspaces) for AI agents - name: Terminal description: Manage interactive terminal sessions in active workspaces - name: Preview description: Manage public preview URLs for workspace ports - name: Profile description: Read and update the authenticated user's profile - name: Credentials description: >- Manage coding-agent credentials for an organization or the authenticated user - name: Google Search Console description: >- Read Search Console properties, performance, sitemaps, and URL inspection results through a connected Google account - name: Slack description: Route Slack threads to Replicas workspaces - name: Automation description: >- Create and manage automations that trigger replicas on a schedule or in response to events - name: Downloads description: Download Replicas applications - name: Analytics description: >- Read aggregated activity and usage metrics for your organization: compute minutes, workspaces created by source, and pull request throughput over a time range. - name: Presence description: >- Read and report ephemeral member presence: who is online, where they are (environment or workspace), and whether they are typing. Presence is backed by short-lived keys rather than the database and broadcast to other members over the events stream. paths: /v1/replica/{id}/events: get: tags: - Replica summary: Stream Events description: >- Opens a Server-Sent Events (SSE) stream for real-time events from a replica. The connection remains open and events are pushed as they occur. Each event is delivered as an SSE message in the format `data: \n\n`. A heartbeat ping is sent every 15 seconds to keep the connection alive. Clients should reconnect automatically on disconnect. All events share a common envelope structure with `id` (unique event ID), `ts` (ISO 8601 timestamp), `type` (event type discriminator), and `payload` (type-specific data). See the `EngineEvent` schema for all possible event types. operationId: streamReplicaEvents parameters: - name: id in: path description: The unique identifier of the replica required: true schema: type: string format: uuid responses: '200': description: >- SSE event stream opened successfully. Each line is a JSON-encoded `EngineEvent`. content: text/event-stream: schema: $ref: '#/components/schemas/EngineEvent' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: EngineEvent: type: object description: >- A real-time event from the replica engine. All events share a common envelope with `id`, `ts`, `type`, and `payload` fields. The `type` field discriminates between event variants. oneOf: - title: engine.ready type: object description: Engine initialization complete. properties: id: type: string description: Unique event ID ts: type: string format: date-time description: ISO 8601 timestamp type: type: string const: engine.ready payload: type: object properties: version: type: string description: Engine protocol version example: v1 required: - version required: - id - ts - type - payload - title: engine.status.changed type: object description: >- Engine status snapshot changed (uptime, active sessions, chat counts, etc.). properties: id: type: string ts: type: string format: date-time type: type: string const: engine.status.changed payload: type: object properties: status: $ref: '#/components/schemas/EngineStatusSnapshot' required: - status required: - id - ts - type - payload - title: repo.discovered type: object description: New repositories discovered in the workspace. properties: id: type: string ts: type: string format: date-time type: type: string const: repo.discovered payload: type: object properties: repos: type: array items: $ref: '#/components/schemas/EngineRepoState' required: - repos required: - id - ts - type - payload - title: repo.status.changed type: object description: >- Repository status changed (branch, diff, PR URL, start hooks status). properties: id: type: string ts: type: string format: date-time type: type: string const: repo.status.changed payload: type: object properties: repos: type: array items: $ref: '#/components/schemas/EngineRepoState' required: - repos required: - id - ts - type - payload - title: chat.created type: object description: A new chat session was created. properties: id: type: string ts: type: string format: date-time type: type: string const: chat.created payload: type: object properties: chat: $ref: '#/components/schemas/EngineChatSummary' clientRequestId: type: string description: >- Echo of the `clientRequestId` from the create request, if one was provided required: - chat required: - id - ts - type - payload - title: chat.updated type: object description: A chat session was updated (e.g. title or processing state changed). properties: id: type: string ts: type: string format: date-time type: type: string const: chat.updated payload: type: object properties: chat: $ref: '#/components/schemas/EngineChatSummary' required: - chat required: - id - ts - type - payload - title: chat.deleted type: object description: A chat session was deleted. properties: id: type: string ts: type: string format: date-time type: type: string const: chat.deleted payload: type: object properties: chatId: type: string description: ID of the deleted chat required: - chatId required: - id - ts - type - payload - title: chat.turn.accepted type: object description: A message was accepted and queued for processing. properties: id: type: string ts: type: string format: date-time type: type: string const: chat.turn.accepted payload: type: object properties: chatId: type: string description: Chat session ID messageId: type: string description: Unique message ID queued: type: boolean description: >- Whether the message was queued (true) or processing immediately (false) position: type: integer description: Position in the queue (0 if processing immediately) required: - chatId - messageId - queued - position required: - id - ts - type - payload - title: chat.turn.started type: object description: The coding agent started processing a message. properties: id: type: string ts: type: string format: date-time type: type: string const: chat.turn.started payload: type: object properties: chatId: type: string description: Chat session ID messageId: type: string description: Message being processed required: - chatId - messageId required: - id - ts - type - payload - title: chat.turn.delta type: object description: >- A streaming delta from the coding agent (tool calls, text output, etc.). properties: id: type: string ts: type: string format: date-time type: type: string const: chat.turn.delta payload: type: object properties: chatId: type: string description: Chat session ID event: $ref: '#/components/schemas/AgentEvent' required: - chatId - event required: - id - ts - type - payload - title: chat.turn.completed type: object description: The coding agent finished processing a message. properties: id: type: string ts: type: string format: date-time type: type: string const: chat.turn.completed payload: type: object properties: chatId: type: string description: Chat session ID isComplete: type: boolean description: >- Whether the turn completed fully (false if interrupted or errored) required: - chatId - isComplete required: - id - ts - type - payload - title: chat.interrupted type: object description: A chat turn was interrupted. properties: id: type: string ts: type: string format: date-time type: type: string const: chat.interrupted payload: type: object properties: chatId: type: string description: Chat session ID interrupted: type: boolean description: Whether the interruption was successful queue: type: array items: type: string description: Remaining message IDs in the queue required: - chatId - interrupted - queue required: - id - ts - type - payload - title: hooks.started type: object description: Hooks started executing. properties: id: type: string ts: type: string format: date-time type: type: string const: hooks.started payload: type: object properties: running: type: boolean description: Whether hooks are currently running completed: type: boolean description: Whether hooks have completed required: - running - completed required: - id - ts - type - payload - title: hooks.progress type: object description: Hooks execution progress update. properties: id: type: string ts: type: string format: date-time type: type: string const: hooks.progress payload: type: object properties: running: type: boolean completed: type: boolean required: - running - completed required: - id - ts - type - payload - title: hooks.completed type: object description: Hooks completed successfully. properties: id: type: string ts: type: string format: date-time type: type: string const: hooks.completed payload: type: object properties: running: type: boolean completed: type: boolean required: - running - completed required: - id - ts - type - payload - title: hooks.failed type: object description: Hooks execution failed. properties: id: type: string ts: type: string format: date-time type: type: string const: hooks.failed payload: type: object properties: running: type: boolean completed: type: boolean required: - running - completed required: - id - ts - type - payload - title: hooks.status type: object description: Current hooks status snapshot. properties: id: type: string ts: type: string format: date-time type: type: string const: hooks.status payload: type: object properties: running: type: boolean completed: type: boolean required: - running - completed required: - id - ts - type - payload - title: preview.changed type: object description: Available preview ports changed. properties: id: type: string ts: type: string format: date-time type: type: string const: preview.changed payload: type: object properties: previews: type: array items: $ref: '#/components/schemas/EnginePreviewPort' required: - previews required: - id - ts - type - payload - title: error type: object description: An error occurred in the event stream. properties: id: type: string ts: type: string format: date-time type: type: string const: error payload: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message details: type: string description: Additional error details required: - code - message required: - id - ts - type - payload EngineStatusSnapshot: type: object description: A snapshot of the engine's current status properties: uptimeSeconds: type: number description: Engine uptime in seconds hasActiveSSHSessions: type: boolean description: Whether there are active SSH sessions activeSseClients: type: integer description: Number of active SSE client connections chatsTotal: type: integer description: Total number of chat sessions chatsProcessing: type: integer description: >- Number of chats currently doing work, including those running background/spawned-agent tasks reposTotal: type: integer description: Total number of repositories hooksRunning: type: boolean description: Whether hooks are currently running desktopReady: type: boolean description: >- Whether the sandbox's noVNC desktop port is accepting connections. The desktop stack boots after wake, so this can lag behind engine readiness. Absent on older engines that do not report it. required: - uptimeSeconds - hasActiveSSHSessions - activeSseClients - chatsTotal - chatsProcessing - reposTotal - hooksRunning EngineRepoState: type: object description: State of a repository within the engine properties: name: type: string description: Repository name path: type: string description: Filesystem path to the repository defaultBranch: type: string description: Default branch name (e.g. main) currentBranch: type: string description: Currently checked-out branch prUrls: type: array items: type: string format: uri description: >- All pull request URLs the workspace has opened in this repository. A single workspace may have multiple PRs in the same repo (e.g. after switching branches or opening follow-up PRs), so this is an array. Empty when no PRs have been observed. gitDiff: oneOf: - $ref: '#/components/schemas/EngineRepoDiff' - type: 'null' description: Git diff statistics, if available startHooksCompleted: type: boolean description: Whether start hooks have finished executing provider: type: string enum: - github - gitlab description: Code host for the repository's origin remote, when resolvable required: - name - path - defaultBranch - currentBranch - prUrls - gitDiff - startHooksCompleted EngineChatSummary: type: object description: Summary of a chat session as reported by the engine properties: id: type: string description: Unique chat session ID provider: type: string enum: - claude - codex - cursor - opencode - pi description: Coding agent provider title: type: string description: Chat title createdAt: type: string format: date-time description: When the chat was created updatedAt: type: string format: date-time description: When the chat was last updated processing: type: boolean description: >- Whether the chat is currently doing work — either processing a foreground message or running background/spawned-agent tasks awaitingInput: type: boolean description: >- The agent has issued an interactive tool call (e.g. ExitPlanMode, AskUserQuestion) and is paused until the user resolves it. `processing` stays true while this is true. parentChatId: type: - string - 'null' description: ID of the parent chat, if this is a sub-chat lastMessageText: type: - string - 'null' description: Preview of the most recent input message sent to this chat. required: - id - provider - title - createdAt - updatedAt - processing - parentChatId AgentEvent: description: >- A raw event from the coding agent, streamed as part of `chat.turn.delta` events. The shape depends on the coding agent provider. Use the `type` field to discriminate between Claude, Codex, Cursor, Opencode, and Pi events. oneOf: - $ref: '#/components/schemas/ClaudeAgentEvent' - $ref: '#/components/schemas/CodexAgentEvent' - $ref: '#/components/schemas/CursorAgentEvent' - $ref: '#/components/schemas/OpencodeAgentEvent' - $ref: '#/components/schemas/PiAgentEvent' discriminator: propertyName: type mapping: claude-assistant: $ref: '#/components/schemas/ClaudeAgentEvent' claude-user: $ref: '#/components/schemas/ClaudeAgentEvent' claude-result: $ref: '#/components/schemas/ClaudeAgentEvent' claude-system: $ref: '#/components/schemas/ClaudeAgentEvent' event_msg: $ref: '#/components/schemas/CodexAgentEvent' response_item: $ref: '#/components/schemas/CodexAgentEvent' cursor-assistant: $ref: '#/components/schemas/CursorAgentEvent' cursor-thinking: $ref: '#/components/schemas/CursorAgentEvent' cursor-tool_call: $ref: '#/components/schemas/CursorAgentEvent' cursor-task: $ref: '#/components/schemas/CursorAgentEvent' cursor-status: $ref: '#/components/schemas/CursorAgentEvent' cursor-error: $ref: '#/components/schemas/CursorAgentEvent' opencode-message.updated: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-session.idle: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-error: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-part-text: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-part-reasoning: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-part-tool: $ref: '#/components/schemas/OpencodeAgentEvent' pi-agent_start: $ref: '#/components/schemas/PiAgentEvent' pi-message_update: $ref: '#/components/schemas/PiAgentEvent' pi-tool_execution_start: $ref: '#/components/schemas/PiAgentEvent' pi-tool_execution_update: $ref: '#/components/schemas/PiAgentEvent' pi-tool_execution_end: $ref: '#/components/schemas/PiAgentEvent' pi-error: $ref: '#/components/schemas/PiAgentEvent' EnginePreviewPort: type: object description: A preview port forwarded from the replica properties: port: type: integer description: Local port number publicUrl: type: string format: uri description: Public URL for the preview createdAt: type: string format: date-time description: When the preview was created required: - port - publicUrl - createdAt Error: type: object properties: error: type: string description: Error message details: type: - string - 'null' description: Additional error details required: - error EngineRepoDiff: type: object description: Git diff statistics for a repository properties: added: type: integer description: Number of lines added removed: type: integer description: Number of lines removed fullDiff: type: string description: Full diff content required: - added - removed ClaudeAgentEvent: type: object description: >- A streaming event from the Claude Code agent. The `type` field is prefixed with `claude-` followed by the SDK message type. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string enum: - claude-assistant - claude-user - claude-result - claude-system description: >- Claude event type. `claude-assistant` contains model output (text, thinking, tool use). `claude-user` contains tool results. `claude-result` signals turn completion or errors. `claude-system` contains system-level messages. payload: $ref: '#/components/schemas/ClaudeEventPayload' required: - timestamp - type - payload CodexAgentEvent: type: object description: >- A streaming event from the Codex CLI agent. Uses either `event_msg` for high-level messages or `response_item` for structured response items. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string enum: - event_msg - response_item description: >- `event_msg` carries high-level messages (user input, reasoning). `response_item` carries structured responses (assistant messages, function calls, tool calls). payload: $ref: '#/components/schemas/CodexEventPayload' required: - timestamp - type - payload CursorAgentEvent: type: object description: >- A streaming event from the Cursor agent. Cursor events are normalized with a `cursor-` prefixed type and a provider payload. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string enum: - cursor-assistant - cursor-thinking - cursor-tool_call - cursor-task - cursor-status - cursor-error description: >- Cursor event type. `cursor-assistant` contains model output, `cursor-thinking` contains reasoning text, `cursor-tool_call` contains tool progress/results, `cursor-task` contains task updates, `cursor-status` contains run status, and `cursor-error` contains failure details. payload: type: object description: >- Cursor event payload. Shape depends on the parent event `type`; Cursor payload sub-shapes are not yet formally specified. additionalProperties: true required: - timestamp - type - payload OpencodeAgentEvent: type: object description: >- A streaming event from the Opencode agent. Opencode events are normalized with an `opencode-` prefixed type and an open provider payload. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string pattern: ^opencode- description: >- Opencode event type. Common values include `opencode-message.updated`, `opencode-session.idle`, `opencode-error`, and `opencode-part-*` events. payload: type: object description: >- Opencode event payload. Shape depends on the parent event `type`; Opencode payload sub-shapes are not yet formally specified. additionalProperties: true required: - timestamp - type - payload PiAgentEvent: type: object description: >- A streaming event from the Pi coding agent. Pi events expose session lifecycle, text and reasoning updates, tool execution, and errors. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string pattern: ^pi- description: >- Pi event type. Common values include pi-message_update, pi-tool_execution_start, pi-tool_execution_update, pi-tool_execution_end, and pi-error. payload: type: object description: Pi event payload. Shape depends on the parent event type. additionalProperties: true required: - timestamp - type - payload ClaudeEventPayload: type: object description: Payload of a Claude Code agent event, wrapping the Claude SDK message. properties: type: type: string description: Original SDK message type (e.g. `assistant`, `user`, `result`) subtype: type: string description: >- Present on `claude-result` events; `success` indicates a clean turn completion. Any other value (e.g. `error`) signals a failed turn even when `is_error` is false. parent_tool_use_id: type: - string - 'null' description: >- If this message is the result of a sub-agent tool call, the parent tool_use ID message: $ref: '#/components/schemas/ClaudeMessage' is_error: type: boolean description: >- Present on `claude-result` events; true if the turn ended with an error errors: type: array items: type: string description: >- Array of error messages, present on `claude-result` events when `is_error` is true additionalProperties: true CodexEventPayload: description: >- Payload of a Codex CLI agent event. Shape depends on the parent event `type`. oneOf: - $ref: '#/components/schemas/CodexEventMsgPayload' - $ref: '#/components/schemas/CodexResponseItemPayload' discriminator: propertyName: type mapping: user_message: $ref: '#/components/schemas/CodexEventMsgPayload' agent_reasoning: $ref: '#/components/schemas/CodexEventMsgPayload' message: $ref: '#/components/schemas/CodexResponseItemPayload' function_call: $ref: '#/components/schemas/CodexResponseItemPayload' function_call_output: $ref: '#/components/schemas/CodexResponseItemPayload' custom_tool_call: $ref: '#/components/schemas/CodexResponseItemPayload' custom_tool_call_output: $ref: '#/components/schemas/CodexResponseItemPayload' ClaudeMessage: type: object description: A Claude SDK message containing an array of content blocks. properties: content: type: array description: Ordered list of content blocks produced or consumed by the model. items: $ref: '#/components/schemas/ClaudeContentBlock' CodexEventMsgPayload: type: object description: Payload for `event_msg` events — high-level user or reasoning messages. properties: type: type: string enum: - user_message - agent_reasoning description: >- `user_message` for user input, `agent_reasoning` for the agent's chain-of-thought message: type: string description: User message text (present when type is `user_message`) text: type: string description: Reasoning text (present when type is `agent_reasoning`) required: - type CodexResponseItemPayload: type: object description: >- Payload for `response_item` events — structured items from the Codex response stream. oneOf: - type: object title: AssistantMessage description: A text message from the Codex agent. properties: type: type: string const: message role: type: string const: assistant content: type: array items: type: object properties: type: type: string const: output_text text: type: string description: The text content required: - type - text required: - type - role - content - type: object title: FunctionCall description: A function call by the Codex agent (shell commands, plan updates). properties: type: type: string const: function_call call_id: type: string description: >- Unique ID for this call, referenced by the corresponding `function_call_output` name: type: string enum: - shell - shell_command - exec_command - update_plan description: Function name arguments: type: string description: >- JSON-encoded arguments (e.g. `{"command": "ls -la"}` for shell commands, `{"plan": [...]}` for plan updates) required: - type - call_id - name - arguments - type: object title: FunctionCallOutput description: Output from a previously invoked function call. properties: type: type: string const: function_call_output call_id: type: string description: ID of the function_call this output corresponds to output: type: string description: >- Raw output string. For shell commands this may include exit codes and stdout/stderr. required: - type - call_id - output - type: object title: CustomToolCall description: A custom tool invocation (e.g. `apply_patch` for file edits). properties: type: type: string const: custom_tool_call call_id: type: string description: Unique ID for this call name: type: string description: Tool name (e.g. `apply_patch`) input: type: string description: Tool input (e.g. patch content for `apply_patch`) status: type: string enum: - in_progress - completed - failed description: Current execution status required: - type - call_id - name - input - type: object title: CustomToolCallOutput description: Output from a custom tool call. properties: type: type: string const: custom_tool_call_output call_id: type: string description: ID of the custom_tool_call this output corresponds to output: type: string description: JSON-encoded output with optional `metadata.exit_code` required: - type - call_id - output discriminator: propertyName: type ClaudeContentBlock: type: object description: A single content block within a Claude message. Discriminated by `type`. oneOf: - type: object title: TextBlock description: A text response from the model. properties: type: type: string const: text text: type: string description: The text content required: - type - text - type: object title: ThinkingBlock description: An extended-thinking block showing the model's reasoning. properties: type: type: string const: thinking text: type: string description: The thinking/reasoning content required: - type - text - type: object title: ToolUseBlock description: >- A tool invocation by the model (e.g. Bash, Edit, Write, Grep, Glob, Read, WebSearch, TaskCreate, Skill). properties: type: type: string const: tool_use id: type: string description: >- Unique ID for this tool use, referenced by subsequent tool_result blocks name: type: string description: >- Tool name (e.g. `Bash`, `Edit`, `Write`, `Read`, `Grep`, `Glob`, `WebSearch`, `TaskCreate`, `Skill`) input: type: object additionalProperties: true description: Tool-specific input parameters required: - type - id - name - input - type: object title: ToolResultBlock description: >- The result of a tool invocation, sent back to the model in `claude-user` events. properties: type: type: string const: tool_result tool_use_id: type: string description: ID of the tool_use block this result corresponds to content: description: >- Tool output — either a plain string or an array of text/image blocks. oneOf: - type: string - type: array items: type: object properties: type: type: string enum: - text - image text: type: string source: type: object properties: type: type: string media_type: type: string data: type: string description: Base64-encoded image data is_error: type: boolean description: Whether the tool execution resulted in an error required: - type - tool_use_id discriminator: propertyName: type responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' BadGateway: description: >- Bad gateway - The workspace is unreachable or returned an invalid response content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: >- Service unavailable - The service is temporarily overloaded or under maintenance content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: >- API key authentication. Obtain your API key from the Replicas dashboard under Organization → Settings → API Keys. ````