> ## Documentation Index > Fetch the complete documentation index at: https://docs.revring.ai/llms.txt > Use this file to discover all available pages before exploring further. # Batch Get Agents > Fetch multiple agents by ID in a single request. Unknown IDs are omitted from the response. Maximum 100 IDs per request. ## OpenAPI ````yaml POST /agents/batch-get openapi: 3.1.0 info: title: RevRing Voice AI API description: >- RevRing Voice AI platform API for managing AI voice agents, phone calls, SIP trunks, and analytics. Build intelligent voice applications that can handle inbound and outbound phone calls with AI-powered conversational agents. version: 1.0.0 contact: name: RevRing Support url: https://revring.ai servers: - url: https://api.revring.ai/v1 description: Production API security: - apiKeyAuth: [] tags: - name: Messaging Connections description: Connect messaging providers so agents can send text messages - name: Messages description: Send text messages and read your message log - name: Conversations description: List and clear managed conversation threads - name: SIP Trunks description: Manage SIP trunks for connecting agents to the phone network - name: Agents description: Manage AI voice agents and their configuration - name: Agent Folders description: Organize agents into folders for dashboard navigation - name: Calls description: Manage and query phone calls - name: Analytics description: Get analytics and metrics about your calls - name: Knowledge Bases description: >- Manage knowledge bases and sources for agent retrieval-augmented generation - name: Test Suites description: Manage test suites, test cases, and test runs for agent evaluation - name: Voices description: Browse the voices available to your organization for agent speech paths: /agents/batch-get: post: tags: - Agents summary: Batch Get Agents description: >- Fetch multiple agents by ID in a single request. Unknown IDs are omitted from the response. Maximum 100 IDs per request. operationId: batchGetAgents requestBody: required: true content: application/json: schema: type: object required: - ids properties: ids: type: array description: Agent IDs to fetch items: type: string minItems: 1 maxItems: 100 minimal: type: boolean description: >- Return a compact representation, omitting prompt template, flow definition, variables, runtime config, custom tools, and knowledge bases default: false responses: '200': description: Matching agents content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Agent' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/BillingInactiveError' components: schemas: Agent: type: object description: AI Voice Agent configuration properties: messagingConnectionId: type: string nullable: true description: >- ID of the messaging connection this agent sends and receives texts through (see Messaging Connections). messagingConfig: $ref: '#/components/schemas/MessagingConfig' widgetKey: type: string nullable: true readOnly: true description: >- Public embed key for the website chat widget (starts with 'rrwk_'). Minted automatically the first time the widget is enabled. Read-only; it appears in the embed snippet you paste on your site. widgetConfig: $ref: '#/components/schemas/WidgetConfig' id: type: string format: uuid sipTrunkId: type: - string - 'null' format: uuid sipTrunk: type: object properties: friendlyName: type: string nullable: true folderId: type: string format: uuid nullable: true description: ID of the folder this agent belongs to, or null for uncategorized folder: type: object nullable: true description: Summary of the folder this agent belongs to properties: id: type: string format: uuid name: type: string color: type: string nullable: true name: type: string description: Agent name status: type: string enum: - active - disabled promptTemplate: type: string description: System prompt template with {{variable}} placeholders defaultVariables: type: object nullable: true description: Default template variables firstMessage: type: string nullable: true description: Agent's opening message firstMessageMode: type: string enum: - static - dynamic nullable: true description: >- How the agent opens the call. "static" speaks the first message text. "dynamic" generates the opening line from the agent's prompt. null uses the default behavior: speak the first message if set, otherwise wait for the caller. turnTimeoutSeconds: type: integer description: Seconds to wait for user response silenceEndCallTimeoutSeconds: type: integer description: Silence duration before ending call maxConversationDurationSeconds: type: integer description: Maximum call duration llmTemperature: type: number minimum: 0 maximum: 2 description: >- LLM temperature for response randomness (0 = deterministic, 2 = very creative) llmModel: type: string enum: - revring-standard - revring-max - revring-ultra description: >- Language model tier powering the agent. Usage is billed per minute at the tier's rate: revring-standard $0.03/min, revring-max $0.05/min, revring-ultra $0.065/min. Defaults to revring-standard. timezone: type: string description: IANA timezone identifier (e.g., America/New_York, Europe/London) language: type: string description: Language code (e.g., en, es, fr, de) preCallWebhookUrl: type: string format: uri nullable: true description: Webhook URL called before answering inbound calls postCallWebhookUrl: type: string format: uri nullable: true description: Webhook URL called after call ends with transcript and recording endCallEnabled: type: boolean description: Allow agent to end the call endCallRulesOverride: type: string nullable: true description: Custom instructions for when agent should end call transferEnabled: type: boolean description: Allow agent to transfer calls transferRoutes: type: array nullable: true description: Available transfer destinations with conditions items: type: object properties: to_number: type: string pattern: ^\+[1-9]\d{1,14}$ description: Transfer destination number (E.164) condition: type: string description: When to offer this transfer option extension: type: string pattern: ^[0-9*#w]+$ description: >- Optional touch-tone digits dialed after the call connects, to reach an extension behind a phone menu (e.g. "123#"). Allowed: 0-9, *, #, and w for a 0.5s pause. Warm transfers only. transferDescriptionOverride: type: string nullable: true description: Custom instructions for transfer feature voicemailEnabled: type: boolean description: Enable voicemail detection voicemailAction: type: string enum: - hangup - leave_message description: What to do when voicemail is detected voicemailMessage: type: string nullable: true description: >- Message to leave on voicemail (if action is leave_message). Supports {{variables}} like the prompt and first message. voiceId: type: string description: Voice ID (copy from dashboard Voice Library) voiceTemperature: type: number minimum: 0 maximum: 1 description: Voice expressiveness (0 = consistent, 1 = more varied). Default 0.7. voiceSpeed: type: number minimum: 0.5 maximum: 2 description: >- Speaking rate multiplier (0.5 = half speed, 2.0 = double speed). Default 1.0. voiceVolume: type: number minimum: -20 maximum: 20 description: Output level in decibels (-20 to 20; 0 = standard). Default 0. voiceTopP: type: number minimum: 0 maximum: 1 description: Advanced sampling range (0 to 1). Default 0.7. runtimeConfig: type: object nullable: true description: Advanced runtime configuration phoneNumbers: type: array description: Phone numbers assigned to this agent for inbound calls items: $ref: '#/components/schemas/AgentPhoneNumber' customTools: type: array description: Custom function calling tools available to this agent items: $ref: '#/components/schemas/AgentCustomTool' createdAt: type: string format: date-time updatedAt: type: string format: date-time mode: type: string enum: - single_prompt - conversation_flow description: >- Agent mode. Set at creation time and cannot be changed. `single_prompt` uses a single system prompt; `conversation_flow` uses a multi-step flow definition. flowDefinition: type: object nullable: true description: >- Conversation flow definition (only used when mode is `conversation_flow`) testVariables: type: object nullable: true description: Variables used for test calls initiated from the dashboard llmReasoningEffort: type: string enum: - low - medium - high description: >- Controls the reasoning effort of the language model. Higher values produce more thorough but slower responses. disableInterruptions: type: boolean description: >- When enabled, the agent will not be interrupted by the caller while speaking interruptionThresholdMs: type: integer minimum: 100 maximum: 2000 default: 500 description: >- Minimum speech duration (ms) before the caller's speech is registered as an interruption. Lower values make the agent easier to interrupt. Range: 100-2000, default 500. transferMode: type: string enum: - cold - warm description: >- Transfer mode. `cold` disconnects the AI before connecting to the destination. `warm` keeps the AI on the line to introduce the caller. warmTransferConfig: type: object nullable: true description: >- Configuration for warm transfers (only used when transferMode is `warm`) properties: holdMessage: type: string maxLength: 500 description: Message played to the caller while on hold holdMusicEnabled: type: boolean description: Whether to play hold music while the caller waits summaryPrompt: type: string maxLength: 2000 description: >- Prompt used to generate a conversation summary for the human agent introMessage: type: string maxLength: 500 description: >- Message the AI speaks to the human agent before connecting the caller continueRecordingAfterTransfer: type: boolean description: >- Keep recording after the warm handoff completes, so the recording also includes the human agent and caller conversation. playKeypadTouchToneEnabled: type: boolean description: >- Enable the keypad input (DTMF) tool, allowing callers to press phone keys during the conversation playKeypadTouchToneDescriptionOverride: type: string maxLength: 2000 nullable: true description: Custom instructions for the keypad input tool behavior knowledgeBaseRetrievalMode: type: string enum: - automatic - query_tool description: >- How the agent queries linked knowledge bases. `automatic` retrieves context on every turn. `query_tool` lets the agent decide when to search. knowledgeBaseChunks: type: integer minimum: 1 maximum: 20 description: Number of text chunks to retrieve per knowledge base query knowledgeBaseSimilarityThreshold: type: number minimum: 0 maximum: 1 description: >- Minimum similarity score for retrieved chunks (0-1). Higher values return only highly relevant results. required: - id - name - status - promptTemplate - createdAt - updatedAt MessagingConfig: type: object description: Per-agent messaging settings. A JSON object; set only the keys you need. properties: smsPrompt: type: string description: >- Optional instructions for composing text replies. If omitted, the agent uses its main prompt. Set it to give texting its own tone, separate from the call prompt. inboundMode: type: string enum: - auto_reply - notify description: >- What happens when someone texts in: 'auto_reply' (RevRing composes and sends a reply from smsPrompt) or 'notify' (RevRing forwards the message to inboundWebhookUrl and you send the reply). inboundWebhookUrl: type: string description: Where RevRing POSTs incoming texts when inboundMode is 'notify'. fromNumber: type: string description: >- Default sender number in E.164. If unset, the connection's Messaging Service chooses the sender. sendMessageEnabled: type: boolean description: Allow the agent to send a text during a live call. sendMessageDescriptionOverride: type: string description: Custom instructions for when and how the agent texts during a call. conversationIdleResetDays: type: integer description: >- Days of inactivity after which earlier conversation history is no longer used as reply context. Defaults to 30. WidgetConfig: type: object description: >- Per-agent website chat widget settings. A JSON object; set only the keys you need. Enabling the widget the first time mints a public embed key (returned as the read-only 'widgetKey' on the agent). properties: enabled: type: boolean description: >- Whether the website chat widget is live. When true, the widget loads on the allowed domains. modes: type: object description: >- Which interaction modes the widget offers. Chat is always on; voice is opt-in. properties: chat: type: boolean description: Text chat (always available; defaults to true). voice: type: boolean description: >- In-browser voice calls. Adds a call button to the widget. Defaults to false. continuity: type: object description: Continue-mode behaviors for voice widget calls. Both default true. properties: resumeCalls: type: boolean description: >- A voice call survives the visitor navigating to another page or reloading (it resumes the same call), and silently redials if it fully dropped. Default true. False = a navigation ends the call, like a normal phone call. sharedMemory: type: boolean description: >- Chat and voice share one visitor memory: a call knows the chat history and later chat knows the call. Default true. False = chat and voice stay separate. allowedDomains: type: array items: type: string description: >- Hostnames the widget may run on (e.g. 'www.example.com'). Subdomains are listed separately. Requests from any other origin are refused. webchatPrompt: type: string description: >- Optional instructions for composing web chat replies. If omitted, the agent uses its main prompt. Set it to give website chat its own tone, separate from calls and texting. appearance: type: object description: Visual customization for the widget. properties: position: type: string enum: - bottom-right - bottom-left - top-right - top-left description: Corner the launcher bubble sits in. Defaults to 'bottom-right'. accentColor: type: string description: >- Brand color as a 3- or 6-digit hex (e.g. '#1a56db'). Defaults to '#1a56db'. theme: type: string enum: - light - dark - auto description: >- Color theme. 'auto' follows the visitor's device. Defaults to 'auto'. launcherLabel: type: string description: Text on the launcher bubble. Defaults to 'Chat with us'. agentDisplayName: type: string description: Name shown in the chat header. Defaults to the agent's name. avatarUrl: type: string description: Image URL shown as the agent avatar. welcomeMessage: type: string description: Message shown when a visitor opens the chat for the first time. chatPlaceholder: type: string description: >- Placeholder text in the message input. Defaults to 'Type a message...'. limits: type: object description: Usage limits for the widget. properties: messagesPerDay: type: integer description: >- Maximum visitor messages answered per conversation per rolling day. Defaults to 300. AgentPhoneNumber: type: object properties: id: type: string format: uuid e164: type: string pattern: ^\+[1-9]\d{1,14}$ description: Phone number in E.164 format createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - e164 - createdAt - updatedAt AgentCustomTool: type: object description: Custom function calling tool for agents properties: id: type: string format: uuid name: type: string description: Tool name (used in function calls) webhookUrl: type: string format: uri description: Webhook URL to invoke enabled: type: boolean schema: type: object description: OpenAI function schema defining parameters createdAt: type: string format: date-time updatedAt: type: string format: date-time httpMethod: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method used when calling the webhook. Defaults to `POST`. headers: type: array nullable: true description: Custom HTTP headers to include in webhook requests items: $ref: '#/components/schemas/KeyValuePair' queryParams: type: array nullable: true description: Custom query parameters appended to the webhook URL items: $ref: '#/components/schemas/KeyValuePair' sendRawRequestBody: type: boolean description: >- When true, sends tool arguments directly as the request body instead of the default wrapper required: - id - name - webhookUrl - enabled - createdAt - updatedAt KeyValuePair: type: object description: A key-value pair properties: key: type: string description: Header or parameter name value: type: string description: Header or parameter value required: - key - value responses: BadRequestError: description: Invalid request parameters content: application/json: schema: type: object properties: error: type: string example: invalid_body details: type: object UnauthorizedError: description: Authentication required or API key invalid content: application/json: schema: type: object properties: error: type: string example: unauthorized BillingInactiveError: description: Subscription inactive or billing issue content: application/json: schema: type: object properties: error: type: string example: billing_inactive securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key for authentication. Generate API keys from the RevRing dashboard. ````