> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # List an agent's versions > The open draft first, if there is one, then published versions newest first. Paginated: pass `pagination.nextCursor` as `after` for the next page. ## OpenAPI ````yaml /api-reference/openapi.documented.json get /v1/agent/{agentId}/versions openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Phone Number - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Analytics - name: Dashboard - name: Benchmark - name: Health - name: Prospect Simulation paths: /v1/agent/{agentId}/versions: get: tags: - Agent summary: List an agent's versions description: >- The open draft first, if there is one, then published versions newest first. Paginated: pass `pagination.nextCursor` as `after` for the next page. operationId: getV1AgentByAgentIdVersions parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 50 default: 20 - in: query name: after schema: type: string format: uuid - schema: type: string in: path name: agentId required: true responses: '200': description: The agent's versions. content: application/json: schema: $ref: '#/components/schemas/ListAgentVersionsResponse' '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const agentVersions = await client.agentVersion.list('agentId'); console.log(agentVersions.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) agent_versions = client.agent_version.list( agent_id="agentId", ) print(agent_versions.data) components: schemas: ListAgentVersionsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/AgentVersionResponse' pagination: type: object properties: total: type: number description: Total number of items hasMore: type: boolean description: Whether there are more items to fetch nextCursor: type: - string - 'null' description: Cursor for the next page of items required: - total - hasMore - nextCursor required: - data - pagination ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message AgentVersionResponse: type: object properties: id: type: string format: uuid agentId: type: string format: uuid status: type: string enum: - DRAFT - PUBLISHED - DISCARDED description: DRAFT while being edited, PUBLISHED once it has been live. versionNumber: type: - integer - 'null' description: v1, v2, ... assigned on publish; null on a draft. revision: type: integer description: >- Increases with every edit to a draft. Send it back as expectedRevision when you publish. baseVersionId: type: - string - 'null' format: uuid description: The published version a draft started from. restoredFromVersionId: type: - string - 'null' format: uuid description: Set when this version restores an older one. summary: type: - string - 'null' description: What changed, written on publish. createdByType: type: string enum: - USER - API - CONFIG - AUTOIMPROVE - INTEGRATION - SYSTEM createdById: type: - string - 'null' format: uuid publishedAt: type: - string - 'null' description: ISO 8601. publishedByType: type: - string - 'null' enum: - USER - API - CONFIG - AUTOIMPROVE - INTEGRATION - SYSTEM publishedById: type: - string - 'null' format: uuid createdAt: type: string description: ISO 8601. updatedAt: type: string description: ISO 8601. modalities: type: array items: type: string enum: - call - chat description: Whether the agent takes calls, chats, or both. language: type: - string - 'null' description: ISO 639-1, e.g. en. firstMessageMode: type: - string - 'null' enum: - SPEAK_TEXT - PLAY_AUDIO - WAIT_FOR_CALLER firstMessage: type: - string - 'null' description: What the agent says first, with firstMessageMode SPEAK_TEXT. firstMessageAudioUrl: type: - string - 'null' description: The audio a call opens with, with firstMessageMode PLAY_AUDIO. llmProvider: type: - string - 'null' enum: - OPENAI - ANTHROPIC - GOOGLE - XAI - ULTRAVOX - AWS - ELEVENLABS llmModel: type: - string - 'null' description: Any model id the provider accepts. One model serves every speaker. llmTemperature: type: - number - 'null' description: 0 to 2. llmMaxTokens: type: - integer - 'null' llmBackendModel: type: - string - 'null' description: 'OpenAI Live models only: the text model they delegate to.' llmVoice: type: - string - 'null' description: 'Speech-to-speech models only: the model''s own voice.' sttProvider: type: - string - 'null' enum: - DEEPGRAM - OPENAI_WHISPER - SPEECHMATICS - ASSEMBLYAI - ELEVENLABS sttModel: type: - string - 'null' sttKeyterms: type: array items: type: string description: Words and phrases the transcriber should listen for. sttSmartFormat: type: - boolean - 'null' sttEndpointingMs: type: - integer - 'null' sttTurnDetection: type: - string - 'null' enum: - pipeline - provider interruptionMode: type: - string - 'null' enum: - ALLOW - BLOCK vadStartSecs: type: - number - 'null' vadStopSecs: type: - number - 'null' callMaxDurationSeconds: type: - integer - 'null' callSilenceTimeoutSeconds: type: - integer - 'null' idleTimeoutSeconds: type: - integer - 'null' idleMaxCount: type: - integer - 'null' idleMessages: type: array items: type: string endDetectionPhrases: type: array items: type: string description: >- Phrases that end the call when the caller says them, matched anywhere in what they say. endDetectionReasons: type: array items: type: string description: When the agent may decide to end the call itself. endCallGoodbyeMessage: type: - string - 'null' backgroundNoise: type: - string - 'null' enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - CONSTRUCTION - CRYING_BABY - DRIVING - LIBRARY - OFFICE - THUNDERSTORM - TRAIN description: A background preset. backgroundNoiseUrl: type: - string - 'null' description: A custom background recording, instead of a preset. backgroundNoiseVolume: type: - number - 'null' description: 0 to 1. chatMaxDurationSeconds: type: - integer - 'null' chatInactivityTimeoutSeconds: type: - integer - 'null' subAgents: type: array items: $ref: '#/components/schemas/AgentVersionSubAgent' description: >- The main agent (key `main`) first, then the sub-agents it can hand the call to. issues: type: array items: $ref: '#/components/schemas/AgentVersionIssue' description: >- Why this version cannot run; empty when it can be published. Returned when reading one version. required: - id - agentId - status - versionNumber - revision - baseVersionId - restoredFromVersionId - summary - createdByType - createdById - publishedAt - publishedByType - publishedById - createdAt - updatedAt - modalities - language - firstMessageMode - firstMessage - firstMessageAudioUrl - llmProvider - llmModel - llmTemperature - llmMaxTokens - llmBackendModel - llmVoice - sttProvider - sttModel - sttKeyterms - sttSmartFormat - sttEndpointingMs - sttTurnDetection - interruptionMode - vadStartSecs - vadStopSecs - callMaxDurationSeconds - callSilenceTimeoutSeconds - idleTimeoutSeconds - idleMaxCount - idleMessages - endDetectionPhrases - endDetectionReasons - endCallGoodbyeMessage - backgroundNoise - backgroundNoiseUrl - backgroundNoiseVolume - chatMaxDurationSeconds - chatInactivityTimeoutSeconds - subAgents description: >- One version of a Roark-hosted agent's configuration. Null settings use the runtime default. AgentVersionSubAgent: type: object properties: key: type: string description: '`main` for the main agent; otherwise letters, digits, `_` or `-`.' name: type: - string - 'null' description: How the agent refers to this speaker. systemPrompt: type: - string - 'null' description: The speaker's prompt. isInitial: type: boolean description: The call opens as this sub-agent instead of the main agent. ttsProvider: type: - string - 'null' enum: - CARTESIA - ELEVENLABS - OPENAI - RIME ttsModel: type: - string - 'null' ttsVoiceId: type: - string - 'null' description: Any voice id the provider accepts, including your own voices. ttsSpeed: type: - number - 'null' description: 0.5 to 2. ttsStability: type: - number - 'null' description: 0 to 1, ElevenLabs. ttsSimilarityBoost: type: - number - 'null' description: 0 to 1, ElevenLabs. tools: type: array items: $ref: '#/components/schemas/AgentVersionTool' handoffs: type: array items: $ref: '#/components/schemas/AgentVersionHandoff' required: - key - name - systemPrompt - isInitial - ttsProvider - ttsModel - ttsVoiceId - ttsSpeed - ttsStability - ttsSimilarityBoost - tools - handoffs description: >- A speaker in the conversation. On a sub-agent, null voice settings use the main agent's. AgentVersionIssue: type: object properties: field: type: string description: The setting the issue is about. message: type: string required: - field - message description: Something that stops a version from running. AgentVersionTool: type: object properties: toolDefinitionId: type: string format: uuid pinnedVersion: type: - integer - 'null' description: >- The tool version the agent runs; null runs the tool's latest declared version. required: - toolDefinitionId - pinnedVersion AgentVersionHandoff: type: object properties: to: type: string description: The key of the sub-agent that takes over; `main` for the main agent. description: type: string description: When to hand off, in the words the model is given. once: type: boolean description: At most once per call. history: type: string enum: - SHARED - NONE description: >- SHARED: the new speaker hears the conversation so far. NONE: it starts fresh. note: type: - string - 'null' description: >- Added to the new speaker's prompt at the handoff, such as a warm-transfer brief. required: - to - description - once - history - note securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.