> ## 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. # Compact a session's context > Requires run. Summarizes the conversation so far to free context for the turns after it. The response's `outcome` says whether it was queued, applied, or not needed. Scope: `run` ## OpenAPI ````yaml /openapi.json post /v3/organizations/{orgId}/sessions/{sessionId}/compact 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: Devices description: >- Owned Mac and headless Device identity, bounded enrollment and root grants. - 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: Account description: Verify a key and resolve the organization it belongs to. - name: Feedback description: Report problems with the API or these docs to the Reason team. - name: Projects description: >- Retired in favour of Reasons. Existing workspace projects remain readable over REST. - name: Reasons description: >- A person's long-running agent conversations: their main Reason and named ones. Message a Reason by opening its conversation and sending to that Session. - name: Sessions description: >- A session is one run of an agent against a repository: it reproduces the task, writes the code, verifies it, and opens a pull request or merge request. - 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: Secrets description: >- Encrypted credentials injected into the agent's sandbox. Write-only: values can be set but never read back. - name: Knowledge description: >- Retired. Workspace notes and knowledge folders have been removed; every operation returns 410. - name: Memory description: >- Editable repository notes that are projected into native memory; generated memory remains read-only. - name: Skills description: >- Reusable instruction bundles Reason selects semantically from their descriptions for matching agent tasks. - name: Automations description: Recurring or one-time triggers that open sessions on a timetable. - name: Change Request Reviews description: >- Automated senior-engineer reviews posted on pull requests and merge requests. - 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: 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: Service Users description: Machine principals that own API keys for headless access. - name: Roles description: Role assignments that govern what each member can do. - name: Attachments description: >- Files uploaded to the organization and shared with sessions, downloaded via short-lived signed URLs. - name: Guardrails description: >- Per-repository automation limits and the violations recorded when a limit is hit. - name: MCP Servers description: >- Org-level Model Context Protocol servers exposed to the agent. Secret values are write-only. - name: Settings description: 'Organization configuration: namespaced settings and the run tag policy.' - name: Blueprints description: >- Read-only declarative manifests of an organization's agents (identity, run config, triggers, suite), with credentials redacted. - name: IP Access List description: >- Source-network allow-list that, when enabled, restricts the organization's API surface to a set of CIDR ranges. - name: Groups description: Manually-curated member groups carrying optional per-day resource limits. - name: Provider Credentials description: >- Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials for model providers. Secret values are write-only. paths: /v3/organizations/{orgId}/sessions/{sessionId}/compact: parameters: - $ref: '#/components/parameters/orgId' - name: sessionId description: >- The session id, returned as `session_id` by `createSession` and `listSessions`. in: path required: true schema: type: string post: tags: - Sessions summary: Compact a session's context description: >- Requires run. Summarizes the conversation so far to free context for the turns after it. The response's `outcome` says whether it was queued, applied, or not needed. Scope: `run` operationId: compactSession responses: '200': description: What the request did. content: application/json: schema: $ref: '#/components/schemas/SessionCompactionRequested' example: ok: true outcome: started '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- The Session's state does not allow this now; `error` says why (for example not_terminal while a turn runs). '429': $ref: '#/components/responses/RateLimited' '503': description: Product writes are disabled. security: - reasonApiKey: - run components: parameters: orgId: name: orgId in: path required: true description: Organization id or slug. Resolve it with `GET /v3/self`. schema: type: string schemas: SessionCompactionRequested: type: object properties: ok: type: boolean const: true description: Always true on success. outcome: type: string enum: - requested - queued - started - already_compacted - credit_exhausted description: >- What the request did: requested (the running turn compacts at its next step), queued (the queued turn compacts when it starts), started (a compaction now runs for the finished Session, or one already was), already_compacted (nothing new to compact, or the next turn starts compact), credit_exhausted (no usage left to compact). status: type: string const: requested description: >- Present when a running or queued turn was asked to compact (outcome requested or queued). detail: type: string description: >- Why, when the outcome is not plain: in_progress for a compaction already running, a reason for already_compacted (for example byok_no_model_call) or for credit_exhausted. required: - ok - outcome 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. responses: BadRequest: description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: prompt_required Unauthorized: description: Missing, invalid, or expired key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_bearer message: Authorization required Forbidden: description: The key lacks the required scope or role. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_scope required_scope: sessions:read NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: session_not_found 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 securitySchemes: reasonApiKey: type: http scheme: bearer bearerFormat: 'reason_ (legacy: ara_)' description: >- Your Reason API key from Settings > API. 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, knowledge:read, memory:read, memory:write, skills:read, skills: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. network:read and network:write are opt-in, excluded from default keys. 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.