> ## 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: >- Provider-neutral API for creating and operating Arbol agents, contacts, conversations, channels, knowledge, integrations, and evaluations. Every request is bound to one Auth0 Organization. title: Arbol API version: 1.0.0 servers: - description: Production url: https://api.getarbol.com/v1 security: [] 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: 3 type: array items: type: string enum: - profiles - 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' prompt: anyOf: - type: string maxLength: 32000 - type: 'null' status: $ref: '#/components/schemas/AgentStatus' supportedChannelKinds: maxItems: 6 type: array items: $ref: '#/components/schemas/ChannelKind' timezone: anyOf: - $ref: '#/components/schemas/IanaTimeZone' - type: 'null' updatedAt: $ref: '#/components/schemas/IsoDatetime' isRunnable: type: boolean knowledgeDocumentIds: maxItems: 100 type: array items: $ref: '#/components/schemas/ArbolResourceId' profiles: maxItems: 3 type: array items: $ref: '#/components/schemas/AgentProfile' toolAccess: type: object properties: entries: $ref: '#/components/schemas/ToolAccess' revision: type: integer minimum: 0 maximum: 9007199254740991 required: - entries - revision additionalProperties: false required: - createdAt - description - id - kind - language - name - prompt - status - supportedChannelKinds - 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: message: type: string maxLength: 500 path: maxItems: 16 type: array items: anyOf: - type: string maxLength: 120 - type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - 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 - email - internal 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 AgentStatus: type: string enum: - active - paused description: Customer-controlled lifecycle state of an Agent. examples: - active title: Agent status ChannelKind: type: string enum: - voice - whatsapp - telegram - slack - email - web description: Conversation transport family. examples: - voice title: Channel kind IanaTimeZone: type: string minLength: 1 maxLength: 120 description: Canonical IANA timezone name. examples: - America/Bogota title: IANA timezone AgentProfile: oneOf: - type: object properties: enabled: type: boolean greeting: anyOf: - type: string minLength: 1 maxLength: 2000 - type: 'null' language: anyOf: - type: string minLength: 2 maxLength: 16 - 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_v2 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.4 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 id: $ref: '#/components/schemas/ArbolResourceId' runtimeStatus: anyOf: - $ref: '#/components/schemas/AgentRuntimeStatus' - type: 'null' required: - enabled - greeting - language - channelKind - settings - id - runtimeStatus additionalProperties: false - type: object properties: enabled: type: boolean greeting: anyOf: - type: string minLength: 1 maxLength: 2000 - type: 'null' language: anyOf: - type: string minLength: 2 maxLength: 16 - 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 multiBubbleDelayMs: type: integer minimum: 250 maximum: 5000 multiBubbleEnabled: type: boolean multiBubbleMaxMessages: type: integer minimum: 2 maximum: 5 outboundAudioMode: type: string enum: - disabled - when_requested - always readReceiptsEnabled: type: boolean 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 id: $ref: '#/components/schemas/ArbolResourceId' runtimeStatus: anyOf: - $ref: '#/components/schemas/AgentRuntimeStatus' - type: 'null' required: - enabled - greeting - language - channelKind - settings - id - runtimeStatus additionalProperties: false description: Persisted channel-specific Agent profile and its provider runtime state. title: Agent profile ToolAccess: maxItems: 50 type: array items: type: object properties: connectedAccountId: $ref: '#/components/schemas/ArbolResourceId' tools: minItems: 1 maxItems: 50 type: array items: type: object properties: approval: $ref: '#/components/schemas/ToolApproval' key: $ref: '#/components/schemas/ToolKey' required: - approval - key additionalProperties: false required: - connectedAccountId - tools additionalProperties: false description: >- Complete account-qualified desired tool access, replaced atomically as one revision. title: Tool access 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 AgentRuntimeStatus: type: string enum: - pending - active - error - revoked description: Applied runtime state of an Agent profile deployment. examples: - active title: Agent runtime status ToolApproval: type: string enum: - automatic - confirmationRequired description: Approval policy required before a granted tool may execute. examples: - confirmationRequired title: Tool approval ToolKey: type: string minLength: 1 maxLength: 200 pattern: ^[a-z][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 ````