# Arbol

> Build and operate Arbol agents through the REST API and MCP.

- [Arbol developer documentation](https://docs.getarbol.com/introduction.md): Use the Arbol API and MCP to work with organization-scoped agents, conversations, contacts, knowledge, and integrations.
- [Quickstart](https://docs.getarbol.com/quickstart.md): Discover the production API base URL and make your first authenticated Arbol request.
- [Organizations and authority](https://docs.getarbol.com/concepts/organizations.md): Understand how Arbol binds identities, permissions, and resources to one organization.
- [Pagination](https://docs.getarbol.com/guides/pagination.md): Traverse Arbol collections with opaque forward cursors without skipping or duplicating pages.
- [Errors](https://docs.getarbol.com/guides/errors.md): Handle Arbol API errors, validation details, authorization failures, and request correlation.
- [Retries and idempotency](https://docs.getarbol.com/guides/retries-and-idempotency.md): Retry Arbol API operations without duplicating calls, facts, contacts, or provider mutations.
- [Contacts](https://docs.getarbol.com/guides/contacts.md): Search, read, import, and merge organization contacts through the consolidated Contacts API.
- [Uploads and downloads](https://docs.getarbol.com/guides/uploads-and-downloads.md): Move private object bytes through short-lived capabilities while keeping API authority tenant-scoped.
- [API reference overview](https://docs.getarbol.com/api-reference/overview.md): How the Arbol REST reference is generated and how to use the production OpenAPI contract.
- [Authentication](https://docs.getarbol.com/api-reference/authentication.md): Authenticate to the organization-scoped Arbol API with the security scheme declared by OpenAPI.
- [List Agents](https://docs.getarbol.com/api-reference/endpoints/agents/list-agents.md): Lists Agents in the verified Organization under agents:read. It performs no writes and is safe to retry with the same cursor and filters.
- [Create an Agent](https://docs.getarbol.com/api-reference/endpoints/agents/create-an-agent.md): Creates one coherent Agent desired state under agents:write and reconciles voice provider state before reporting success; its profile, Knowledge selection, and account-qualified tool access require their additional permissions when configured. No idempotency key exists, so confirm an uncertain respo…
- [Get an Agent](https://docs.getarbol.com/api-reference/endpoints/agents/get-an-agent.md): Returns one Agent from the verified Organization under agents:read. Knowledge and tool-access expansions require their additional read permissions; the operation is side-effect free and retry-safe.
- [Delete an Agent](https://docs.getarbol.com/api-reference/endpoints/agents/delete-an-agent.md): Soft-deletes one tenant-owned Agent under agents:write, then best-effort removes its voice runtime. Repeating the request may return not found, so confirm an uncertain response before retrying.
- [Update an Agent](https://docs.getarbol.com/api-reference/endpoints/agents/update-an-agent.md): Updates the current Agent desired state under agents:write with last-write-wins fields and reconciles voice provider state before reporting success; a supplied profile, Knowledge selection, or tool access replaces that complete part and may require additional permissions. Tool access keeps its own o…
- [Create an Agent Knowledge MCP session](https://docs.getarbol.com/api-reference/endpoints/agents/create-an-agent-knowledge-mcp-session.md): Issues a five-minute, read-only Streamable HTTP MCP capability for an active Agent in the verified Organization. Requires agents:read and knowledge:read. Use the returned token as Authorization: Bearer when calling the returned URL from an MCP client. It searches only the Agent's current assigned do…
- [Cancel an Agent evaluation run](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/cancel-an-agent-evaluation-run.md): Records a cancellation request under agents:read and agent-evaluations:run; running trials stop only at their durable boundary. A repeated request against a terminal run returns conflict, so inspect the returned state before retrying.
- [List Agent evaluation runs](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/list-agent-evaluation-runs.md): Lists immutable evaluation run records for one tenant-owned Agent under agent-evaluations:read. It has no side effects and is safe to retry with the same cursor and filters.
- [Start an Agent evaluation run](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/start-an-agent-evaluation-run.md): Under agents:read and agent-evaluations:run, snapshots the active suite, rubric calibration/promotion state, pricing policy, and current runnable Agent configuration before starting one durable run. Evidence types require their additional permissions, and stale blocking-rubric calibration fails admi…
- [Get an Agent evaluation run](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/get-an-agent-evaluation-run.md): Returns immutable run summary state under agent-evaluations:read and no trace payloads by default. Trial expansion additionally requires conversations:transcript for recorded inputs, integrations:read for mocked tools, and knowledge:read for Knowledge evidence. It is side-effect free and safe to ret…
- [List Agent evaluation suites](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/list-agent-evaluation-suites.md): Lists suite metadata and case counts under agent-evaluations:read; case bodies and evidence require the detail operation. It performs no writes and is safe to retry with the same cursor.
- [Create an Agent evaluation suite](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/create-an-agent-evaluation-suite.md): Creates one suite under agent-evaluations:write; recorded and tool-bearing cases require their additional evidence permissions, mocked tools require exact fixtures, and AI rubrics must begin advisory. Use the human-only promotion operation after golden-set calibration. No idempotency key exists, so…
- [Get an Agent evaluation suite](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/get-an-agent-evaluation-suite.md): Returns one suite under agent-evaluations:read; recorded-conversation cases additionally require conversations:transcript and mocked or tool-bearing cases require integrations:read. It performs no writes and is safe to retry.
- [Replace an Agent evaluation suite](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/replace-an-agent-evaluation-suite.md): Updates one suite under agent-evaluations:write at expectedRevision; supplied cases replace the complete array, evidence requires additional permissions, and generic replacement cannot create or preserve a blocking AI rubric. Use the human-only promotion operation after replacement. A successful rev…
- [Promote a calibrated AI rubric](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/promote-a-calibrated-ai-rubric.md): A human actor attests a bounded golden set. The API binds that evidence to the exact rubric and current judge configuration, versions it, and records an explicit blocking promotion in the suite revision.
- [Create an evaluation trace download capability](https://docs.getarbol.com/api-reference/endpoints/agent-evaluations/create-an-evaluation-trace-download-capability.md): Under agent-evaluations:read plus permissions required by the run evidence, issues a short-lived capability only for a retained, integrity-matched private trace. It does not mutate the run, and requesting another capability is safe.
- [Query a fact breakdown](https://docs.getarbol.com/api-reference/endpoints/analytics/query-a-fact-breakdown.md): Counts one conversation Definition's current Fact values over conversations started in the window, under analytics:read. It performs no writes and is safe to retry with the same body.
- [Query analytics](https://docs.getarbol.com/api-reference/endpoints/analytics/query-analytics.md): Returns only the requested tenant-scoped analytics sections under analytics:read and resolves their shared time window once. It performs no writes and is safe to retry with the same body.
- [Query retention cohorts](https://docs.getarbol.com/api-reference/endpoints/analytics/query-retention-cohorts.md): Counts weekly cohorts of first-time contacts and the later weeks they returned in, under analytics:read. It performs no writes and is safe to retry with the same body.
- [Assign the channel Agent](https://docs.getarbol.com/api-reference/endpoints/channels/assign-the-channel-agent.md): Attaches an Agent to a connected channel that has none, under agents:write and channels:write. It fails if the channel already has an Agent or the Agent has no live runtime for the channel kind.
- [Unassign the channel Agent](https://docs.getarbol.com/api-reference/endpoints/channels/unassign-the-channel-agent.md): Returns a connected channel to the unassigned pool under agents:write and channels:write. The provider endpoint is kept; the channel simply stops answering.
- [Authorize the Agent channel](https://docs.getarbol.com/api-reference/endpoints/channels/authorize-the-agent-channel.md): Issues a new short-lived setup capability for the named pending WhatsApp channel under agents:write and channels:write. It does not change the desired assignment, and requesting another capability safely supersedes the prior URL.
- [List channels](https://docs.getarbol.com/api-reference/endpoints/channels/list-channels.md): Lists every connected channel in the verified Organization under agents:read and channels:read, optionally only those assigned to one Agent. It performs no provider writes and is safe to retry with the same cursor.
- [Create the Agent channel](https://docs.getarbol.com/api-reference/endpoints/channels/create-the-agent-channel.md): Connects a carrier number, SIP trunk, or WhatsApp endpoint for the verified Organization under agents:write and channels:write. Omit agentId to connect it unassigned and attach an Agent later; several endpoints may route to the same Agent. Provider onboarding has no idempotency key, so confirm an un…
- [Get a channel](https://docs.getarbol.com/api-reference/endpoints/channels/get-a-channel.md): Reads one connected channel of the verified Organization by its own id under agents:read and channels:read. It performs no provider writes and is safe to retry.
- [Delete the Agent channel](https://docs.getarbol.com/api-reference/endpoints/channels/delete-the-agent-channel.md): Disconnects and retires the named channel under agents:write and channels:write. A repeat may return not found, so confirm an uncertain response before retrying.
- [Update the Agent channel](https://docs.getarbol.com/api-reference/endpoints/channels/update-the-agent-channel.md): Updates direction or display settings on the named channel under agents:write and channels:write, reconciling provider state. An unassigned channel cannot enable traffic. There is no idempotency key; inspect current state before replaying an uncertain request.
- [Get a representative Agent channel](https://docs.getarbol.com/api-reference/endpoints/channels/get-a-representative-agent-channel.md): Reads one representative provider-neutral channel of the named Agent under agents:read and channels:read. Use the organization channel list for the complete endpoint inventory. It performs no provider writes and is safe to retry.
- [Recover an existing WhatsApp channel](https://docs.getarbol.com/api-reference/endpoints/channels/recover-an-existing-whatsapp-channel.md): Recovers an already-connected WhatsApp number into the named channel under agents:write and channels:write. Verifies the number belongs to the authenticated Organization, requires an assigned active WhatsApp Agent, and configures the signed inbound webhook. A pending channel, including expired setup…
- [List Composio accounts](https://docs.getarbol.com/api-reference/endpoints/connected-accounts/list-composio-accounts.md): Lists the authenticated organization's connected accounts live from Composio. Arbol stores no account mirror.
- [Connect a Composio account](https://docs.getarbol.com/api-reference/endpoints/connected-accounts/connect-a-composio-account.md): Creates a Composio Connect Link for the authenticated organization. Arbol stores no account or authorization session.
- [Get a Composio account](https://docs.getarbol.com/api-reference/endpoints/connected-accounts/get-a-composio-account.md): Returns one Composio-owned account and optionally counts current Arbol permissions that reference it.
- [Delete a Composio account](https://docs.getarbol.com/api-reference/endpoints/connected-accounts/delete-a-composio-account.md): Deletes the account directly in Composio and removes its Arbol permissions.
- [List contacts](https://docs.getarbol.com/api-reference/endpoints/contacts/list-contacts.md): Lists Contact summaries in the verified Organization under contacts:read. The optional query searches names and identity addresses in the same cursor-paginated collection, replacing the former standalone search operation. It performs no writes and is safe to retry with the same cursor and filters.
- [Create a contact](https://docs.getarbol.com/api-reference/endpoints/contacts/create-a-contact.md): Creates one Contact and its supplied identities in the verified Organization under contacts:write. No idempotency key is accepted, so confirm an uncertain response before retrying.
- [Get a contact](https://docs.getarbol.com/api-reference/endpoints/contacts/get-a-contact.md): Returns one Contact together with a cursor page of its merged Conversation and Fact timeline under contacts:read and facts:read. Identity and current-Fact projections remain explicit expansions; timelineCursor and timelineLimit continue the embedded activity page without a second endpoint. The opera…
- [Delete a contact](https://docs.getarbol.com/api-reference/endpoints/contacts/delete-a-contact.md): Soft-deletes one tenant-owned Contact under contacts:write. A repeated request may return not found, so confirm an uncertain response before retrying.
- [Update a contact](https://docs.getarbol.com/api-reference/endpoints/contacts/update-a-contact.md): Updates one tenant-owned Contact under contacts:write; supplied identity and address arrays replace their complete sets. There is no idempotency key, so inspect current state before replaying an uncertain request.
- [Import contacts](https://docs.getarbol.com/api-reference/endpoints/contacts/import-contacts.md): Accepts an HTTPS URL for one CSV file plus an exact header-to-field mapper under contacts:write. A Cloudflare Workflow downloads at most 2 MB and 500 rows, validates every mapped Contact, and imports them durably with tenant-local phone, email, and document identity deduplication. The response only…
- [Merge contacts](https://docs.getarbol.com/api-reference/endpoints/contacts/merge-contacts.md): Atomically reattaches every tenant-owned reference to the primary Contact and retires the secondary under contacts:write. Repeating the completed merge may return not found; verify both Contacts before retrying.
- [List conversations](https://docs.getarbol.com/api-reference/endpoints/conversations/list-conversations.md): Lists Conversation summaries and Contact display projections in the verified Organization under conversations:read and contacts:read. It performs no writes and is safe to retry with the same cursor and filters.
- [Start an outbound conversation](https://docs.getarbol.com/api-reference/endpoints/conversations/start-an-outbound-conversation.md): Starts one outbound voice Conversation under conversations:write. Callers do not provide channelId: Agents validates the organization and Agent, prefers that Agent's active outbound voice channel, and otherwise uses the organization's enabled platform-managed global outbound line. Provider routing a…
- [Get a conversation](https://docs.getarbol.com/api-reference/endpoints/conversations/get-a-conversation.md): Returns one Conversation under conversations:read and channels:read. Messages, Facts, and participants require their additional permissions; the operation is side-effect free and retry-safe.
- [Delete a conversation](https://docs.getarbol.com/api-reference/endpoints/conversations/delete-a-conversation.md): Soft-deletes one tenant-owned Conversation under conversations:write. A repeated request may return not found, so confirm an uncertain response before retrying.
- [Update or close a conversation](https://docs.getarbol.com/api-reference/endpoints/conversations/update-or-close-a-conversation.md): Updates or closes one tenant-owned Conversation under conversations:write; supplied Contact and Agent references are revalidated in the same tenant. Closing a non-test web or WhatsApp chat first persists its runtime transcript, then starts title, summary and assessment processing asynchronously. Rep…
- [Download conversation media](https://docs.getarbol.com/api-reference/endpoints/conversations/download-conversation-media.md): Under conversations:read and conversations:transcript, authorizes one persisted private Agents object and returns a short-lived read capability. API never fetches provider bytes; issuing another capability is side-effect free and retry-safe.
- [List definitions](https://docs.getarbol.com/api-reference/endpoints/definitions/list-definitions.md): Lists revisioned Definitions in the verified Organization under definitions:read. It performs no writes and is safe to retry with the same cursor and filters.
- [Create a definition](https://docs.getarbol.com/api-reference/endpoints/definitions/create-a-definition.md): Creates one typed Definition and its complete option set in the verified Organization under definitions:write. No idempotency key is accepted, so confirm an uncertain response before retrying.
- [Get a definition](https://docs.getarbol.com/api-reference/endpoints/definitions/get-a-definition.md): Returns one tenant-owned Definition under definitions:read with explicitly requested options or usage. It is side-effect free and safe to retry.
- [Update or retire a definition](https://docs.getarbol.com/api-reference/endpoints/definitions/update-or-retire-a-definition.md): Updates one Definition under definitions:write using expectedRevision; supplied options replace the complete set and retirement is permanent. A successful request must not be blindly replayed because its revision is consumed.
- [List facts](https://docs.getarbol.com/api-reference/endpoints/facts/list-facts.md): Lists current or historical immutable Fact assertions in the verified Organization under facts:read. It performs no writes and is safe to retry with the same cursor and subject.
- [Assert a fact](https://docs.getarbol.com/api-reference/endpoints/facts/assert-a-fact.md): Appends an immutable assertion under facts:write; an unset value is an explicit tombstone and never deletes history. When supplied, the idempotencyKey and observedAt pair may be reused after an uncertain response to recover the same assertion.
- [Get an integration](https://docs.getarbol.com/api-reference/endpoints/integrations/get-an-integration.md): Returns one live-discovered integration under integrations:read without exposing provider identifiers or credentials. It performs no writes and is safe to retry.
- [List available integrations](https://docs.getarbol.com/api-reference/endpoints/integrations/list-available-integrations.md): Discovers provider-neutral business integrations live under integrations:read while excluding channel/runtime infrastructure. It stores nothing and is safe to retry subject to rate limits.
- [List integration tools](https://docs.getarbol.com/api-reference/endpoints/integrations/list-integration-tools.md): Lists current provider-neutral tools live from Composio under integrations:read. It stores nothing and is safe to retry subject to rate limits.
- [List knowledge documents](https://docs.getarbol.com/api-reference/endpoints/knowledge/list-knowledge-documents.md): Lists Knowledge document metadata and indexing state in the verified Organization under knowledge:read. It performs no ingestion work and is safe to retry with the same cursor and filters.
- [Create a knowledge document upload](https://docs.getarbol.com/api-reference/endpoints/knowledge/create-a-knowledge-document-upload.md): Under knowledge:write, creates pending metadata and returns a five-minute direct R2 PUT capability. A document-scoped Workflow expires an unused capability or validates, promotes, and indexes uploaded bytes; callers observe progress with Get a knowledge document. No create idempotency key exists, so…
- [Get a knowledge document](https://docs.getarbol.com/api-reference/endpoints/knowledge/get-a-knowledge-document.md): Returns one tenant-owned Knowledge document projection under knowledge:read without reading its source bytes. It is side-effect free and safe to retry.
- [Delete a knowledge document](https://docs.getarbol.com/api-reference/endpoints/knowledge/delete-a-knowledge-document.md): Soft-deletes one tenant-owned document under knowledge:write and schedules convergent object/index cleanup. Repeating the API request may return not found even while cleanup continues.
- [Update a knowledge document](https://docs.getarbol.com/api-reference/endpoints/knowledge/update-a-knowledge-document.md): Updates the display metadata or enabled state of one tenant-owned document under knowledge:write; source bytes are immutable. No idempotency key is accepted, so read current state before retrying an uncertain request.
- [Create a knowledge download capability](https://docs.getarbol.com/api-reference/endpoints/knowledge/create-a-knowledge-download-capability.md): Issues a short-lived direct read capability for completed source bytes under knowledge:read. It does not proxy the object or mutate document state, and requesting another capability is safe.
- [Reindex a knowledge document](https://docs.getarbol.com/api-reference/endpoints/knowledge/reindex-a-knowledge-document.md): Starts a document-scoped Workflow that upserts completed source bytes under knowledge:write and durably polls their index state. A later repeat starts another idempotent upsert.
- [Search knowledge documents](https://docs.getarbol.com/api-reference/endpoints/knowledge/search-knowledge-documents.md): Searches only the explicitly named ready documents under knowledge:read; text stays in the request body and never enters a URL. It stores no query or result state and is safe to retry subject to rate limits.
- [Get knowledge storage usage](https://docs.getarbol.com/api-reference/endpoints/knowledge/get-knowledge-storage-usage.md): Returns tenant-scoped Knowledge document counts and durable source-byte usage under knowledge:read. It performs no storage scan or mutation and is safe to retry.
- [Get the current organization](https://docs.getarbol.com/api-reference/endpoints/organization/get-the-current-organization.md): Returns product settings for the verified user's active Auth0 Organization. Machine actors cannot call it; it performs no identity-provider or database writes and is safe to retry.
- [Cancel an outbound batch](https://docs.getarbol.com/api-reference/endpoints/outbound-batches/cancel-an-outbound-batch.md): Stops dialing: pending recipients become cancelled, calls already in progress finish normally. Cancelling a finished batch returns 409.
- [List outbound batches](https://docs.getarbol.com/api-reference/endpoints/outbound-batches/list-outbound-batches.md): Lists the organization's outbound batches, newest first, with recipient counts by status. Side-effect free.
- [Create an outbound batch](https://docs.getarbol.com/api-reference/endpoints/outbound-batches/create-an-outbound-batch.md): Creates an outbound batch under conversations:write and starts dialing right away, at most five calls at a time per organization. Send up to 5000 recipients as JSON, or a csvUrl (https) to a CSV with a header row: phone_number (E.164) is required; name, first_message, prompt, and from_channel_id map…
- [Get an outbound batch](https://docs.getarbol.com/api-reference/endpoints/outbound-batches/get-an-outbound-batch.md): Returns one outbound batch with its recipient counts by status. Poll it to follow progress; GET /outbound-batches/{id}/recipients lists the people and how each call went.
- [List outbound batch recipients](https://docs.getarbol.com/api-reference/endpoints/outbound-batches/list-outbound-batch-recipients.md): Lists a batch's recipients in the order they were given, with status, attempts, next retry time, failure reason, the Conversation id once a call was placed, and that Conversation's success evaluation (outcome) once post-call analysis ran. Filter by status; GET /conversations/{id} has the transcript…
- [List voices](https://docs.getarbol.com/api-reference/endpoints/voices/list-voices.md): Returns bounded provider-neutral voice discovery to an authenticated Organization user under the baseline org:use grant. Provider identity and provider-only capabilities are not exposed; it stores nothing and is safe to retry subject to rate limits.
- [Preview a voice](https://docs.getarbol.com/api-reference/endpoints/voices/preview-a-voice.md): Synthesizes one short voice-selection sample for an authenticated Organization user under the baseline org:use grant. Audio is generated on demand, not persisted, and has no idempotency requirement; retrying may incur another provider synthesis.
- [Arbol MCP overview](https://docs.getarbol.com/mcp/overview.md): How the standalone Arbol MCP server turns the published OpenAPI contract into organization-scoped tools.
- [MCP failures and recovery](https://docs.getarbol.com/mcp/errors.md): Distinguish MCP authentication, protocol and tool failures, and recover without replaying an unsafe API mutation.
- [Connect MCP through Composio](https://docs.getarbol.com/mcp/composio.md): Prerequisites and verification steps for publishing the Arbol MCP server as a Composio Custom MCP toolkit.
- [MCP OAuth](https://docs.getarbol.com/mcp/oauth.md): The two-audience OAuth and on-behalf-of flow for an Arbol user calling API-backed MCP tools.

## OpenAPI Specs

- [openapi](https://api.getarbol.com/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.