> ## 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.
# Get a plugin
> Returns one plugin from listPlugins by slug, with its bundled skills and every installation the caller sees.
Scope: `mcp:read`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/plugins/{slug}
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.
- 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: Plugins
description: >-
The plugin catalog (catalog connectors, custom MCP servers, native app
connectors): install, browser OAuth sign-in, bundled skills and per-Reason
settings. Never returns credentials.
- 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}/plugins/{slug}:
parameters:
- $ref: '#/components/parameters/orgId'
- name: slug
description: Plugin slug from listPlugins, stable across installs and uninstalls.
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 120
get:
tags:
- Plugins
summary: Get a plugin
description: >-
Returns one plugin from listPlugins by slug, with its bundled skills and
every installation the caller sees.
Scope: `mcp:read`
operationId: getPlugin
parameters:
- name: reason_id
in: query
required: false
schema:
type: string
format: uuid
description: >-
Also list this Reason's own installations in `accounts` (requires
access to the Reason).
responses:
'200':
description: The plugin.
content:
application/json:
schema:
$ref: '#/components/schemas/Plugin'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
security:
- reasonApiKey:
- mcp: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:
Plugin:
type: object
properties:
slug:
type: string
description: >-
Stable plugin identifier. Catalog plugins keep it across installs; a
custom server's slug comes from its URL.
name:
type: string
description: Display name.
description:
type: string
description: What this plugin does.
icon:
description: Icon URL, or null.
type:
- string
- 'null'
source:
type: string
enum:
- curated
- grok
- codex
- cursor
- devin
- custom
- native
description: >-
`curated` (Reason's catalog), a marketplace it was imported from
(`grok`, `codex`, `cursor`, `devin`), `custom` (an MCP server added
by URL) or `native` (a Reason-managed app connector).
auth_type:
type: string
enum:
- none
- oauth
- bearer
- api_key
- basic
- native
description: >-
How it authenticates: `oauth` browser sign-in,
`bearer`/`api_key`/`basic` credentials sent in `secrets`, `none` for
public tools, `native` for a Reason-managed app sign-in.
secret_names:
type: array
items:
type: string
description: >-
Credential names installPlugin accepts in `secrets` (for example
`MCP_API_KEY`); empty when none.
scope:
type: string
enum:
- personal
- organization
description: The scope installPlugin uses when `scope` is omitted.
supported_scopes:
type: array
items:
type: string
enum:
- personal
- organization
description: >-
Scopes it can be installed in for this workspace: `personal` (the
caller's own account) and/or `organization` (one shared connection).
connectable:
type: boolean
description: >-
Whether it can be installed from the API now; false when `setup`
explains what blocks it.
setup:
anyOf:
- $ref: '#/components/schemas/PluginSetup'
- type: 'null'
description: null when connectable; otherwise what blocks installation.
docs_url:
description: Documentation URL, or null.
type:
- string
- 'null'
website_url:
description: Provider website URL, or null.
type:
- string
- 'null'
verified:
type: boolean
description: Whether Reason verified this plugin's server.
bundled_skills:
type: array
items:
$ref: '#/components/schemas/PluginSkill'
description: Skills shipped with the plugin; empty when it has none.
installed:
type: boolean
description: Whether the caller sees at least one installation (`accounts`).
mcp_server_id:
description: >-
The caller's preferred MCP installation: their personal one, else
the workspace's. Null when not installed or native.
type:
- string
- 'null'
connection_state:
description: Health of the preferred installation, or null.
type:
- string
- 'null'
connection_checked_at:
description: When the preferred installation was last probed, or null.
type:
- string
- 'null'
accounts:
type: array
items:
$ref: '#/components/schemas/PluginAccount'
description: >-
Every installation the caller sees: personal, the workspace's, and
(with `reason_id`) the Reason's own, each with its signed-in
account.
required:
- slug
- name
- description
- icon
- source
- auth_type
- secret_names
- scope
- supported_scopes
- connectable
- setup
- docs_url
- website_url
- verified
- bundled_skills
- installed
- mcp_server_id
- connection_state
- connection_checked_at
- accounts
PluginSetup:
type: object
properties:
code:
type: string
description: >-
Machine-readable reason, for example `coming_soon`,
`provider_unavailable`, `oauth_client_missing`,
`connection_configuration_required`, `endpoint_required`.
owner:
type: string
description: 'Who can resolve it: `reason`, `provider` or `workspace`.'
message:
type: string
description: Human-readable explanation.
required:
- code
- owner
- message
PluginSkill:
type: object
properties:
slug:
type: string
description: >-
Stable skill selector within the plugin, for example `linear`. Pass
it in `skill_slugs`.
name:
type: string
description: Display name.
description:
type: string
description: 'One sentence: what the skill does.'
installed:
type: boolean
description: >-
Whether the skill is installed as a workspace skill in any scope the
caller sees (`installed_scopes`).
installed_scopes:
type: array
items:
type: string
enum:
- personal
- organization
description: >-
Scopes the skill is installed in: `personal` (the caller's own)
and/or `organization` (the workspace's).
required:
- slug
- name
- description
- installed
- installed_scopes
PluginAccount:
type: object
properties:
connection_id:
type: string
description: >-
The connection id: pass it with adapter `adapter` to
manageConnection, and as `mcp_server_id` (MCP) to uninstallPlugin or
startPluginSignIn.
adapter:
type: string
enum:
- mcp
- native
description: Connection adapter, as listConnections reports it.
mcp_server_id:
description: >-
The MCP server id (same as connection_id) for an MCP installation;
null for a native connector.
type:
- string
- 'null'
scope:
type: string
enum:
- personal
- organization
- reason
description: >-
`personal`: the caller's own; `organization`: the workspace's shared
one; `reason`: a Reason's own connection (listed with `reason_id`).
reason_id:
description: The Reason a `reason` scope connection belongs to.
type:
- string
- 'null'
account_id:
description: >-
Provider account id the sign-in resolved (OpenID subject, workspace
or team id), or null when unknown or not signed in.
type:
- string
- 'null'
account_name:
description: >-
Account label (email, workspace or team handle), or null when
unknown. Tells two accounts on one service apart.
type:
- string
- 'null'
connection_state:
description: >-
Cached health: `ready`, `needs_auth`, `offline`, `protocol_error`,
`disabled` or `unverified` (MCP); a native connector's own state.
Null when never probed.
type:
- string
- 'null'
connection_checked_at:
description: ISO timestamp of the last health probe.
type:
- string
- 'null'
connection_error_code:
description: Machine-readable reason of the current failure, when unhealthy.
type:
- string
- 'null'
enabled:
type: boolean
description: Whether the installation is enabled.
can_manage:
type: boolean
description: >-
Whether the caller may reconnect, update or uninstall this
installation.
reason_mode:
description: >-
A Reason's own connection: `member` (each member connects their own
account) or `shared`. Null otherwise.
oneOf:
- type: string
enum:
- member
- shared
- type: 'null'
required:
- connection_id
- adapter
- mcp_server_id
- scope
- reason_id
- account_id
- account_name
- connection_state
- connection_checked_at
- connection_error_code
- enabled
- can_manage
- reason_mode
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:
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.