> ## Documentation Index > Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt > Use this file to discover all available pages before exploring further. # Get an agent deployment version ## OpenAPI ````yaml /openapi.yaml get /v1/agent-deployments/{deployment_id}/versions/{version_id} openapi: 3.1.0 info: title: Nullspace API version: 0.1.0 description: | Cloud machine platform for AI agents. Create on-demand microVMs, execute commands, manage files, automate desktop environments, and stream output over WebSocket. license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.13-215-85-171.sslip.io description: Private beta - url: https://nullspace.example description: Self-hosted single-host owned-domain - url: http://localhost description: Self-hosted single-host localhost/no-domain via Caddy - url: http://localhost:3000 description: Local development direct API security: - bearerAuth: [] tags: - name: Health description: Public process-liveness check (no auth required) - name: Machines description: Machine lifecycle, execution, and process management - name: Files description: Filesystem operations within a machine - name: Git description: First-class structured git operations within a machine - name: Desktop description: Desktop automation (mouse, keyboard, screenshots) - name: Recording description: Screen recording management - name: PTY description: Pseudo-terminal session management - name: Templates description: Machine template management - name: Agent Deployments description: Named, versioned agent deployment control plane - name: Volumes description: Persistent volume control plane and attached volume actions - name: WebSocket description: Streaming execution and PTY over WebSocket - name: Monitor description: In-repo WebSocket stream for machine health, metrics, and process updates - name: API Keys description: Runtime API key metadata and dormant self-serve key management - name: Account description: Dormant Supabase-session account profile, export, and deletion routes - name: Admin description: Supabase-session operator console APIs for account support - name: Auth description: Dormant self-serve Auth proxy routes gated by deployment config - name: Code description: Stateful code execution via Jupyter kernels (Code Interpreter) - name: Internal Operations description: Operator-only internal API surfaces; not part of the public SDK contract paths: /v1/agent-deployments/{deployment_id}/versions/{version_id}: parameters: - $ref: '#/components/parameters/AgentDeploymentId' - $ref: '#/components/parameters/AgentDeploymentVersionId' get: tags: - Agent Deployments summary: Get an agent deployment version operationId: getAgentDeploymentVersion responses: '200': description: Agent deployment version content: application/json: schema: $ref: '#/components/schemas/AgentDeploymentVersion' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/AgentDeploymentNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/FeatureUnavailable' components: parameters: AgentDeploymentId: name: deployment_id in: path required: true schema: type: string description: Agent deployment ID AgentDeploymentVersionId: name: version_id in: path required: true schema: type: string description: Agent deployment version ID schemas: AgentDeploymentVersion: type: object required: - id - deployment_id - version_number - bundle_digest - bundle_manifest - config - template - workdir - entrypoint_command - env_spec - resource_config - debug_config - status - cache_policy - created_at properties: id: type: string example: adpv_1234abcd deployment_id: type: string version_number: type: integer minimum: 1 bundle_digest: type: string bundle_manifest: $ref: '#/components/schemas/AgentBundleManifest' config: $ref: '#/components/schemas/AgentDeploymentConfig' template: type: string workdir: type: string install_command: type: string nullable: true entrypoint_command: type: string service_port: type: integer minimum: 1 maximum: 65535 nullable: true readiness_config: nullable: true allOf: - $ref: '#/components/schemas/AgentReadinessConfig' env_spec: $ref: '#/components/schemas/AgentEnvSpec' resource_config: $ref: '#/components/schemas/AgentResourceConfig' debug_config: $ref: '#/components/schemas/AgentDebugConfig' status: $ref: '#/components/schemas/AgentDeploymentVersionStatus' cache_policy: $ref: '#/components/schemas/AgentDeploymentCachePolicy' cache_summary: $ref: '#/components/schemas/AgentDeploymentCacheSummary' nullable: true build_summary: $ref: '#/components/schemas/AgentDeploymentBuildSummary' nullable: true failure_reason: type: string nullable: true created_at: type: string format: date-time ready_at: type: string format: date-time nullable: true AgentBundleManifest: type: object required: - bundle_digest - config_digest - archive_format - total_size - file_count - generated_at - materialization_path - entries - include_patterns - exclude_patterns - default_exclude_patterns properties: bundle_digest: type: string config_digest: type: string archive_format: type: string enum: - tar total_size: type: integer format: int64 minimum: 0 file_count: type: integer minimum: 0 generated_at: type: string format: date-time materialization_path: type: string example: /workspace/project entries: type: array items: $ref: '#/components/schemas/AgentBundleEntry' include_patterns: type: array items: type: string exclude_patterns: type: array items: type: string default_exclude_patterns: type: array items: type: string AgentDeploymentConfig: type: object required: - name - mode - template - workdir - entrypoint - env - resources - service - debug properties: name: type: string mode: $ref: '#/components/schemas/AgentDeploymentMode' template: type: string workdir: type: string install: type: string nullable: true entrypoint: type: string env: $ref: '#/components/schemas/AgentEnvSpec' resources: $ref: '#/components/schemas/AgentResourceConfig' permissions: $ref: '#/components/schemas/AgentPermissionConfig' service: $ref: '#/components/schemas/AgentServiceConfig' debug: $ref: '#/components/schemas/AgentDebugConfig' outputs: $ref: '#/components/schemas/AgentOutputConfig' AgentReadinessConfig: type: object additionalProperties: true description: >- Service readiness probe config, validated on write (type one of http, tcp, timeout; path must start with /). Unknown keys are preserved verbatim, so the object is deliberately open beyond the known fields. properties: type: type: string enum: - http - tcp - timeout kind: type: string enum: - http - tcp - timeout description: Accepted alias for `type`. path: type: string description: HTTP readiness path; must start with `/`. timeout_seconds: type: integer minimum: 0 AgentEnvSpec: type: object required: - required - optional additionalProperties: false properties: required: type: array items: type: string optional: type: array items: type: string description: >- Environment variable names only. Secret values must not be stored in deployment config rows. AgentResourceConfig: type: object properties: vcpus: type: integer minimum: 1 memory_mb: type: integer minimum: 1 disk_mb: type: integer minimum: 1 timeout_seconds: type: integer minimum: 1 AgentDebugConfig: type: object description: >- Debug retention config for agent deployments. The server validates that only retain_on_failure and retain_seconds are accepted when a deployment version is created. properties: retain_on_failure: type: boolean retain_seconds: type: integer format: int64 minimum: 1 AgentDeploymentVersionStatus: type: string enum: - created - building - ready - failed - superseded AgentDeploymentCachePolicy: type: string enum: - auto - no_cache - rebuild AgentDeploymentCacheSummary: type: object required: - enabled - policy - status - artifact_ready properties: enabled: type: boolean policy: $ref: '#/components/schemas/AgentDeploymentCachePolicy' status: $ref: '#/components/schemas/AgentDeploymentCacheStatus' reason: type: string nullable: true build_id: type: string nullable: true cache_key_digest: type: string nullable: true example: sha256:abc123 artifact_id: type: string nullable: true artifact_ready: type: boolean updated_at: type: string format: date-time nullable: true AgentDeploymentBuildSummary: type: object required: - build_id - status - artifact_ready properties: build_id: type: string example: adpb_1234abcd status: $ref: '#/components/schemas/AgentDeploymentBuildStatus' artifact_id: type: string nullable: true artifact_ready: type: boolean size_bytes: type: integer format: int64 minimum: 0 nullable: true failure_reason: type: string nullable: true started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true ErrorResponse: type: object required: - error - code properties: error: type: string description: Human-readable error message code: type: string description: Machine-readable error code enum: - invalid_request - machine_not_found - snapshot_not_found - template_not_found - template_build_not_found - template_name_claim_not_found - machine_not_ready - unauthorized - auth_failed - auth_locked - auth_proxy_error - auth_proxy_unavailable - invalid_auth_redirect - invalid_oauth_provider - captcha_required - captcha_failed - captcha_unavailable - disposable_email - signup_rate_limited - oauth_rate_limited - email_action_rate_limited - database_error - email_not_verified - account_deleted - operator_required - account_not_found - account_not_soft_deleted - account_hard_delete_active_resources - file_upload_error - build_error - exec_timeout - exec_failed - file_error - not_implemented - capacity_exceeded - QUOTA_EXCEEDED - feature_unavailable - snapshot_in_use - no_eligible_runtime_host - same_host_required - incompatible_snapshot - rebuild_required - rate_limit_exceeded - transition_in_progress - transition_conflict - agent_deployment_not_found - agent_deployment_version_not_found - agent_run_not_found - agent_service_instance_not_found - agent_deployment_name_conflict - agent_deployment_idempotency_mismatch - agent_deployment_invalid_config - agent_deployment_invalid_state - volume_beta_restriction - volume_invalid_mount_path - volume_overlapping_mounts - volume_backend_capability_unsupported - volume_quota_exceeded - volume_mount_credential_issue_failed - volume_backend_unavailable - volume_stale_revision - volume_busy - volume_read_only - volume_limit_exceeded - internal_error error_detail: $ref: '#/components/schemas/ErrorDetail' request_id: type: string description: Request correlation ID returned in the `x-request-id` header build_id: type: string description: Template build ID when the error is associated with a tracked build AgentBundleEntry: type: object required: - path - kind - included - reason - size properties: path: type: string kind: type: string enum: - file - dir - symlink included: type: boolean reason: type: string size: type: integer format: int64 minimum: 0 mode: type: integer nullable: true digest: type: string nullable: true symlink_target: type: string nullable: true AgentDeploymentMode: type: string enum: - job - service AgentPermissionConfig: type: object additionalProperties: false properties: internet_access: type: boolean description: Whether the agent machine can reach the internet. allow_out: type: array items: type: string description: Optional outbound allow rules passed to machine network policy. deny_out: type: array items: type: string description: Optional outbound deny rules passed to machine network policy. public_url: type: boolean description: >- Service-mode control for whether the service URL endpoint returns a public URL. allow_public_traffic: type: boolean description: >- Service-mode control for whether public ingress skips the traffic-token header requirement. volumes: type: boolean description: Reserved P0 gate for future deployment volume mounts. desktop: type: boolean description: Whether to request desktop support on the backing machine. pty: type: boolean description: Reserved P0 gate for future deployment PTY/debug surfaces. debug: type: boolean description: Reserved P0 gate for future deployment debug surfaces. retain_on_failure: type: boolean description: Whether failed job runs may retain backing machines. max_vcpus: type: integer minimum: 1 max_memory_mb: type: integer minimum: 1 max_disk_mb: type: integer minimum: 1 max_timeout_seconds: type: integer minimum: 1 AgentServiceConfig: type: object properties: port: type: integer minimum: 1 maximum: 65535 readiness: $ref: '#/components/schemas/AgentReadinessConfig' AgentOutputConfig: type: object properties: paths: type: array description: Machine file or directory paths to inspect when a job run completes. items: type: string additionalProperties: false AgentDeploymentCacheStatus: type: string enum: - disabled - bypassed - cache_miss - cache_hit - building - ready - failed AgentDeploymentBuildStatus: type: string enum: - queued - building - ready - failed - expired ErrorDetail: oneOf: - $ref: '#/components/schemas/TemplateFailureDetail' - $ref: '#/components/schemas/UploadFailureDetail' TemplateFailureDetail: type: object required: - code - message - phase - retryable - suggested_action properties: code: type: string enum: - unauthorized - file_upload_error - build_error - internal_error message: type: string phase: $ref: '#/components/schemas/TemplateFailurePhase' retryable: type: boolean suggested_action: type: string step_index: type: integer attempt: type: integer max_attempts: type: integer cache_subject: type: string build_id: type: string request_id: type: string description: >- Present on terminal request-originated failures and blocking error responses. details: type: object additionalProperties: true description: >- Stable failure metadata. Includes a `reason` key plus phase-specific fields such as `blob_id`, `path`, digest/size mismatch values, `command`, or `alias`. UploadFailureDetail: type: object required: - reason - message - retryable properties: reason: $ref: '#/components/schemas/UploadFailureReason' message: type: string retryable: type: boolean upload_id: type: string request_id: type: string path: type: string description: >- Normalized absolute machine path associated with the failed upload when available. part_number: type: integer format: uint32 details: type: object additionalProperties: true description: >- Additional failure diagnostics; keys depend on the failure reason, deliberately open. TemplateFailurePhase: type: string enum: - auth - preflight - blob_upload - prepare - build_step - readiness - snapshot - finalize - interrupted UploadFailureReason: type: string enum: - insufficient_staging_space - size_limit_exceeded - invalid_part_checksum - part_out_of_range - part_size_mismatch - whole_checksum_mismatch - upload_expired - upload_aborted - upload_already_completed - target_conflict - directory_extract_invalid_path - directory_extract_invalid_symlink - directory_extract_unsupported_entry - missing_parts responses: Unauthorized: description: Missing or invalid bearer credential content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Missing or invalid bearer credential value: error: Missing or invalid bearer credential code: unauthorized request_id: req_123 AgentDeploymentNotFound: description: >- Agent deployment, version, run, or service instance was not found for the authenticated tenant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: Request was throttled by abuse controls or rate limits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' FeatureUnavailable: description: Feature is unavailable in current deployment mode content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer description: API key passed as Bearer token ````