{ "openapi": "3.1.0", "info": { "title": "Vulcan Artifact Registry API", "version": "1.0.0", "description": "Production Artifact Registry. Anonymous operations use the public read server; publication and operational routes use the IAM server with AWS SigV4." }, "servers": [ { "url": "https://artifacts-registry.neat.sima.ai", "description": "IAM-authenticated API Gateway (including GET requests)" } ], "security": [ { "sigv4": [] } ], "paths": { "/v1/runs": { "post": { "operationId": "createRun", "summary": "Create run", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRun" } } } }, "responses": { "200": { "$ref": "#/components/responses/RunCreated" }, "201": { "$ref": "#/components/responses/RunCreated" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "description": "Create run\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/runs/{run_id}/inputs/{name}": { "put": { "operationId": "putRunInput", "summary": "Put run input", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/Name" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "description": "Put run input\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/runs/{run_id}/parameters": { "put": { "operationId": "putRunParameters", "summary": "Put run parameters", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunParameters" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "description": "Put run parameters\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/runs/{run_id}/artifacts/{name}": { "put": { "operationId": "putArtifact", "summary": "Put artifact", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/Name" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "description": "Put artifact\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] }, "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getArtifact", "summary": "Get artifact", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/Name" }, { "name": "expires_in", "in": "query", "schema": { "type": "integer", "minimum": 60, "maximum": 900, "default": 300 } }, { "name": "download_filename", "in": "query", "description": "Optional MPK or full-model ZIP download basename; changes the response filename without renaming the stored object.", "schema": { "type": "string", "maxLength": 255, "pattern": "^(?:[a-z][a-z0-9]*(?:_[a-z0-9]+)*_mpk\\.tar\\.gz|[a-z][a-z0-9]*(?:_[a-z0-9]+)+\\.zip)$" } } ], "responses": { "200": { "$ref": "#/components/responses/Object" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Get artifact\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/runs/{run_id}/artifacts/{name}/content": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getArtifactContent", "summary": "Get artifact content", "description": "Returns immutable, integrity-checked Markdown or PNG hero content for a registered model card artifact after its producing run completes. Other artifact types cannot be served inline.\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/Name" } ], "responses": { "200": { "description": "Model README Markdown or hero PNG", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "text/markdown": { "schema": { "type": "string" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } }, "tags": [ "Public reads" ] } }, "/v1/runs/{run_id}/test-results/{suite}/{name}": { "put": { "operationId": "putTestResult", "summary": "Put test result", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/Suite" }, { "$ref": "#/components/parameters/Name" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestResult" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "409": { "$ref": "#/components/responses/Error" } }, "description": "Put test result\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/runs/{run_id}/measurements/batch": { "post": { "operationId": "putMeasurements", "summary": "Put measurements", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "measurements" ], "properties": { "measurements": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/Measurement" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "description": "Put measurements\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/runs/{run_id}/finalize": { "post": { "operationId": "finalizeRun", "summary": "Finalize run", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "enum": [ "completed", "failed", "expired", "cancelled" ] }, "failure_classification": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "description": "Finalize run\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/runs/{run_id}/publication-status": { "get": { "operationId": "getPublicationStatus", "summary": "Get publication status", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "$ref": "#/components/responses/Object" } }, "description": "Get publication status\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/runs/{run_id}": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getRun", "summary": "Get run", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "$ref": "#/components/responses/Object" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Get run\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/runs/{run_id}/provenance": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getRunProvenance", "summary": "Get run provenance", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "$ref": "#/components/responses/Object" } }, "description": "Get run provenance\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/runs/{run_id}/test-results": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getRunTestResults", "summary": "Get run test results", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "$ref": "#/components/responses/Object" } }, "description": "Get run test results\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/runs/{run_id}/metrics": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getRunMetrics", "summary": "Get run metrics", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "$ref": "#/components/responses/Object" } }, "description": "Get run metrics\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/repositories": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "listRepositories", "summary": "List repositories", "responses": { "200": { "$ref": "#/components/responses/Object" } }, "description": "List repositories\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/repositories/{organization}/{repository}/runs": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "listRepositoryRuns", "summary": "List repository runs", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "run_type", "in": "query", "schema": { "type": "string" } }, { "name": "commit_sha", "in": "query", "schema": { "type": "string" } }, { "name": "git_ref", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive AND search across model names, variants, category IDs and labels, compiler, target, branch, and commit.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "model_type", "in": "query", "schema": { "$ref": "#/components/schemas/TaxonomyId" } }, { "name": "task", "in": "query", "description": "Comma-separated task IDs use OR semantics within this facet.", "schema": { "type": "string" } }, { "name": "architecture_id", "in": "query", "schema": { "$ref": "#/components/schemas/TaxonomyId" } }, { "name": "architecture_paradigm", "in": "query", "schema": { "$ref": "#/components/schemas/TaxonomyId" } }, { "name": "input_modality", "in": "query", "description": "Comma-separated modality IDs use OR semantics within this facet.", "schema": { "type": "string" } }, { "name": "output_modality", "in": "query", "description": "Comma-separated modality IDs use OR semantics within this facet.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "Comma-separated normalized tags use OR semantics within this facet.", "schema": { "type": "string" } }, { "name": "latest_per_model_compiler", "in": "query", "description": "Return only the latest run for each branch, model, variant, compiler name/version, and target combination.", "schema": { "type": "boolean", "default": false } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by the preceding page and bound to its filters.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "$ref": "#/components/responses/Object" } }, "description": "List repository runs\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/repositories/{organization}/{repository}/branches": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "listRepositoryBranches", "summary": "List repository branches", "description": "Lists active branch refs represented by registry runs or current model catalogs, excluding tombstoned refs.\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" } ], "responses": { "200": { "description": "Complete active branch catalog for the repository.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCatalog" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "tags": [ "Public reads" ] } }, "/v1/repositories/{organization}/{repository}/catalogs/{revision}/snapshots": { "post": { "operationId": "publishCatalogProgressSnapshot", "summary": "Publish catalog progress snapshot", "description": "Compare the previous current snapshot digest and atomically publish a new immutable progress snapshot. Initialize once before compilation, then publish each complete invocation independently. Stale snapshots return catalog_snapshot_conflict (409); reload and retry. Updates for a revision that is no longer current are rejected.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/CatalogRevision" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "catalog", "previous_snapshot", "initialize" ], "properties": { "catalog": { "$ref": "#/components/schemas/ModelCatalogProgress" }, "previous_snapshot": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "initialize": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Existing identical immutable snapshot." }, "201": { "description": "Progress snapshot created and made current." }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/catalogs/{revision}": { "put": { "operationId": "publishModelCatalog", "summary": "Publish model catalog", "description": "Publishes an immutable complete catalog snapshot and atomically makes it current for its branch.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/CatalogRevision" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCatalogPublication" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "201": { "$ref": "#/components/responses/Object" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] }, "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getModelCatalog", "summary": "Get model catalog", "description": "Reads the current branch snapshot or an immutable snapshot by full Git commit SHA.\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/CatalogRevisionOrCurrent" }, { "$ref": "#/components/parameters/GitRef" }, { "name": "snapshot", "in": "query", "description": "Exact immutable snapshot digest; omit for the most recent snapshot of the revision.", "schema": { "$ref": "#/components/schemas/Sha256" } } ], "responses": { "200": { "$ref": "#/components/responses/Object" }, "404": { "$ref": "#/components/responses/Error" } }, "tags": [ "Public reads" ] } }, "/v1/repositories/{organization}/{repository}/models": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "listCurrentCatalogModels", "summary": "List current catalog models", "description": "Searches the current complete catalog snapshot for a branch.\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/GitRef" }, { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "model_type", "in": "query", "schema": { "$ref": "#/components/schemas/TaxonomyId" } }, { "name": "task", "in": "query", "schema": { "type": "string" } }, { "name": "architecture_id", "in": "query", "schema": { "$ref": "#/components/schemas/TaxonomyId" } }, { "name": "architecture_paradigm", "in": "query", "schema": { "$ref": "#/components/schemas/TaxonomyId" } }, { "name": "input_modality", "in": "query", "schema": { "type": "string" } }, { "name": "output_modality", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "toolchain_version", "in": "query", "description": "Returns models with at least one catalog build produced by this exact compiler version.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by the preceding page and bound to its branch, snapshot, and filters.", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Object" }, "404": { "$ref": "#/components/responses/Error" } }, "tags": [ "Public reads" ] } }, "/v1/repositories/{organization}/{repository}/taxonomies/{version}": { "put": { "operationId": "publishModelTaxonomy", "summary": "Publish model taxonomy", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/TaxonomyVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelTaxonomyPublication" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "201": { "$ref": "#/components/responses/Object" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "description": "Publish model taxonomy\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] }, "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "getModelTaxonomy", "summary": "Get model taxonomy", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/TaxonomyVersionOrLatest" } ], "responses": { "200": { "$ref": "#/components/responses/Object" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Get model taxonomy\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/repositories/{organization}/{repository}/resolve": { "get": { "security": [], "servers": [ { "url": "https://models-registry.neat.sima.ai", "description": "Anonymous reads for allowlisted repositories" } ], "operationId": "resolveRun", "summary": "Resolve run", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "name": "run_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "fingerprint", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Sha256" } }, { "name": "fingerprint_version", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "$ref": "#/components/responses/Object" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Resolve run\n\nAuthentication: none on the public read hostname, for allowlisted repositories.", "tags": [ "Public reads" ] } }, "/v1/repositories/{organization}/{repository}/branches/purge": { "post": { "operationId": "purgeBranch", "summary": "Purge branch", "description": "Immediately queue deletion of all snapshotted runs and exclusively owned S3 objects for a deleted branch.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchPurgeRequest" } } } }, "responses": { "202": { "description": "Purge job was durably recorded and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchPurgeJob" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/branches/restore": { "post": { "operationId": "restoreBranch", "summary": "Restore branch", "description": "Remove a completed purge tombstone before publishing a recreated branch.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchPurgeRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/branches/reconcile": { "post": { "operationId": "reconcileBranches", "summary": "Reconcile branches", "description": "Compare a complete GitHub branch inventory with registry refs and record missing-branch observations.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchReconciliationRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Object" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/purge-jobs/{job_id}": { "get": { "operationId": "getBranchPurgeJob", "summary": "Get branch purge job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current purge progress and terminal deletion counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchPurgeJob" } } } }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Get branch purge job\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/deployments": { "post": { "operationId": "createCandidateDeployment", "summary": "Create candidate deployment", "description": "Register a candidate with a seven-day assembly deadline. Does not publish a catalog selection.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCandidate" } } } }, "responses": { "201": { "$ref": "#/components/responses/Candidate" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/deployments/{deployment_id}": { "get": { "operationId": "getCandidateDeployment", "summary": "Get candidate deployment", "description": "Publisher-authenticated candidate inspection. Availability is registry state rather than a live S3 probe. This route is not on the public reader.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/DeploymentId" } ], "responses": { "200": { "$ref": "#/components/responses/Candidate" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/deployments/{deployment_id}/runs/{run_id}": { "put": { "operationId": "attachCandidateRun", "summary": "Attach candidate run", "description": "Bind an owned run to one declared role before upload. Bindings cannot be replaced. All registered dependencies of the run are protected while a candidate hold is active.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/DeploymentId" }, { "$ref": "#/components/parameters/RunId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "role" ], "properties": { "role": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Candidate" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/deployments/{deployment_id}/finalize": { "post": { "operationId": "finalizeCandidateDeployment", "summary": "Finalize candidate deployment", "description": "Freeze a complete manifest and establish protection atomically. Newest successful generation gets durable latest-successful protection. An older late completion gets seven days of grace. Neither action approves or changes a catalog. Idempotent replay returns the original receipt; GET returns current protection and availability.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/DeploymentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "contract_digest" ], "properties": { "contract_digest": { "$ref": "#/components/schemas/Sha256" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Candidate" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/branch-deployments": { "post": { "operationId": "selectBranchDeployment", "summary": "Select branch deployment", "description": "Publisher atomically selects a protected finalized candidate in its source feature-branch catalog and installs a branch-selection hold. Develop, Main and master are excluded. Validates current profile build_requirements, exact native manifests and availability. expected_snapshot must match the current catalog digest; an older candidate generation cannot replace a newer selected generation even after a snapshot retry. Supports metadata-only catalogs and repeated builds at the same commit. Does not approve or copy artifacts. Requires publisher IAM authentication and an Idempotency-Key; replay returns the original receipt.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectBranchDeployment" } } } }, "responses": { "200": { "description": "Selection and protection committed together. Read current catalog for current state after replay.", "content": { "application/json": { "schema": { "type": "object", "required": [ "git_ref", "result_snapshot", "selection" ], "properties": { "git_ref": { "type": "string" }, "result_snapshot": { "$ref": "#/components/schemas/Sha256" }, "selection": { "$ref": "#/components/schemas/DeploymentReference" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/promotions": { "post": { "operationId": "requestCandidatePromotion", "summary": "Request candidate promotion", "description": "Publisher requests approval of a finalized candidate for Develop. Acquires a seven-day pending hold after exact target and artifact validation.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromotion" } } } }, "responses": { "201": { "$ref": "#/components/responses/Promotion" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/promotions/{promotion_id}": { "get": { "operationId": "getCandidatePromotion", "summary": "Get candidate promotion", "description": "Publisher or scoped approver reads current state, immutable source identity, reviewed selection and expiry. No public access.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/PromotionId" } ], "responses": { "200": { "$ref": "#/components/responses/Promotion" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/promotions/{promotion_id}/approve": { "post": { "operationId": "approveCandidatePromotion", "summary": "Approve candidate promotion", "description": "Separate approver role only. Atomically select the reviewed candidate, protect its dependencies and replace the scoped selection hold. Any target snapshot change returns 409 and requires a new request and review.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/PromotionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovePromotion" } } } }, "responses": { "200": { "$ref": "#/components/responses/Promotion" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/promotions/{promotion_id}/reject": { "post": { "operationId": "rejectCandidatePromotion", "summary": "Reject candidate promotion", "description": "Separate approver role only. Reject a pending request and release only its pending hold.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/PromotionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosePromotion" } } } }, "responses": { "200": { "$ref": "#/components/responses/Promotion" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } }, "/v1/repositories/{organization}/{repository}/promotions/{promotion_id}/cancel": { "post": { "operationId": "cancelCandidatePromotion", "summary": "Cancel candidate promotion", "description": "Publisher cancels a pending request. Never undoes completed promotion.\n\nAuthentication: AWS SigV4 (us-west-2, execute-api), using an authorized IAM role. Generated header examples do not compute a valid AWS signature.", "parameters": [ { "$ref": "#/components/parameters/Organization" }, { "$ref": "#/components/parameters/Repository" }, { "$ref": "#/components/parameters/PromotionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosePromotion" } } } }, "responses": { "200": { "$ref": "#/components/responses/Promotion" }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } }, "tags": [ "IAM authenticated" ] } } }, "components": { "securitySchemes": { "sigv4": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "AWS Signature Version 4, region us-west-2, service execute-api. Not a static API key; use an AWS signing client with authorized credentials." } }, "parameters": { "PromotionId": { "name": "promotion_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, "DeploymentId": { "name": "deployment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "RunId": { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Name": { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "Suite": { "name": "suite", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "Organization": { "name": "organization", "in": "path", "required": true, "schema": { "type": "string" } }, "Repository": { "name": "repository", "in": "path", "required": true, "schema": { "type": "string" } }, "TaxonomyVersion": { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "TaxonomyVersionOrLatest": { "name": "version", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "const": "latest" } ] } }, "CatalogRevision": { "name": "revision", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$" } }, "CatalogRevisionOrCurrent": { "name": "revision", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "string", "pattern": "^[0-9a-f]{40}$" }, { "type": "string", "const": "current" } ] } }, "GitRef": { "name": "git_ref", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^refs/heads/.+$" } } }, "schemas": { "CreateCandidate": { "type": "object", "additionalProperties": false, "required": [ "git_ref", "commit_sha", "model_id", "profile_id", "contract" ], "properties": { "git_ref": { "type": "string", "pattern": "^refs/heads/.+" }, "commit_sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40,64}$" }, "model_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "profile_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "contract": { "$ref": "#/components/schemas/CandidateContract" } } }, "CandidateContract": { "type": "object", "additionalProperties": false, "required": [ "version", "roles" ], "properties": { "version": { "type": "integer", "const": 1 }, "roles": { "type": "object", "minProperties": 1, "maxProperties": 32, "description": "Required producing/evidence roles. Between 1 and 512 required file names across all roles. Finalization also limits the complete registered S3 dependency set to 512 versions and the frozen manifest to 1 MiB.", "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "additionalProperties": { "type": "object", "additionalProperties": false, "required": [ "run_type", "artifacts", "inputs" ], "properties": { "run_type": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "artifacts": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "inputs": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } } } } } } }, "CandidateDeployment": { "type": "object", "required": [ "deployment_id", "state", "generation", "git_ref", "commit_sha", "model_id", "profile_id", "contract", "contract_digest", "manifest", "manifest_digest", "assembly_expires_at", "upload_prefix", "bindings", "protection", "availability" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "assembling", "finalized" ] }, "generation": { "type": "integer", "minimum": 1 }, "git_ref": { "type": "string" }, "commit_sha": { "type": "string" }, "model_id": { "type": "string" }, "profile_id": { "type": "string" }, "contract": { "$ref": "#/components/schemas/CandidateContract" }, "contract_digest": { "$ref": "#/components/schemas/Sha256" }, "manifest": { "type": [ "object", "null" ], "description": "Frozen version-1 document containing source/model/profile identity, contract digest, and snapshots of runs, environments, artifacts, inputs, parameters, tests and measurements. Not a catalog or approval." }, "manifest_digest": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "assembly_expires_at": { "type": "string" }, "upload_prefix": { "type": "string", "description": "Candidate-owned S3 prefix. Retain exact upload version IDs and retry registration before the assembly deadline." }, "bindings": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "original_run_id": { "type": "string", "format": "uuid" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": [ "string", "null" ] } } } }, "protection": { "type": "array", "description": "Active holds only. This may change after finalization independently of the immutable manifest.", "items": { "type": "object", "required": [ "reason", "owner", "expires_at" ], "properties": { "reason": { "type": "string", "enum": [ "assembly", "latest_successful", "late_completion", "promotion_pending", "approved_selection" ] }, "owner": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "description": "Null means durable until explicitly released or replaced." } } } }, "availability": { "type": "string", "enum": [ "assembling", "registered", "unavailable" ] } } }, "Sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "TaxonomyId": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "ModelCategories": { "type": "object", "additionalProperties": false, "required": [ "taxonomy_version", "model_type", "tasks", "modalities", "architecture", "tags" ], "properties": { "taxonomy_version": { "type": "integer", "minimum": 1 }, "model_type": { "$ref": "#/components/schemas/TaxonomyId" }, "tasks": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/TaxonomyId" } }, "modalities": { "type": "object", "additionalProperties": false, "required": [ "inputs", "outputs" ], "properties": { "inputs": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/TaxonomyId" } }, "outputs": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/TaxonomyId" } } } }, "architecture": { "type": "object", "additionalProperties": false, "required": [ "id", "paradigm" ], "properties": { "id": { "$ref": "#/components/schemas/TaxonomyId" }, "paradigm": { "$ref": "#/components/schemas/TaxonomyId" }, "variant": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]*$" }, "components": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "role", "architecture_id" ], "properties": { "role": { "$ref": "#/components/schemas/TaxonomyId" }, "architecture_id": { "$ref": "#/components/schemas/TaxonomyId" } } } } } }, "tags": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/TaxonomyId" } } } }, "ModelTaxonomyPublication": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "canonical_sha256", "taxonomy" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "canonical_sha256": { "$ref": "#/components/schemas/Sha256" }, "taxonomy": { "type": "object" } } }, "ModelCatalogProgress": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "repository", "git_ref", "catalog_revision", "taxonomy_sha256", "taxonomy", "models", "pending_builds" ], "properties": { "schema_version": { "type": "integer", "const": 2 }, "repository": { "type": "string", "const": "sima-neat/models" }, "git_ref": { "type": "string", "pattern": "^refs/heads/.+$" }, "catalog_revision": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "taxonomy_sha256": { "$ref": "#/components/schemas/Sha256" }, "taxonomy": { "type": "object" }, "models": { "type": "array", "description": "Complete metadata with available builds. Models without builds must have a pending invocation unless build_on_demand is true; on-demand models may publish metadata without scheduling compilation.", "items": { "$ref": "#/components/schemas/ModelCatalogModel" } }, "pending_builds": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "model_id", "build_profile_id", "compile_invocation_id", "component_ids", "compile_fingerprint" ], "properties": { "model_id": { "type": "string" }, "build_profile_id": { "type": "string" }, "compile_invocation_id": { "type": "string" }, "component_ids": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } }, "compile_fingerprint": { "$ref": "#/components/schemas/Sha256" } } } } } }, "ModelCatalogPublication": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "repository", "git_ref", "catalog_revision", "taxonomy_sha256", "taxonomy", "models" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "repository": { "type": "string", "const": "sima-neat/models" }, "git_ref": { "type": "string", "pattern": "^refs/heads/.+$" }, "catalog_revision": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "taxonomy_sha256": { "$ref": "#/components/schemas/Sha256" }, "taxonomy": { "type": "object" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelCatalogModel" } } } }, "BuildRequirements": { "type": "object", "additionalProperties": false, "required": [ "version", "compiler_version", "invocations", "packages" ], "properties": { "version": { "type": "integer", "const": 1 }, "compiler_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "invocations": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "component_ids", "compile_fingerprint" ], "properties": { "id": { "type": "string" }, "component_ids": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "type": "string" } }, "compile_fingerprint": { "$ref": "#/components/schemas/Sha256" } } } }, "packages": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "component_ids", "layout", "format" ], "properties": { "id": { "type": "string" }, "component_ids": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "type": "string" } }, "layout": { "type": "string", "enum": [ "archive", "directory" ] }, "format": { "type": "string", "enum": [ "zip", "llima" ] } } } } } }, "SelectBranchDeployment": { "type": "object", "additionalProperties": false, "required": [ "git_ref", "deployment_id", "manifest_digest", "expected_snapshot" ], "properties": { "git_ref": { "type": "string", "pattern": "^refs/heads/.+", "description": "Candidate source feature branch; develop, main and master are rejected." }, "deployment_id": { "type": "string", "format": "uuid" }, "manifest_digest": { "$ref": "#/components/schemas/Sha256" }, "expected_snapshot": { "$ref": "#/components/schemas/Sha256" } } }, "ApprovedDeployment": { "$ref": "#/components/schemas/DeploymentReference" }, "DeploymentReference": { "type": "object", "required": [ "deployment_id", "manifest_digest", "artifacts" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "manifest_digest": { "$ref": "#/components/schemas/Sha256" }, "artifacts": { "type": "array", "description": "Server-derived runtime roots. Directory roots are existing JSON file manifests; retrieve their files through the same run-artifact API. Source documentation remains on original candidate-bound runs.", "items": { "type": "object", "required": [ "role", "run_id", "artifact_name", "layout", "format" ], "properties": { "role": { "type": "string" }, "component_id": { "type": "string" }, "package_id": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" }, "artifact_name": { "type": "string" }, "layout": { "type": "string", "enum": [ "archive", "directory" ] }, "format": { "type": "string", "enum": [ "mpk", "llima", "zip" ] } } } } } }, "CreatePromotion": { "type": "object", "additionalProperties": false, "required": [ "deployment_id", "manifest_digest", "target_git_ref", "expected_target_snapshot", "reason", "workflow" ], "properties": { "deployment_id": { "type": "string", "format": "uuid" }, "manifest_digest": { "$ref": "#/components/schemas/Sha256" }, "target_git_ref": { "type": "string", "const": "refs/heads/develop" }, "expected_target_snapshot": { "$ref": "#/components/schemas/Sha256" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "workflow": { "type": "object", "additionalProperties": false, "description": "Correlation only; never authorization evidence.", "properties": { "run_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "run_url": { "type": "string", "minLength": 1, "maxLength": 1000 }, "issue_url": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "ApprovePromotion": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "ClosePromotion": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "PromotionRequest": { "type": "object", "description": "Idempotent writes replay their original receipt; GET returns current state. Expiry is effective immediately even before scheduled cleanup persists it.", "properties": { "promotion_id": { "type": "string", "format": "uuid" }, "deployment_id": { "type": "string", "format": "uuid" }, "manifest_digest": { "$ref": "#/components/schemas/Sha256" }, "target_git_ref": { "type": "string" }, "expected_target_snapshot": { "$ref": "#/components/schemas/Sha256" }, "state": { "type": "string", "enum": [ "pending", "promoted", "rejected", "cancelled", "expired" ] }, "expires_at": { "type": "string", "format": "date-time" }, "pending_protection": { "type": "boolean" }, "source": { "type": "object", "description": "Original git_ref, commit_sha, model_id and profile_id." }, "selection": { "$ref": "#/components/schemas/ApprovedDeployment" }, "previous_selection": { "type": [ "object", "null" ] }, "result_snapshot": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "workflow": { "type": "object" }, "requested_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decision_reason": { "type": [ "string", "null" ] } } }, "ModelCatalogModel": { "type": "object", "additionalProperties": false, "required": [ "id", "display_name", "description", "license", "maturity", "categories", "builds" ], "properties": { "id": { "$ref": "#/components/schemas/TaxonomyId" }, "display_name": { "type": "string" }, "parameter_count_billion": { "type": "number", "exclusiveMinimum": 0, "description": "Published parameter count in billions before quantization." }, "description": { "type": "string" }, "license": { "type": "object" }, "maturity": { "type": "string" }, "categories": { "type": "object" }, "documentation": { "$ref": "#/components/schemas/ModelDocumentation" }, "build_on_demand": { "type": "boolean", "default": false, "description": "Scheduling policy only. When true, builds may be empty without pending compilation; does not grant approval or retention protection." }, "build_requirements": { "type": "object", "maxProperties": 32, "description": "Optional versioned producer requirements keyed by profile, including unbuilt on-demand profiles. Required for promotion eligibility.", "additionalProperties": { "$ref": "#/components/schemas/BuildRequirements" } }, "branch_deployments": { "type": "object", "description": "Server-owned unapproved feature-branch selections keyed by profile. Same shape as approved_deployments, with no approval meaning. Consumers prefer this reference over legacy outputs for the selected feature profile; Develop/Main must use approved_deployments. Omit or echo exactly during ordinary publication. Compatible metadata updates preserve selections; changed/removed profile requirements in a new revision retire the selection and release only its branch hold. Branch purge clears current selections and branch holds; historical snapshots remain immutable and are not indefinite download guarantees.", "additionalProperties": { "$ref": "#/components/schemas/DeploymentReference" } }, "approved_deployments": { "type": "object", "description": "Server-owned selections keyed by profile. Ordinary publication preserves these; conflicting replacements or requirement changes return 409. Historical snapshots remain unchanged.", "additionalProperties": { "$ref": "#/components/schemas/ApprovedDeployment" } }, "benchmark_fingerprints": { "type": "object", "minProperties": 1, "description": "Optional fingerprints of whole-model benchmark runs, keyed by built profile. Clients resolve each fingerprint with /v1/repositories/{org}/{repo}/resolve (run_type model_performance or model_accuracy). Fingerprints may appear in later snapshots of the same revision as profiles finish, and change only when the profile's builds change. A fingerprint is published before its run exists and resolves once the run completes; the registry does not check that a matching run exists.", "additionalProperties": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "performance": { "$ref": "#/components/schemas/Sha256" }, "accuracy": { "$ref": "#/components/schemas/Sha256" } } } }, "builds": { "type": "array", "items": { "type": "object" } }, "packages": { "type": "array", "description": "Optional full-model ZIP package artifacts. Each references a completed model_package run.", "items": { "$ref": "#/components/schemas/ModelCatalogPackage" } } } }, "ModelDocumentation": { "type": "object", "additionalProperties": false, "required": [ "format", "overview_markdown", "run_id", "artifact_name", "artifact_sha256", "size_bytes", "media_type", "source_path", "source_commit" ], "properties": { "format": { "type": "string", "const": "markdown" }, "overview_markdown": { "type": "string", "description": "One or two prose paragraphs containing 50 to 120 whitespace-delimited words.", "pattern": "^(?:\\S+\\s+){49,119}\\S+(?![\\s\\S])" }, "run_id": { "type": "string", "format": "uuid" }, "artifact_name": { "type": "string", "const": "readme" }, "artifact_sha256": { "$ref": "#/components/schemas/Sha256" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 131072 }, "media_type": { "type": "string", "const": "text/markdown; charset=utf-8" }, "source_path": { "type": "string", "pattern": "^models/[a-z][a-z0-9_]+/README\\.md$" }, "source_commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "hero": { "description": "Optional hero image packaged with the model card when a non-placeholder asset is available.", "$ref": "#/components/schemas/ModelDocumentationHero" } } }, "ModelDocumentationHero": { "type": "object", "description": "References a 1200x480 PNG using the registry profile of IHDR, optional PLTE, IDAT, IEND, and optional validated tIME or tRNS ancillary chunks.", "additionalProperties": false, "required": [ "artifact_name", "markdown_path", "alt_text", "artifact_sha256", "size_bytes", "media_type", "source_path" ], "properties": { "artifact_name": { "type": "string", "const": "hero" }, "markdown_path": { "type": "string", "const": "hero.png" }, "alt_text": { "type": "string", "minLength": 1, "maxLength": 200 }, "artifact_sha256": { "$ref": "#/components/schemas/Sha256" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 2097152 }, "media_type": { "type": "string", "const": "image/png" }, "source_path": { "type": "string", "pattern": "^models/[a-z][a-z0-9_]+/hero\\.png$" } } }, "ModelCatalogPackage": { "type": "object", "additionalProperties": false, "required": [ "package_id", "build_profile_id", "run_id", "artifact_sha256", "size_bytes", "package_fingerprint", "component_run_ids" ], "properties": { "package_id": { "$ref": "#/components/schemas/TaxonomyId" }, "build_profile_id": { "$ref": "#/components/schemas/TaxonomyId" }, "run_id": { "type": "string", "format": "uuid" }, "artifact_sha256": { "$ref": "#/components/schemas/Sha256" }, "size_bytes": { "type": "integer", "minimum": 0 }, "package_fingerprint": { "$ref": "#/components/schemas/Sha256" }, "component_run_ids": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string", "format": "uuid" } } } }, "CreateRun": { "type": "object", "additionalProperties": false, "required": [ "run_type", "commit_sha", "environment" ], "properties": { "schema_version": { "type": "integer", "const": 1, "default": 1 }, "run_type": { "type": "string" }, "commit_sha": { "type": "string", "pattern": "^[0-9A-Fa-f]{40,64}$" }, "git_ref": { "type": "string" }, "pull_request_number": { "type": "integer" }, "ci_provider": { "type": "string" }, "ci_run_url": { "type": "string", "format": "uri" }, "run_fingerprint": { "$ref": "#/components/schemas/Sha256" }, "environment": { "type": "object", "required": [ "fingerprint" ], "properties": { "fingerprint": { "$ref": "#/components/schemas/Sha256" }, "fingerprint_version": { "type": "integer", "default": 1 }, "toolchain_name": { "type": "string" }, "toolchain_version": { "type": "string" }, "target_platform": { "type": "string" }, "target_device": { "type": "string" }, "properties": { "type": "object" } } }, "metadata": { "type": "object" }, "model_categories": { "$ref": "#/components/schemas/ModelCategories" } } }, "RunInput": { "type": "object", "required": [ "input_type", "sha256" ], "properties": { "input_type": { "type": "string" }, "source_reference": { "type": "string" }, "s3_bucket": { "type": "string" }, "s3_key": { "type": "string" }, "s3_version_id": { "type": "string" }, "sha256": { "$ref": "#/components/schemas/Sha256" }, "size_bytes": { "type": "integer", "minimum": 0 }, "media_type": { "type": "string" }, "metadata": { "type": "object" }, "delete_with_run": { "type": "boolean", "default": false, "description": "Explicitly marks this input object as run-owned and eligible for purge." } } }, "RunParameters": { "type": "object", "required": [ "parameters" ], "properties": { "parameters": { "type": "object" }, "canonical_sha256": { "$ref": "#/components/schemas/Sha256" }, "canonicalization_version": { "type": "integer", "default": 1 } } }, "Artifact": { "type": "object", "required": [ "artifact_type", "s3_bucket", "s3_key", "s3_version_id", "sha256", "size_bytes" ], "properties": { "artifact_type": { "type": "string" }, "s3_bucket": { "type": "string" }, "s3_key": { "type": "string" }, "s3_version_id": { "type": "string" }, "sha256": { "$ref": "#/components/schemas/Sha256" }, "size_bytes": { "type": "integer", "minimum": 0 }, "media_type": { "type": "string" }, "retention_class": { "type": "string", "description": "on-demand requires an active candidate assembly binding. README/hero accept branch or on-demand with no explicit expiry; other validation remains unchanged." }, "expires_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" } } }, "BranchPurgeRequest": { "type": "object", "additionalProperties": false, "required": [ "git_ref" ], "properties": { "git_ref": { "type": "string", "pattern": "^refs/heads/.+", "maxLength": 512 } } }, "BranchCatalog": { "type": "object", "additionalProperties": false, "required": [ "branches" ], "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/BranchCatalogEntry" } } } }, "BranchCatalogEntry": { "type": "object", "additionalProperties": false, "required": [ "name", "git_ref", "latest_run_at", "run_count" ], "properties": { "name": { "type": "string" }, "git_ref": { "type": "string", "pattern": "^refs/heads/.+", "maxLength": 512 }, "latest_run_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest non-superseded run time on this branch; null for a catalog with only inherited builds." }, "run_count": { "type": "integer", "minimum": 0 } } }, "BranchPurgeJob": { "type": "object", "required": [ "job_id", "git_ref", "status", "run_count" ], "properties": { "job_id": { "type": "string", "format": "uuid" }, "git_ref": { "type": "string" }, "status": { "enum": [ "queued", "running", "completed", "failed" ] }, "attempts": { "type": "integer", "minimum": 0 }, "run_count": { "type": "integer", "minimum": 0 }, "object_count": { "type": "integer", "minimum": 0 }, "retained_run_count": { "type": "integer", "minimum": 0, "description": "Present on job inspection. Runs skipped because of candidate protection." }, "retained_object_count": { "type": "integer", "minimum": 0, "description": "Present on job inspection. Versions retained due to holds or shared references." }, "deleted_object_count": { "type": "integer", "minimum": 0 }, "deleted_run_count": { "type": "integer", "minimum": 0 }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BranchReconciliationRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "active_refs", "default_ref", "grace_hours", "dry_run" ], "properties": { "active_refs": { "type": "array", "maxItems": 10000, "uniqueItems": true, "items": { "type": "string", "pattern": "^refs/heads/.+", "maxLength": 512 } }, "default_ref": { "type": "string", "pattern": "^refs/heads/.+", "maxLength": 512 }, "grace_hours": { "type": "integer", "minimum": 1, "maximum": 720 }, "dry_run": { "type": "boolean" } } }, { "type": "object", "additionalProperties": false, "required": [ "clear_refs" ], "properties": { "clear_refs": { "description": "Reset-only request used after GitHub confirms an eligible ref exists.", "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^refs/heads/.+", "maxLength": 512 } } } } ] }, "TestResult": { "type": "object", "required": [ "status" ], "properties": { "status": { "enum": [ "passed", "failed", "skipped", "error" ] }, "version": { "type": "string", "default": "1" }, "duration_ms": { "type": "number", "minimum": 0 }, "attempt": { "type": "integer", "minimum": 1, "default": 1 }, "failure_classification": { "type": "string" }, "report_artifact_id": { "type": "string", "format": "uuid" }, "log_artifact_id": { "type": "string", "format": "uuid" }, "summary": { "type": "object" } } }, "Measurement": { "type": "object", "required": [ "measurement_key", "name", "unit", "value" ], "properties": { "measurement_key": { "type": "string" }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]*$" }, "unit": { "type": "string" }, "value_type": { "enum": [ "numeric", "text" ], "default": "numeric" }, "value": {}, "direction": { "enum": [ "higher", "lower", "neutral" ], "default": "neutral" }, "sample_count": { "type": "integer", "minimum": 1, "default": 1 }, "aggregation": { "type": "string", "default": "raw" }, "dimensions": { "type": "object" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } }, "responses": { "Promotion": { "description": "Reviewed candidate and promotion lifecycle state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionRequest" } } } }, "Candidate": { "description": "Candidate identity, immutable content when finalized, and current protection. An idempotent replay returns the original receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateDeployment" } } } }, "Object": { "description": "Successful JSON response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "RunCreated": { "description": "New run or an idempotent replay.", "headers": { "Idempotent-Replay": { "schema": { "type": "string", "const": "true" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "created_at" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "Error": { "description": "Stable application error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }