> ## Documentation Index > Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt > Use this file to discover all available pages before exploring further. # Get an Agent > 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. ## OpenAPI ````yaml https://api.getarbol.com/openapi.json get /agents/{id} openapi: 3.1.2 info: contact: email: support@getarbol.com name: Arbol url: https://docs.getarbol.com description: >- Build and operate Arbol's organization-scoped conversational platform through one provider-neutral REST contract. Resources cover Agents, channels, contacts, conversations, Knowledge, connected accounts, analytics, and evaluation runs. Every bearer is verified by Auth0, every request is bound to exactly one Organization, and every operation enforces all scopes listed in its security requirement. title: Arbol API version: 1.0.0 servers: - description: Production url: https://api.getarbol.com/v1 security: [] tags: - description: >- Create and configure conversational Agents. Provider-specific runtime details remain private to Arbol. name: Agents - description: >- Define suites, start durable evaluation runs, inspect trials, and compare Agent behavior. name: Agent evaluations - description: >- Read organization-scoped operational aggregates without exposing raw provider telemetry. name: Analytics - description: >- Attach and manage provider-neutral voice or messaging endpoints owned by an Agent. name: Channels - description: >- Authorize and manage reusable organization accounts whose credentials remain in Composio. name: Connected accounts - description: >- Manage people, their routable identities, merged activity timeline, and durable CSV imports. name: Contacts - description: >- Start outbound calls and inspect tenant-scoped voice, WhatsApp, and web conversations. name: Conversations - description: >- Define revisioned structured fields used to capture organization-specific Contact and Conversation facts. name: Definitions - description: >- Call a list of phone numbers with one Agent, a few at a time, with optional first-message and prompt overrides. name: Outbound batches - description: >- Read and assert typed values against active Definitions with explicit evidence and verification state. name: Facts - description: >- Discover live business-tool capabilities available through Arbol's Composio boundary. name: Integrations - description: >- Upload, index, search, download, and lifecycle-manage organization Knowledge documents. name: Knowledge - description: Read and update the current Organization's product-level settings. name: Organization - description: >- Discover provider-neutral synthetic voices that can be assigned to voice Agents. name: Voices paths: /agents/{id}: get: tags: - Agents summary: Get an Agent description: >- 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. operationId: getAgent parameters: - in: path required: true name: id schema: $ref: '#/components/schemas/ArbolResourceId' - in: query name: expand schema: maxItems: 2 type: array items: type: string enum: - knowledge - toolAccess allowEmptyValue: true allowReserved: true explode: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgentOutput' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '400': description: >- Inferable validation failure or a non-inferable malformed transport request. content: application/json: schema: oneOf: - oneOf: - $ref: '#/components/schemas/BadRequest' - $ref: '#/components/schemas/UndefinedError' - $ref: '#/components/schemas/TransportBadRequestError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '401': description: Authentication is required. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Unauthorized' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '403': description: The caller is not allowed to perform this operation. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Forbidden' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '404': description: Agent not found content: application/json: schema: oneOf: - $ref: '#/components/schemas/NotFound' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' security: - userOAuth: - org:use - agents:read - machineOAuth: - agents:read components: schemas: ArbolResourceId: type: string maxLength: 64 pattern: >- ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ description: >- Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type. examples: - agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31 title: Arbol resource ID AgentOutput: type: object properties: createdAt: $ref: '#/components/schemas/IsoDatetime' description: anyOf: - type: string maxLength: 2000 - type: 'null' id: $ref: '#/components/schemas/ArbolResourceId' kind: $ref: '#/components/schemas/WorkerKind' language: type: string minLength: 2 maxLength: 16 name: $ref: '#/components/schemas/AgentName' profile: $ref: '#/components/schemas/AgentProfile' prompt: anyOf: - type: string maxLength: 65536 - type: 'null' status: $ref: '#/components/schemas/AgentStatus' timezone: anyOf: - $ref: '#/components/schemas/IanaTimeZone' - type: 'null' updatedAt: $ref: '#/components/schemas/IsoDatetime' isRunnable: type: boolean description: True when the Agent is active and its profile can take traffic. knowledgeDocumentIds: maxItems: 100 type: array items: $ref: '#/components/schemas/ArbolResourceId' toolAccess: $ref: '#/components/schemas/ToolAccessSnapshot' required: - createdAt - description - id - kind - language - name - profile - prompt - status - timezone - updatedAt - isRunnable additionalProperties: false title: Agent BadRequest: type: object properties: defined: const: true inferable: type: boolean code: const: BAD_REQUEST status: const: 400 message: type: string data: type: object properties: issues: maxItems: 20 type: array items: type: object properties: code: type: string enum: - custom - invalid_format - invalid_type - invalid_value - too_big - too_small - unrecognized_keys message: type: string maxLength: 500 path: maxItems: 16 type: array items: anyOf: - type: string maxLength: 120 - type: integer minimum: 0 maximum: 9007199254740991 required: - code - message additionalProperties: false truncated: type: boolean required: - issues - truncated additionalProperties: false required: - defined - inferable - code - status - message - data UndefinedError: type: object properties: defined: const: false inferable: type: boolean code: type: string status: type: number message: type: string data: {} required: - defined - inferable - code - status - message TransportBadRequestError: additionalProperties: false properties: code: const: BAD_REQUEST data: {} defined: const: false inferable: const: false message: type: string required: - defined - inferable - code - message type: object Unauthorized: type: object properties: defined: const: true inferable: type: boolean code: const: UNAUTHORIZED status: const: 401 message: type: string data: {} required: - defined - inferable - code - status - message Forbidden: type: object properties: defined: const: true inferable: type: boolean code: const: FORBIDDEN status: const: 403 message: type: string data: type: object properties: missingPermissions: maxItems: 10 type: array items: $ref: '#/components/schemas/AuthPermission' required: - missingPermissions additionalProperties: false required: - defined - inferable - code - status - message NotFound: type: object properties: defined: const: true inferable: type: boolean code: const: NOT_FOUND status: const: 404 message: type: string data: {} required: - defined - inferable - code - status - message IsoDatetime: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: ISO 8601 timestamp with an explicit UTC offset. examples: - '2026-08-29T14:30:00Z' title: ISO timestamp WorkerKind: type: string enum: - voice - messaging description: Runtime family implemented by an Agent. examples: - voice title: Agent kind AgentName: type: string minLength: 1 maxLength: 120 description: Customer-visible name of an Agent. examples: - Asistente de ventas title: Agent name AgentProfile: oneOf: - type: object properties: greeting: anyOf: - type: string minLength: 1 maxLength: 2000 - type: 'null' channelKind: type: string const: voice settings: type: object properties: availableLanguages: maxItems: 16 type: array items: type: string minLength: 2 maxLength: 16 conversationalBehavior: type: object properties: backgroundSound: default: null anyOf: - type: object properties: crossfadeLoop: default: true type: boolean presetId: default: office1 type: string enum: - office1 - office2 - restaurant - city - typing - elevator1 - elevator2 - elevator3 - elevator4 volume: default: 0.6 type: number minimum: 0.01 maximum: 1 required: - crossfadeLoop - presetId - volume additionalProperties: false - type: 'null' backgroundVoiceDetection: default: false type: boolean expressiveMode: default: false type: boolean interruptionIgnoreTerms: default: [] maxItems: 50 type: array items: type: string minLength: 1 maxLength: 64 keywords: default: [] maxItems: 50 type: array items: type: string minLength: 1 maxLength: 64 maxDurationMessage: default: null anyOf: - type: string maxLength: 500 - type: 'null' maxDurationSeconds: default: 600 type: integer exclusiveMinimum: 0 maximum: 7200 mergeDefaultIgnoreTerms: default: false type: boolean retranscribeOnTurnTimeout: default: false type: boolean silenceEndCallTimeoutSeconds: default: 20 type: number minimum: -1 maximum: 3600 speculativeTurn: default: false type: boolean spellingPatience: default: auto type: string enum: - auto - 'off' transcribeOnDisabledInterruptions: default: false type: boolean turnEagerness: default: normal type: string enum: - patient - normal - eager turnModel: default: turn_v3 type: string enum: - turn_v2 - turn_v3 turnTimeoutSeconds: default: 7 type: number minimum: -1 maximum: 600 required: - backgroundSound - backgroundVoiceDetection - expressiveMode - interruptionIgnoreTerms - keywords - maxDurationMessage - maxDurationSeconds - mergeDefaultIgnoreTerms - retranscribeOnTurnTimeout - silenceEndCallTimeoutSeconds - speculativeTurn - spellingPatience - transcribeOnDisabledInterruptions - turnEagerness - turnModel - turnTimeoutSeconds additionalProperties: false disableFirstMessageInterruptions: type: boolean greetingTranslations: maxItems: 16 type: array items: type: object properties: language: type: string minLength: 2 maxLength: 16 text: type: string maxLength: 2000 required: - language - text additionalProperties: false humanTransfers: anyOf: - maxItems: 10 type: array items: type: object properties: condition: type: string minLength: 1 maxLength: 2000 phoneNumber: $ref: '#/components/schemas/E164PhoneNumber' transferType: default: conference type: string enum: - conference - sip_refer required: - condition - phoneNumber - transferType additionalProperties: false - type: 'null' intelligence: type: object properties: backupLlm: default: mode: default order: [] type: object properties: mode: default: default type: string enum: - default - disabled - custom order: default: [] maxItems: 5 type: array items: type: string minLength: 1 maxLength: 128 required: - mode - order additionalProperties: false cascadeTimeoutSeconds: default: 4 type: number minimum: 2 maximum: 15 llm: default: gpt-5.6-luna type: string minLength: 1 maxLength: 128 maxTokens: default: -1 type: integer minimum: -1 maximum: 128000 parallelToolCalls: default: false type: boolean reasoningEffort: default: none anyOf: - type: string enum: - none - minimal - low - medium - high - xhigh - max - type: 'null' reasoningSummary: default: false type: boolean softTimeout: default: enabled: false message: '' seconds: 3 type: object properties: enabled: default: false type: boolean message: default: '' type: string maxLength: 500 seconds: default: 3 type: number minimum: 0.5 maximum: 30 required: - enabled - message - seconds additionalProperties: false temperature: default: 0.7 anyOf: - type: number minimum: 0 maximum: 2 - type: 'null' additionalProperties: false toolConfigs: maxItems: 5 type: array items: oneOf: - type: object properties: config: type: object properties: endCallDescription: type: string minLength: 1 maxLength: 2000 endCallReasons: maxItems: 4 type: array items: type: string enum: - farewell - task_complete - spam - asks_human additionalProperties: false isEnabled: type: boolean type: type: string const: END_CALL required: - config - isEnabled - type additionalProperties: false - type: object properties: config: type: object properties: onlyAtConversationStart: type: boolean additionalProperties: false isEnabled: type: boolean type: type: string const: LANGUAGE_DETECTION required: - config - isEnabled - type additionalProperties: false - type: object properties: config: type: object properties: {} additionalProperties: false isEnabled: type: boolean type: type: string const: SKIP_TURN required: - config - isEnabled - type additionalProperties: false - type: object properties: config: type: object properties: voicemailMessage: type: string minLength: 1 maxLength: 1000 additionalProperties: false isEnabled: type: boolean type: type: string const: VOICEMAIL_DETECTION required: - config - isEnabled - type additionalProperties: false - type: object properties: config: type: object properties: suppressTurnAfterDtmf: type: boolean useOutOfBandDtmf: type: boolean additionalProperties: false isEnabled: type: boolean type: type: string const: PLAY_KEYPAD_TOUCH_TONE required: - config - isEnabled - type additionalProperties: false voiceConfigs: maxItems: 16 type: array items: $ref: '#/components/schemas/VoiceConfigurationOutput' additionalProperties: false required: - greeting - channelKind - settings additionalProperties: false - type: object properties: greeting: anyOf: - type: string minLength: 1 maxLength: 2000 - type: 'null' channelKind: type: string enum: - web - whatsapp settings: type: object properties: documentUnderstandingEnabled: type: boolean imageUnderstandingEnabled: type: boolean inactivityFollowUpEnabled: type: boolean inactivityFollowUpMessage: anyOf: - type: string maxLength: 2000 - type: 'null' inactivityFollowUpMinutes: anyOf: - type: integer minimum: 1 maximum: 10080 - type: 'null' inactivityFollowUpTranslations: maxItems: 16 type: array items: type: object properties: language: type: string minLength: 2 maxLength: 16 text: type: string maxLength: 2000 required: - language - text additionalProperties: false model: anyOf: - type: string minLength: 1 maxLength: 256 pattern: ^@cf\/[a-z0-9_-]+\/[a-z0-9_.-]+$ - type: string const: dynamic/whatsapp-appointments - type: string const: openai/gpt-5.6-terra multiBubbleDelayMs: type: integer minimum: 250 maximum: 5000 multiBubbleEnabled: type: boolean multiBubbleMaxMessages: type: integer minimum: 2 maximum: 5 outboundAudioMode: type: string enum: - disabled - when_requested - match_input - always description: >- Voice-note policy: match_input asks the Agent to answer inbound audio with audio and text with text, while honoring an explicit format preference. WhatsApp synthesis uses ElevenLabs v3 and requires outboundVoice. Missing voice or synthesis failure falls back to text, never another speech provider. outboundVoice: anyOf: - $ref: '#/components/schemas/VoiceNoteConfigurationOutput' - type: 'null' description: >- Selected ElevenLabs v3 voice for WhatsApp voice notes, including language and stability. Use an available catalog voiceId. Omitted or null produces text instead of audio; a separate phone Agent's voice is never inherited automatically. Applies when outboundAudioMode permits audio. readReceiptsEnabled: type: boolean reasoningEffort: type: string enum: - none - low - medium - high - xhigh - max description: >- OpenAI messaging reasoning effort: none prioritizes response latency; low (the omitted default), medium, high, xhigh and max allocate progressively more reasoning. Applies only to openai/gpt-5.6-terra; other models keep their provider defaults. This is not a response-time guarantee or a delivery delay. replyButtonsEnabled: type: boolean replyListsEnabled: type: boolean sessionCloseAfterMinutes: anyOf: - type: integer minimum: 1 maximum: 10080 - type: 'null' sessionCloseEnabled: type: boolean textFirstMessageTranslations: maxItems: 16 type: array items: type: object properties: language: type: string minLength: 2 maxLength: 16 text: type: string maxLength: 2000 required: - language - text additionalProperties: false typingIndicatorEnabled: type: boolean additionalProperties: false required: - greeting - channelKind - settings additionalProperties: false description: Complete desired settings for one channel-specific Agent profile. title: Agent profile AgentStatus: type: string enum: - active - paused description: Customer-controlled lifecycle state of an Agent. examples: - active title: Agent status IanaTimeZone: type: string minLength: 1 maxLength: 120 description: Canonical IANA timezone name. examples: - America/Bogota title: IANA timezone ToolAccessSnapshot: type: object properties: entries: $ref: '#/components/schemas/ToolAccess' revision: type: integer minimum: 0 maximum: 9007199254740991 required: - entries - revision additionalProperties: false description: >- The Agent's current tool allowlist and the revision that guards its next replacement. title: Tool access snapshot AuthPermission: type: string enum: - agent-evaluations:read - agent-evaluations:run - agent-evaluations:write - agents:read - agents:write - analytics:read - arbi:use - channels:read - channels:write - contacts:read - contacts:write - conversations:read - conversations:transcript - conversations:write - definitions:read - definitions:write - facts:read - facts:write - integrations:read - integrations:write - knowledge:read - knowledge:write - org:manage - org:use description: >- One permission from the closed Arbol API vocabulary accepted from a verified Auth0 token. examples: - agents:read title: API permission E164PhoneNumber: type: string pattern: ^\+[1-9]\d{7,14}$ description: International telephone number in E.164 form. examples: - '+573001234567' title: E.164 phone number VoiceConfigurationOutput: type: object properties: label: anyOf: - type: string maxLength: 200 - type: 'null' language: type: string minLength: 2 maxLength: 16 settings: default: similarity: 0.8 speed: 1 stability: 0.5 type: object properties: similarity: type: number minimum: 0 maximum: 1 speed: type: number minimum: 0.7 maximum: 1.2 stability: type: number minimum: 0 maximum: 1 required: - similarity - speed - stability additionalProperties: false voiceId: type: string minLength: 1 maxLength: 256 required: - language - settings - voiceId additionalProperties: false description: One language's selected voice and bounded synthesis controls. title: Voice configuration VoiceNoteConfigurationOutput: type: object properties: language: type: string minLength: 2 maxLength: 16 voiceId: type: string minLength: 1 maxLength: 256 stability: default: 0.5 description: >- Eleven v3 delivery: 0 creative, 0.5 natural, 1 robust. Speed and similarity controls are not supported by this model. anyOf: - type: number const: 0 - type: number const: 0.5 - type: number const: 1 required: - language - voiceId - stability additionalProperties: false description: >- Explicit ElevenLabs v3 voice-note selection. No automatic inheritance from another Agent or fallback speech provider. title: Voice note configuration ToolAccess: maxItems: 50 type: array items: type: object properties: connectedAccountId: $ref: '#/components/schemas/ExternalIdentityId' maxLength: 256 tools: minItems: 1 maxItems: 50 type: array items: type: object properties: key: $ref: '#/components/schemas/ToolKey' required: - key additionalProperties: false required: - connectedAccountId - tools additionalProperties: false description: >- Complete account-qualified desired tool access, replaced atomically as one revision. title: Tool access ExternalIdentityId: type: string minLength: 1 maxLength: 512 description: >- Opaque identifier issued by an external authority; consumers compare it but do not interpret it. title: External identity ID ToolKey: type: string minLength: 1 maxLength: 200 pattern: ^[a-z0-9][a-z0-9._:-]*$ description: Stable provider-neutral action key derived from reviewed live discovery. examples: - google-calendar.create-event title: Tool key headers: RequestId: description: >- Opaque request correlation identifier. Include it when contacting Arbol support. schema: type: string maxLength: 128 securitySchemes: userOAuth: description: >- Organization-scoped Auth0 user access token issued to an approved first-party client or exchanged by a trusted OBO resource server. flows: authorizationCode: authorizationUrl: https://auth.getarbol.com/authorize scopes: agent-evaluations:read: Read Agent evaluation suites, runs, and results. agent-evaluations:run: Execute and cancel Agent evaluation runs. agent-evaluations:write: Create and update Agent evaluation suites. agents:read: Read Agents and their explicitly requested expansions. agents:write: Create, update, and delete Agents. analytics:read: Read organization analytics. arbi:use: Use the personal Arbi workspace. channels:read: Read Agent channels. channels:write: Create, update, authorize, and delete Agent channels. contacts:read: Read Contacts and their explicitly requested expansions. contacts:write: Create, update, merge, import, and delete Contacts. conversations:read: Read Conversation metadata. conversations:transcript: Read Conversation messages and media evidence. conversations:write: Create and process Conversations. definitions:read: Read Definitions and Definition usage. definitions:write: Create, update, and retire Definitions. facts:read: Read current and historical Facts. facts:write: Assert typed Facts. integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence. integrations:write: Authorize accounts and assign exact tool access. knowledge:read: Read Knowledge documents and search indexed content. knowledge:write: Create, index, update, and delete Knowledge documents. org:manage: Update the Organization and administer its members. org:use: Use Arbol as a member of the selected Auth0 Organization. tokenUrl: https://auth.getarbol.com/oauth/token type: oauth2 machineOAuth: description: >- Organization-bound Auth0 client-credentials token. The client grant must contain every operation scope. flows: clientCredentials: scopes: agent-evaluations:read: Read Agent evaluation suites, runs, and results. agent-evaluations:run: Execute and cancel Agent evaluation runs. agent-evaluations:write: Create and update Agent evaluation suites. agents:read: Read Agents and their explicitly requested expansions. agents:write: Create, update, and delete Agents. analytics:read: Read organization analytics. channels:read: Read Agent channels. channels:write: Create, update, authorize, and delete Agent channels. contacts:read: Read Contacts and their explicitly requested expansions. contacts:write: Create, update, merge, import, and delete Contacts. conversations:read: Read Conversation metadata. conversations:transcript: Read Conversation messages and media evidence. conversations:write: Create and process Conversations. definitions:read: Read Definitions and Definition usage. definitions:write: Create, update, and retire Definitions. facts:read: Read current and historical Facts. facts:write: Assert typed Facts. integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence. integrations:write: Authorize accounts and assign exact tool access. knowledge:read: Read Knowledge documents and search indexed content. knowledge:write: Create, index, update, and delete Knowledge documents. org:manage: Update the Organization and administer its members. tokenUrl: https://auth.getarbol.com/oauth/token type: oauth2 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.