> ## Documentation Index > Fetch the complete documentation index at: https://docs.terminaluse.com/llms.txt > Use this file to discover all available pages before exploring further. # List Versions > List all versions for an agent. Optionally filter by branch name or version status. Versions are ordered by deployed_at descending (most recent first). ## OpenAPI ````yaml openapi.json GET /agents/{namespace_slug}/{agent_name}/versions openapi: 3.1.0 info: title: Sb0 API version: 0.1.0 servers: [] security: [] paths: /agents/{namespace_slug}/{agent_name}/versions: get: tags: - Agents summary: List Versions for Agent description: |- List all versions for an agent. Optionally filter by branch name or version status. Versions are ordered by deployed_at descending (most recent first). operationId: agents_list_versions parameters: - in: path name: namespace_slug required: true schema: title: Namespace Slug type: string - in: path name: agent_name required: true schema: title: Agent Name type: string - description: >- Filter by branch name (e.g., 'main', 'feature/login'). If not provided, returns versions across all branches. in: query name: branch required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by branch name (e.g., 'main', 'feature/login'). If not provided, returns versions across all branches. title: Branch - description: Filter by version status in: query name: status required: false schema: anyOf: - $ref: '#/components/schemas/VersionStatus' - type: 'null' description: Filter by version status title: Status - description: Maximum versions to return in: query name: limit required: false schema: default: 20 description: Maximum versions to return maximum: 100 minimum: 1 title: Limit type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/VersionListResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error components: schemas: VersionStatus: description: Status of a version in its lifecycle. enum: - DEPLOYING - ACTIVE - FAILED - UNHEALTHY - DRAINING - RETIRED - ROLLED_BACK title: VersionStatus type: string VersionListResponse: description: Response for listing versions of a branch. properties: branch_id: anyOf: - type: string - type: 'null' description: Branch ID title: Branch Id total: description: Total count title: Total type: integer versions: description: List of versions items: $ref: '#/components/schemas/VersionResponse' title: Versions type: array required: - versions - total title: VersionListResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object VersionResponse: description: Full version details. properties: acp_type: $ref: '#/components/schemas/ACPType' description: Type of ACP server (sync or async) author_email: description: Commit author email title: Author Email type: string author_name: description: Commit author name title: Author Name type: string branch_id: description: Parent branch ID title: Branch Id type: string created_at: anyOf: - format: date-time type: string - type: 'null' description: Creation timestamp title: Created At deployed_at: description: When this version was deployed format: date-time title: Deployed At type: string failure_diagnostics: anyOf: - additionalProperties: type: string type: object - type: 'null' description: >- User-facing failure diagnostics with 'title', 'description', and 'action' fields title: Failure Diagnostics failure_reason: anyOf: - type: string - type: 'null' description: >- Classified failure reason when status is FAILED (e.g., 'image_pull_failed', 'crash_loop', 'scheduling_failed') title: Failure Reason git_branch: description: Git branch name title: Git Branch type: string git_hash: description: Git commit hash title: Git Hash type: string git_message: default: '' description: Git commit message title: Git Message type: string id: description: Version ID title: Id type: string image_expires_at: anyOf: - format: date-time type: string - type: 'null' description: When image expires (for rollback window) title: Image Expires At image_url: description: Container image URL title: Image Url type: string is_dirty: default: false description: Whether the commit had uncommitted changes title: Is Dirty type: boolean last_rollback_at: anyOf: - format: date-time type: string - type: 'null' description: Timestamp when this version was last rolled back TO title: Last Rollback At replicas: default: 0 description: Current pod count for this version title: Replicas type: integer retired_at: anyOf: - format: date-time type: string - type: 'null' description: When version was retired title: Retired At rollback_count: default: 0 description: Number of rollbacks to this version title: Rollback Count type: integer rolled_back_at: anyOf: - format: date-time type: string - type: 'null' description: Timestamp when this version was rolled back FROM title: Rolled Back At sdk_type: $ref: '#/components/schemas/SDKType' description: SDK type for agent runtime source_filesystem_id: anyOf: - type: string - type: 'null' description: Filesystem snapshot that can reopen this version in Agent Builder title: Source Filesystem Id status: $ref: '#/components/schemas/VersionStatus' description: Version lifecycle status updated_at: anyOf: - format: date-time type: string - type: 'null' description: Last update timestamp title: Updated At required: - id - branch_id - git_hash - git_branch - author_name - author_email - image_url - status - deployed_at - sdk_type - acp_type title: VersionResponse type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object ACPType: description: Type of ACP server. enum: - sync - async title: ACPType type: string SDKType: description: SDK type for agent runtime. enum: - claude_agent_sdk - codex_agent_sdk title: SDKType type: string ````