> ## 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.
# Create a single-use benchmark workspace
> Creates an empty workspace for one trial, owned by the caller, with one scoped key. The parent pays for its usage: the workspace budget (rcus) is held on the parent's wallet and settled for actual consumption after retirement; internal parents are not charged and runs use the parent's connected provider accounts. It admits exactly one Session, created with mode ephemeral, and is retired at expiry or by the retire operation. Available only to enabled parent workspaces.
Scope: `org:write`
## OpenAPI
````yaml /openapi.json post /v3/organizations/{orgId}/ephemeral-workspaces
openapi: 3.1.0
info:
title: Reason Machines 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,
knowledge, 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: >-
Discover existing workspace projects to target when creating and listing
sessions.
- 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: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Knowledge
description: Durable notes the agent consults while it works.
- 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}/ephemeral-workspaces:
parameters:
- $ref: '#/components/parameters/orgId'
post:
tags:
- Organizations
summary: Create a single-use benchmark workspace
description: >-
Creates an empty workspace for one trial, owned by the caller, with one
scoped key. The parent pays for its usage: the workspace budget (rcus)
is held on the parent's wallet and settled for actual consumption after
retirement; internal parents are not charged and runs use the parent's
connected provider accounts. It admits exactly one Session, created with
mode ephemeral, and is retired at expiry or by the retire operation.
Available only to enabled parent workspaces.
Scope: `org:write`
operationId: createEphemeralWorkspace
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEphemeralWorkspace'
responses:
'200':
description: Replayed an identical request.
content:
application/json:
schema:
$ref: '#/components/schemas/EphemeralWorkspaceCreated'
example:
organization_id: 22222222-2222-4222-8222-222222222222
parent_organization_id: 11111111-1111-4111-8111-111111111111
reference: harbor-0b6c
expires_at: '2026-10-03T04:00:00.000Z'
retired_at: null
api_key: ara_illustrative
'201':
description: Created.
content:
application/json:
schema:
$ref: '#/components/schemas/EphemeralWorkspaceCreated'
example:
organization_id: 22222222-2222-4222-8222-222222222222
parent_organization_id: 11111111-1111-4111-8111-111111111111
reference: harbor-0b6c
expires_at: '2026-10-03T04:00:00.000Z'
retired_at: null
api_key: ara_illustrative
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: >-
The parent pays: it needs paid model access (or internal billing)
and enough RCU for the workspace budget.
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Ephemeral workspaces are not enabled for this workspace.
'409':
description: Reference conflict, retired workspace, or active limit reached.
'429':
$ref: '#/components/responses/RateLimited'
security:
- reasonApiKey:
- org:write
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
schemas:
CreateEphemeralWorkspace:
type: object
properties:
reference:
type: string
minLength: 1
maxLength: 200
pattern: ^[A-Za-z0-9._:-]+$
description: >-
Caller trial identifier. The same request replays the same workspace
and key; a different request with this reference conflicts.
ttl_minutes:
description: >-
Lifetime before the workspace is retired automatically. Defaults to
240.
type: integer
minimum: 5
maximum: 360
rcus:
description: >-
Workspace budget held on the parent's wallet and charged for actual
use after retirement. Decimal string, defaults to 30, maximum 300; 0
runs only on the parent's connected provider accounts (BYOK).
type: string
required:
- reference
EphemeralWorkspaceCreated:
type: object
properties:
organization_id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
parent_organization_id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
reference:
type: string
expires_at:
type: string
retired_at:
type:
- string
- 'null'
api_key:
type: string
description: >-
Key for the new workspace only. Scopes: run, sessions:read,
devices:read, devices:write, devices:use, deployment:read.
required:
- organization_id
- parent_organization_id
- reference
- expires_at
- retired_at
- api_key
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
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, automations:read,
automations:write, agent_auth:read. 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.