> ## 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 plugins
> Lists the plugin catalog: Reason's curated and imported marketplace connectors, the workspace's custom MCP servers and native app connectors. Each plugin has its auth method, supported scopes, bundled skills (with where each is installed) and every installation the caller sees in `accounts`, with its signed-in account and cached health. Never includes credentials or another member's personal installations.
Scope: `mcp:read`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/plugins
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:
parameters:
- $ref: '#/components/parameters/orgId'
get:
tags:
- Plugins
summary: List plugins
description: >-
Lists the plugin catalog: Reason's curated and imported marketplace
connectors, the workspace's custom MCP servers and native app
connectors. Each plugin has its auth method, supported scopes, bundled
skills (with where each is installed) and every installation the caller
sees in `accounts`, with its signed-in account and cached health. Never
includes credentials or another member's personal installations.
Scope: `mcp:read`
operationId: listPlugins
parameters:
- name: installed
in: query
required: false
schema:
type: string
enum:
- 'true'
- 'false'
description: Only installed (`true`) or not installed (`false`) plugins.
- name: source
in: query
required: false
schema:
type: string
enum:
- curated
- grok
- codex
- cursor
- devin
- custom
- native
description: Only plugins from this source.
- name: q
in: query
required: false
schema:
type: string
maxLength: 200
description: Case-insensitive search over slug, name and description.
- 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: Plugins.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginList'
'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:
PluginList:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Plugin'
required:
- items
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
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.
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
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.