> ## 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.
# List a session's pending input requests
> The requests the Session is waiting on a person for: questions the agent asked and request cards (secret, network_hosts, permission_rules and connection requests), including a copy of another Session's request shown in this Session (a Reason's conversation), which carries `origin`. Only pending requests are listed; read one in any state with getSessionInputRequest. `actions` says what this caller can do through the API; every other request is completed in the web app at `app_url`.
Scope: `sessions:read`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/sessions/{sessionId}/input-requests
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: 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}/sessions/{sessionId}/input-requests:
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
get:
tags:
- Sessions
summary: List a session's pending input requests
description: >-
The requests the Session is waiting on a person for: questions the agent
asked and request cards (secret, network_hosts, permission_rules and
connection requests), including a copy of another Session's request
shown in this Session (a Reason's conversation), which carries `origin`.
Only pending requests are listed; read one in any state with
getSessionInputRequest. `actions` says what this caller can do through
the API; every other request is completed in the web app at `app_url`.
Scope: `sessions:read`
operationId: listSessionInputRequests
responses:
'200':
description: Pending requests.
content:
application/json:
schema:
$ref: '#/components/schemas/InputRequestList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'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
schemas:
InputRequestList:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/InputRequest'
description: Pending requests, newest first.
required:
- items
InputRequest:
type: object
properties:
id:
type: string
description: >-
The request's id: a question's 64-character hex operation id, or a
request card's id (a UUID). A copy shown in a Reason's conversation
has its source request's id.
type:
type: string
enum:
- question
- secret
- network_hosts
- permission_rules
- installed_connector
- endpoint_connector
- registry_connector
- connector
- native_connector
- source_control
- device_plugin
- personal_connector_grant
status:
type: string
enum:
- pending
- answered
- moved_past
- cancelled
- withdrawn
- timed_out
- closed
- allowed
- declined
- applied
- completed
- expired
description: >-
pending: still waiting on a person. Questions: answered, moved_past
(a person's later message in the Session settled it without
answering it), cancelled, withdrawn (the agent took it back),
timed_out (its wait or decision timeout ended it) or closed (any
other end). network_hosts: allowed, declined, completed (every host
was allowed elsewhere) or expired. permission_rules: applied,
declined or expired. secret: completed (a value was saved and the
Session resumed), declined (its member's Not now) or expired. Other
connection types: completed (a connection resumed the Session),
expired (after their receipt or 24 hours) or closed (the Session was
cancelled or archived); their pending state is best effort, because
the server records no answer for them.
session_id:
type: string
description: The Session this copy is shown in.
asked_in_session_id:
type: string
description: The Session whose agent asked.
resumes_session_id:
type: string
description: The Session that continues once the request is completed.
for_user_id:
description: >-
The only member who may answer it (a question for one teammate, a
personal connection grant, a secret card); null when anyone who can
open the Session may.
type:
- string
- 'null'
requires_role:
description: 'owner_or_admin: only a workspace owner or admin can complete it.'
oneOf:
- type: string
enum:
- owner_or_admin
- type: 'null'
origin:
anyOf:
- $ref: '#/components/schemas/InputRequestOrigin'
- type: 'null'
created_at:
type: string
expires_at:
description: >-
When the request's signed receipt ends, or for a secret or
connection request without one the end of its 24-hour window; null
for a question and for a network_hosts or permission_rules card
without a receipt.
type:
- string
- 'null'
reason:
description: Why the agent asks, in its words.
type:
- string
- 'null'
label:
type: string
description: A short name for the request.
question:
anyOf:
- $ref: '#/components/schemas/InputRequestQuestion'
- type: 'null'
secret_request:
anyOf:
- $ref: '#/components/schemas/InputRequestSecret'
- type: 'null'
description: >-
type secret: the secret the agent asks for (its name and how it is
used), never a value.
network_hosts:
type:
- object
- 'null'
properties:
hosts:
type: array
items:
type: string
required:
- hosts
permission_rules:
type:
- object
- 'null'
properties:
changes:
type: array
items:
type: string
description: One line per proposed change.
required:
- changes
connector:
anyOf:
- $ref: '#/components/schemas/InputRequestConnector'
- type: 'null'
actions:
type: array
items:
type: string
enum:
- answer
- approve
- deny
- secret
- cancel
description: >-
What this caller can do with it through the API now. Only actions an
API route serves are listed: answer (a pending question this caller
may answer; answerSessionInputRequest), approve and deny (a
network_hosts or permission_rules request, for an owner or admin;
approve also on a network_hosts request that reads completed, to
record the answer), and cancel (the member's own secret request).
Empty when the request is settled or must be completed in the web
app: open app_url. A hint: every action checks again, so cancel on a
secret request whose Session has moved on since it was asked returns
409 input_request_not_waiting.
app_url:
type: string
description: The Session in the web app, where every request can be completed.
required:
- id
- type
- status
- session_id
- asked_in_session_id
- resumes_session_id
- for_user_id
- requires_role
- origin
- created_at
- expires_at
- reason
- label
- question
- secret_request
- network_hosts
- permission_rules
- connector
- actions
- app_url
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.
InputRequestOrigin:
type: object
properties:
session_id:
type: string
description: The Session that asked.
title:
description: That Session's title when the request was shown here.
type:
- string
- 'null'
reason_name:
description: The Reason whose conversation shows this copy.
type:
- string
- 'null'
required:
- session_id
- title
- reason_name
description: >-
Set on a copy of the request shown in a Reason's conversation (a request
card copied there, or a question relayed to the member it is for); null
on the asking Session's own request.
InputRequestQuestion:
type: object
properties:
wait_for_answer:
type: boolean
description: >-
True when the agent waits for the answer; false when it keeps
working and reads the answer later.
questions:
type: array
items:
type: object
properties:
header:
type: string
description: Short heading, up to 30 characters; may be empty.
question:
type: string
description: The question, up to 2000 characters.
multi_select:
type: boolean
description: Whether more than one option may be chosen.
options:
type: array
items:
type: object
properties:
label:
type: string
description: >-
The option's label (up to 60 characters); answer with it
or with your own words.
description:
type:
- string
- 'null'
required:
- label
- description
description: >-
Up to 8 suggested answers; a free-text answer is always
accepted.
required:
- header
- question
- multi_select
- options
description: Every question of the card, in order (at most 4).
decision_timeout:
type:
- object
- 'null'
properties:
assumption:
type: string
description: What the agent will assume if nobody answers in time.
at:
description: When it will assume it; null when not scheduled.
type:
- string
- 'null'
required:
- assumption
- at
computer_auth:
description: >-
Set when the question hands a sign-in on a computer to the person:
open app_url to do it.
type:
- object
- 'null'
properties:
target:
type: string
enum:
- cloud
- local_device
description: Which computer a person must sign in on before answering.
reason:
type:
- string
- 'null'
required:
- target
- reason
required:
- wait_for_answer
- questions
- decision_timeout
- computer_auth
InputRequestSecret:
type: object
properties:
name:
type: string
description: The secret's environment variable name.
label:
type:
- string
- 'null'
placeholder:
type:
- string
- 'null'
value_prefix:
description: The prefix a valid value starts with, when the agent knows it.
type:
- string
- 'null'
replace:
type: boolean
description: >-
True when a stored value of this name was rejected and a new one is
asked for.
broker_hosts:
type: array
items:
type: string
description: Hosts the agent proposed the value is used only for.
reason_id:
description: >-
The Reason the Session is filed under, where the value can be
stored.
type:
- string
- 'null'
reason_name:
type:
- string
- 'null'
reason_team:
type: boolean
required:
- name
- label
- placeholder
- value_prefix
- replace
- broker_hosts
- reason_id
- reason_name
- reason_team
InputRequestConnector:
type: object
properties:
provider:
description: 'native_connector: slack or infisical; source_control: github.'
type:
- string
- 'null'
slug:
type:
- string
- 'null'
server_id:
description: 'installed_connector: the saved connection to reconnect.'
type:
- string
- 'null'
plugin:
description: 'device_plugin: chrome or computer-use.'
type:
- string
- 'null'
description:
type:
- string
- 'null'
icon:
type:
- string
- 'null'
auth_type:
oneOf:
- type: string
enum:
- none
- oauth
- bearer
- type: 'null'
auth_scheme:
oneOf:
- type: string
enum:
- basic
- type: 'null'
fields:
type: array
items:
type: object
properties:
name:
type: string
label:
type: string
description:
type:
- string
- 'null'
required:
type: boolean
required:
- name
- label
- description
- required
description: >-
Credential fields the connection asks for; empty for OAuth and
keyless connections.
url:
type:
- string
- 'null'
documentation_url:
type:
- string
- 'null'
website_url:
type:
- string
- 'null'
registry_name:
type:
- string
- 'null'
registry_version:
type:
- string
- 'null'
repository:
description: 'source_control: the repository the agent needs.'
type:
- string
- 'null'
configure_url:
description: >-
source_control: the GitHub page where the App's repository access is
changed.
type:
- string
- 'null'
reconnect:
type: boolean
reason_id:
type:
- string
- 'null'
reason_name:
type:
- string
- 'null'
required:
- provider
- slug
- server_id
- plugin
- description
- icon
- auth_type
- auth_scheme
- fields
- url
- documentation_url
- website_url
- registry_name
- registry_version
- repository
- configure_url
- reconnect
- reason_id
- reason_name
description: >-
Display fields of a connection request (every type but question, secret,
network_hosts and permission_rules); a field a type does not use is
null.
responses:
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 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.