> ## 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. # List build history for a custom template ref > Returns durable build attempts for the logical template resolved by ref, including failed attempts that never produced artifacts and historical builds whose tags have since moved. If the template's canonical ref itself ends with `builds`, the subresource remains one segment deeper, for example `/v1/templates/refs/acme/builds/builds`. ## OpenAPI ````yaml /openapi.yaml get /v1/templates/refs/{ref}/builds 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/templates/refs/{ref}/builds: parameters: - name: ref in: path required: true schema: type: string description: Canonical custom template ref. - name: status in: query required: false schema: $ref: '#/components/schemas/TemplateBuildStatus' - name: backend in: query required: false schema: $ref: '#/components/schemas/TemplateBuildBackend' - name: source_type in: query required: false schema: $ref: '#/components/schemas/TemplateBuildSourceType' - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false schema: type: string get: tags: - Templates summary: List build history for a custom template ref description: > Returns durable build attempts for the logical template resolved by ref, including failed attempts that never produced artifacts and historical builds whose tags have since moved. If the template's canonical ref itself ends with `builds`, the subresource remains one segment deeper, for example `/v1/templates/refs/acme/builds/builds`. operationId: listTemplateBuildsByRef responses: '200': description: Build history page content: application/json: schema: $ref: '#/components/schemas/TemplateBuildListResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/TemplateResourceNotFound' '503': $ref: '#/components/responses/FeatureUnavailable' components: schemas: TemplateBuildStatus: type: string enum: - waiting - building - ready - error - cancelled TemplateBuildBackend: type: string description: >- Template build backend. `native` is retained for declarative/OCI build requests and historical filters; Dockerfile build requests use `buildkit`. enum: - native - buildkit TemplateBuildSourceType: type: string enum: - declarative - dockerfile - oci_import - template_base TemplateBuildListResponse: type: object required: - builds properties: builds: type: array items: $ref: '#/components/schemas/TemplateBuildSummary' next_cursor: type: string TemplateBuildSummary: type: object required: - build_id - template_id - name - tags - status - build_backend - source_type - created_at - updated_at properties: build_id: type: string template_id: type: string name: type: string tags: type: array items: type: string status: $ref: '#/components/schemas/TemplateBuildStatus' build_backend: $ref: '#/components/schemas/TemplateBuildBackend' source_type: $ref: '#/components/schemas/TemplateBuildSourceType' source_digest: type: string context_digest: type: string dockerfile_digest: type: string triggered_by: type: string queued_at: type: string format: date-time started_at: type: string format: date-time finished_at: type: string format: date-time duration_ms: type: integer format: uint64 failure_phase: type: string cache_summary: $ref: '#/components/schemas/TemplateBuildCacheSummary' artifact_availability: $ref: '#/components/schemas/TemplateBuildArtifactAvailability' promotability: $ref: '#/components/schemas/TemplateBuildPromotability' retention_expires_at: type: string format: date-time artifact_ids: type: array items: type: string created_at: type: string format: date-time updated_at: type: string format: date-time 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 TemplateBuildCacheSummary: type: object properties: final_artifact_hits: type: integer final_artifact_misses: type: integer final_artifact_bypasses: type: integer final_artifact_stores: type: integer layer_hits: type: integer layer_misses: type: integer layer_bypasses: type: integer layer_stores: type: integer file_blob_hits: type: integer file_blob_misses: type: integer file_blob_bypasses: type: integer file_blob_stores: type: integer TemplateBuildArtifactAvailability: type: object required: - status properties: status: $ref: '#/components/schemas/TemplateBuildArtifactAvailabilityStatus' reason: type: string TemplateBuildPromotability: type: object required: - status - promotable properties: status: $ref: '#/components/schemas/TemplateBuildPromotabilityStatus' promotable: type: boolean reason: type: string ErrorDetail: oneOf: - $ref: '#/components/schemas/TemplateFailureDetail' - $ref: '#/components/schemas/UploadFailureDetail' TemplateBuildArtifactAvailabilityStatus: type: string enum: - available - publishing - warming - unavailable - failed TemplateBuildPromotabilityStatus: type: string enum: - promotable - not_ready - expired - purged - unavailable 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: InvalidRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 TemplateResourceNotFound: description: Template or template build not found 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 ````