> ## Documentation Index > Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Stream workspace events > A resumable Server-Sent Events stream (`text/event-stream`) of what happens in the workspace's Sessions, in the order it happened. Requires sessions:read. An Experiments feature (`workspace_events_api`): elsewhere it returns 403 `workspace_events_unavailable`. Event types: `message.created`, `turn.finished`. - `message.created`: a message was added to a Session (a person's prompt or follow-up, or a message Reason posted). `data`: `message_id`, `role`. Read it with listSessionConversation or listSessionMessages. - `turn.finished`: a turn of a Session ended. `data.status` is the Session's public status for that turn (`exit`, `error`, `cancelled`, ...). It is not the verdict: read the Session's `outcome` with getSession. Each event frame is `id: `, `event: `, `data: {"id", "type", "created_at", "session_id", "run_id", "data"}`. Events carry ids and states, never conversation content: read the content through the ordinary, access-checked operations. Resuming. `id` is the workspace's event sequence. Reconnect with the `Last-Event-ID` header (EventSource does this itself) or `?after=` and the stream first replays every retained event after it, then continues live. Without either it starts at the current end. Events are retained for 7 days: a cursor older than that gets a `reset` frame (`{"reason": "cursor_expired", "resume_after": ""}`), meaning events were lost, so re-read the views you show, then the stream continues from the oldest retained event. Ids increase but may skip numbers. Other frames: `hello` first (`{"after": "", "latest": "", "retention_seconds": n}`); `pulse` every 45 seconds while nothing arrives, and after events you may not see, carrying the stream's current `id` so a reconnect resumes past them; `error` before the server ends the stream because the key, its workspace, its IP access list or the account no longer admits the caller (`{"error": code, "message": text}`; reconnect only after fixing the cause); `reconnect` when the client should come back with its last id: `{"reason": "server_draining"}` when the server restarts, `{"reason": "auth_unavailable", "retry_ms": 5000}` when the key could not be re-checked for a few minutes. Visibility. An event about a Session reaches you only while the key's owner may read that Session through this API (its privacy, the Reason it is filed under, membership), checked when the event is sent, not when it happened. The credential is re-checked before any frame once 30 seconds have passed since the last check, and at every 45-second pulse. Scope: `sessions:read` ## OpenAPI ````yaml /openapi.json get /v3/organizations/{orgId}/events openapi: 3.1.0 info: title: Reason API version: 3.0.0 description: >- The Reason HTTP API. Drive cloud software-engineering agents: open sessions against your repositories, stream their work, and manage the secrets, skills, and automations they run with. Authenticate with a Reason API key sent as a bearer token. New keys use `reason_`; legacy `ara_` keys remain accepted. Every resource is scoped to an organization; resolve your `org_id` once with `GET /v3/self`. servers: - url: https://api.reasonmachines.com security: - reasonApiKey: [] tags: - name: Account description: Verify a key and resolve the organization it belongs to. - name: Reasons description: >- Start here. A Reason is the long-running agent a person keeps: their main Reason and named ones, each with its own instructions, default model and repositories, conversation, Loops and Sessions. Give a Reason work by messaging it (sendReasonMessage) and read its replies with listReasonMessages. - name: Loops description: >- Standing work a Reason does, woken by a schedule or an event: a webhook, a GitHub event or a Slack message. Each wake opens or continues a Session of the Reason; webhook events that share a correlation key continue one Session. - name: Memory description: >- What Reasons remember across Sessions. Each Session starts by reading MEMORY.md (a short index) and the list of topic notes, and reads a note when its topic comes up. `personal` memory belongs to one person (the API key's owner) and only their Sessions read it; `team` memory belongs to the Workspace and every member's Sessions read it. memory:read lists, reads and searches; memory:write writes and deletes, in team memory only for a Workspace owner or admin. - name: Sessions description: >- A Session is one run of work inside a Reason: every Reason message and Loop wake runs in one, and createSession starts one directly for a single unattended task with a pass/fail outcome. Its transcript, events, result and pull request are read here. - name: Skills description: >- Reusable instruction bundles Reason selects semantically from their descriptions for matching agent tasks. - name: Workspace events description: >- Follow a whole workspace without polling each Session. streamWorkspaceChanges is a Server-Sent Events stream of view revisions: when a topic's revision moves, re-read that view. streamWorkspaceEvents is a resumable Server-Sent Events stream of what happened (a message added, a turn finished), replayed from Last-Event-ID for 7 days. Event webhooks POST the same events, signed (Standard Webhooks), to endpoints you register. sessions:read reads; webhooks also need automations:read / automations:write; the devices topic also needs devices:read. An Experiments feature (workspace_events_api): elsewhere these return 403 `workspace_events_unavailable`. - name: Pages description: >- The HTML pages Reasons make: charts, dashboards and reports a person reads in the chat, opens full size, shares and finds in a Reason's Library. List and read the pages you may see, make one in a Reason's conversation or a Session, keep it current with updatePage (same id, link and share link, a new revision), share it and delete it. pages:read reads; pages:write writes. An Experiments feature (pages_api): elsewhere these return 403 `pages_api_unavailable`. - name: Secrets description: >- Encrypted credentials injected into the agent's sandbox. Write-only: values can be set but never read back. - name: Attachments description: >- Files uploaded to the organization and shared with sessions, downloaded via short-lived signed URLs. - name: Repositories description: Connected repositories, their indexing state, and generated wikis. - name: Git Connections description: Linked source-control accounts and the repositories they expose. - name: Machines description: >- Named Workspace queues served by headless workers. Sessions target a Machine by name and wait for a free worker; more workers serve more Sessions concurrently. - name: Devices description: >- Owned Mac and headless Device identity, bounded enrollment and root grants. - name: Cloud Access description: >- Keyless cloud sign-in for sessions: Reason's OIDC issuer facts and the AWS, Google Cloud and Azure connections a workspace trusts, including which run triggers each one signs in. - name: MCP Servers description: >- Org-level Model Context Protocol servers exposed to the agent. Secret values are write-only. - name: Change Request Reviews description: >- Automated senior-engineer reviews posted on pull requests and merge requests. - name: Consumption description: 'Billing-aligned usage: daily consumption and billing cycles.' - name: Metrics description: Aggregate analytics over sessions, change requests, and usage. - name: Audit Logs description: An append-only record of changes made within the organization. - name: Organizations description: The top-level tenant. Create, read, update, and delete organizations. - name: Members description: People in an organization and their pending invites. - name: Roles description: Role assignments that govern what each member can do. - name: Settings description: 'Organization configuration: namespaced settings and the run tag policy.' - name: Provider credentials description: >- Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials for model providers. Secret values are write-only. - name: Feedback description: Report problems with the API or these docs to the Reason team. - name: Projects description: >- Deprecated: a project is a Reason with the same id. Use the Reasons operations; these remain for existing clients. - name: Automations description: >- The older form of Loops. Prefer the Loops under a Reason (listReasonLoops, createReasonLoop), which take every wake: schedule, webhook, GitHub, Slack. Use these for what Loops do not carry yet: a run's MCP and app tools, and automations not filed under a Reason. paths: /v3/organizations/{orgId}/events: parameters: - $ref: '#/components/parameters/orgId' get: tags: - Workspace events summary: Stream workspace events description: >- A resumable Server-Sent Events stream (`text/event-stream`) of what happens in the workspace's Sessions, in the order it happened. Requires sessions:read. An Experiments feature (`workspace_events_api`): elsewhere it returns 403 `workspace_events_unavailable`. Event types: `message.created`, `turn.finished`. - `message.created`: a message was added to a Session (a person's prompt or follow-up, or a message Reason posted). `data`: `message_id`, `role`. Read it with listSessionConversation or listSessionMessages. - `turn.finished`: a turn of a Session ended. `data.status` is the Session's public status for that turn (`exit`, `error`, `cancelled`, ...). It is not the verdict: read the Session's `outcome` with getSession. Each event frame is `id: `, `event: `, `data: {"id", "type", "created_at", "session_id", "run_id", "data"}`. Events carry ids and states, never conversation content: read the content through the ordinary, access-checked operations. Resuming. `id` is the workspace's event sequence. Reconnect with the `Last-Event-ID` header (EventSource does this itself) or `?after=` and the stream first replays every retained event after it, then continues live. Without either it starts at the current end. Events are retained for 7 days: a cursor older than that gets a `reset` frame (`{"reason": "cursor_expired", "resume_after": ""}`), meaning events were lost, so re-read the views you show, then the stream continues from the oldest retained event. Ids increase but may skip numbers. Other frames: `hello` first (`{"after": "", "latest": "", "retention_seconds": n}`); `pulse` every 45 seconds while nothing arrives, and after events you may not see, carrying the stream's current `id` so a reconnect resumes past them; `error` before the server ends the stream because the key, its workspace, its IP access list or the account no longer admits the caller (`{"error": code, "message": text}`; reconnect only after fixing the cause); `reconnect` when the client should come back with its last id: `{"reason": "server_draining"}` when the server restarts, `{"reason": "auth_unavailable", "retry_ms": 5000}` when the key could not be re-checked for a few minutes. Visibility. An event about a Session reaches you only while the key's owner may read that Session through this API (its privacy, the Reason it is filed under, membership), checked when the event is sent, not when it happened. The credential is re-checked before any frame once 30 seconds have passed since the last check, and at every 45-second pulse. Scope: `sessions:read` operationId: streamWorkspaceEvents parameters: - in: query name: after schema: type: string description: >- Resume after this event id (an earlier frame's `id`); the `Last-Event-ID` header does the same. Omit both to start at the current end. responses: '200': description: >- The stream. It stays open until the client leaves, the server restarts (`reconnect` frame) or access ends (`error` frame). content: text/event-stream: schema: type: string description: >- Server-Sent Events: `hello`, then event frames, `pulse`, `reset`, and finally `error` or `reconnect`. '400': description: >- `after` or `Last-Event-ID` is not a non-negative integer (`invalid_request`). '401': $ref: '#/components/responses/Unauthorized' '403': description: >- sessions:read is missing, or workspace_events_api is not on for this workspace (`workspace_events_unavailable`). '429': $ref: '#/components/responses/RateLimited' security: - reasonApiKey: - sessions:read components: parameters: orgId: name: orgId in: path required: true description: Organization id or slug. Resolve it with `GET /v3/self`. schema: type: string responses: Unauthorized: description: Missing, invalid, or expired key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_bearer message: Authorization required RateLimited: description: >- Too many requests. Retry after the number of seconds in the `Retry-After` response header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 required: true content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: rate_limited message: This API key exceeded its request-rate limit schemas: Error: type: object properties: error: oneOf: - type: string - type: object required: - type - message properties: type: type: string message: type: string request_id: type: - string - 'null' message: type: string required_scope: type: string description: >- The capability required when the request was denied for a missing scope. securitySchemes: reasonApiKey: type: http scheme: bearer bearerFormat: 'reason_ (legacy: ara_)' description: >- Your Reason API key from Settings › API keys. New keys use `reason_`; legacy `ara_` keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, devices:read, devices:write, devices:use, computers:read, computers:write, ssh:write, knowledge:read, memory:read, memory:write, skills:read, skills:write, pages:read, pages:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. devices:write, devices:use, computers:read, computers:write, ssh:write, network:read and network:write are opt-in, excluded from default keys. computers:read lists visible cloud and connected computers without waking them or granting execution access. devices:read discovers local Device targets; devices:use separately consents to local execution, so a discover-and-run local workflow needs both. devices:write manages enrollment and device grants; computers:write creates or deletes cloud computers; ssh:write manages retained SSH access. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.