{ "openapi": "3.1.0", "info": { "title": "sfmapi", "version": "0.0.1" }, "paths": { "/healthz": { "get": { "tags": [ "health" ], "summary": "Healthz", "description": "Liveness \u2014 only checks the process is responding. Use\n``/readyz`` to test that the service can serve traffic.", "operationId": "healthz_healthz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/readyz": { "get": { "tags": [ "health" ], "summary": "Readyz", "description": "Readiness \u2014 verifies backing stores (DB; Redis when configured)\nare reachable. Returns ``503`` with a per-check breakdown when\nanything is unreachable so Kubernetes / load balancers can drain\ntraffic during a degraded state.", "operationId": "readyz_readyz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyzResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyzResponse" } } } } } } }, "/version": { "get": { "tags": [ "health" ], "summary": "Version", "description": "Return sfmapi + the registered backend's identity / runtime\nversion map. ``backend`` is ``None`` when no backend is registered\n\u2014 useful for headless / wire-only deployments.\n\nThe contents of ``backend.runtime_versions`` are backend-defined;\ntypical fields include engine commit shas, CUDA arch, and\nauxiliary library versions that influence the cache-key salt.", "operationId": "version_version_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } } } } }, "/spec": { "get": { "tags": [ "health" ], "summary": "Spec", "description": "Discovery endpoint: identifies which standard this server\nimplements. Clients can hit this to learn the spec version + a\npointer to the human-readable doc.\n\n``spec_url`` is configurable via ``SFMAPI_SPEC_URL`` because sfmapi\nhas no canonical hosting; deployments point clients at their own\nspec mirror or leave it ``None``.", "operationId": "spec_spec_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecResponse" } } } } } } }, "/v1/projects": { "post": { "tags": [ "projects" ], "summary": "Create", "description": "Create a new Project under the caller's tenant.\n\nProjects are the top-level workspace; every Dataset / Reconstruction\nrolls up under one. ``name`` is a human label and is NOT unique \u2014\nrely on the returned ``project_id`` (a ULID) as the canonical key.", "operationId": "create_v1_projects_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "projects" ], "summary": "List ", "description": "List the caller's projects, AIP-158 paginated.\n\nPass an empty ``page_token`` for the first page; iterate by\nthreading the previous response's ``next_page_token`` back. A\n``null`` ``next_page_token`` means the iteration is exhausted.", "operationId": "list__v1_projects_get", "parameters": [ { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ProjectOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects/{project_id}": { "get": { "tags": [ "projects" ], "summary": "Get", "description": "Read a single project by id.\n\nReturns 404 when the project doesn't exist for this tenant \u2014 a row\nthat exists under another tenant looks identical to \"not present\"\nby design (see ``L2`` tenant boundary).", "operationId": "get_v1_projects__project_id__get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "projects" ], "summary": "Patch", "description": "Partially update a project.\n\nWithout ``update_mask``, only fields present in the request body\nare written. With ``update_mask``, only the named field paths are\napplied and they must also be present in the body.", "operationId": "patch_v1_projects__project_id__patch", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "update_mask", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional AIP-161 comma-separated field mask. Allowed paths: name, description.", "title": "Update Mask" }, "description": "Optional AIP-161 comma-separated field mask. Allowed paths: name, description." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "projects" ], "summary": "Delete", "description": "Delete a project (cascade).\n\nCascades through datasets, reconstructions, jobs, and on-disk\nworkspace state. Returns 204 on success, 404 when the project\ndoesn't exist for this tenant. Conflict-409 if active jobs prevent\na clean teardown \u2014 cancel them first.", "operationId": "delete_v1_projects__project_id__delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects/{project_id}/datasets:from_video": { "post": { "tags": [ "projects" ], "summary": "From Video", "description": "Extract frames from a worker-local video file. The result carries\nthe output directory; the client follows up with a ``local``-source\ndataset pointing at it.", "operationId": "from_video_v1_projects__project_id__datasets_from_video_post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoFramesRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects/{project_id}/datasets:import_kapture": { "post": { "tags": [ "projects" ], "summary": "Import Kapture", "description": "Parse a Kapture archive into a sensors+records inventory; the\njob result carries the parsed contents and the recommended\n``image_root`` so the client can register a ``local`` dataset\npointing at it.", "operationId": "import_kapture_v1_projects__project_id__datasets_import_kapture_post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KaptureImportRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/artifacts/kinds": { "get": { "tags": [ "artifacts" ], "summary": "List Artifact Kinds", "description": "List sfmapi's reserved core artifact kinds.\n\nBackends may still emit namespaced extension kinds. The core list\ngives clients stable semantics for portable stage inputs.", "operationId": "list_artifact_kinds_v1_artifacts_kinds_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ArtifactKindOut_" } } } } } } }, "/v1/artifacts/formats": { "get": { "tags": [ "artifacts" ], "summary": "List Artifact Formats", "description": "List sfmapi's reserved core artifact interchange formats.\n\nBackend-native formats are exposed by backend artifact contracts,\nnot reserved here. Core formats are the stable interchange surface\nclients can rely on across backend implementations.", "operationId": "list_artifact_formats_v1_artifacts_formats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ArtifactFormatOut_" } } } } } } }, "/v1/artifacts/{artifact_id}:conversionPlan": { "post": { "tags": [ "artifacts" ], "summary": "Plan Artifact Conversion", "description": "Plan conversion from this artifact's current format to a target format.", "operationId": "plan_artifact_conversion_v1_artifacts__artifact_id__conversionPlan_post", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactConversionPlanRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactConversionPlanOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/artifacts/{artifact_id}:convert": { "post": { "tags": [ "artifacts" ], "summary": "Convert Artifact", "description": "Submit an artifact format conversion as a normal sfmapi job.", "operationId": "convert_artifact_v1_artifacts__artifact_id__convert_post", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactConvertRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/artifacts/{artifact_id}:validate": { "post": { "tags": [ "artifacts" ], "summary": "Validate Artifact", "description": "Validate an artifact descriptor and any local server-managed bytes.", "operationId": "validate_artifact_v1_artifacts__artifact_id__validate_post", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactValidationOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/artifacts:import": { "post": { "tags": [ "artifacts" ], "summary": "Import Artifact", "description": "Register an existing artifact URI for validation and downstream reuse.", "operationId": "import_artifact_v1_artifacts_import_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactImportRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageArtifactOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/artifacts/{artifact_id}": { "get": { "tags": [ "artifacts" ], "summary": "Get Artifact", "description": "Read one typed stage artifact by id.", "operationId": "get_artifact_v1_artifacts__artifact_id__get", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageArtifactOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/artifacts/{artifact_id}/content": { "get": { "tags": [ "artifacts" ], "summary": "Read Artifact Content", "description": "Serve content for local, server-managed file artifacts.\n\nRemote object-store URIs and paths outside sfmapi's managed roots\nare intentionally not dereferenced through this route.", "operationId": "read_artifact_content_v1_artifacts__artifact_id__content_get", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "download", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force Content-Disposition: attachment", "default": false, "title": "Download" }, "description": "Force Content-Disposition: attachment" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend": { "get": { "tags": [ "backend" ], "summary": "Get Backend", "description": "Read the active backend identity and extension-action links.", "operationId": "get_backend_v1_backend_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendOut" } } } } } } }, "/v1/backend/actions": { "get": { "tags": [ "backend" ], "summary": "List Actions", "description": "List backend-native extension actions.\n\nThis is the generic discovery layer for COLMAP commands and future\nbackend-specific tools. Portable sfmapi features still belong in\n``GET /v1/capabilities``; this catalog is intentionally namespaced\nand backend-specific.", "operationId": "list_actions_v1_backend_actions_get", "parameters": [ { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Page Size" } }, { "name": "include_schemas", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include each action's input/output schema in the list response.", "default": false, "title": "Include Schemas" }, "description": "Include each action's input/output schema in the list response." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_BackendActionOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/config-schemas": { "get": { "tags": [ "backend" ], "summary": "List Config Schemas", "description": "List backend-specific option schemas for portable sfmapi stages.\n\nClients use this catalog to discover which keys are valid inside a\nstage spec's ``backend_options`` object. The top-level stage spec\nremains the portable sfmapi contract.", "operationId": "list_config_schemas_v1_backend_config_schemas_get", "parameters": [ { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Page Size" } }, { "name": "include_schemas", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include JSON Schemas for each backend_options object.", "default": true, "title": "Include Schemas" }, "description": "Include JSON Schemas for each backend_options object." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_BackendConfigSchemaOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/artifact-contracts": { "get": { "tags": [ "backend" ], "summary": "List Artifact Contracts", "description": "List artifact kinds accepted and emitted by backend portable stages.", "operationId": "list_artifact_contracts_v1_backend_artifact_contracts_get", "parameters": [ { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_BackendArtifactContractOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/actions/{action_id}:validate": { "post": { "tags": [ "backend" ], "summary": "Validate Action", "description": "Validate backend action inputs without creating a job.", "operationId": "validate_action_v1_backend_actions__action_id__validate_post", "parameters": [ { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Action Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendActionValidateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendActionValidateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/actions/{action_id}:run": { "post": { "tags": [ "backend" ], "summary": "Run Action", "description": "Submit a backend-native action as a normal sfmapi job.\n\nAll execution goes through the existing job/task path, so clients\nuse ``GET /v1/jobs/{job_id}``, ``/progress``, cancellation, and SSE\nexactly as they do for standard SfM workflows.", "operationId": "run_action_v1_backend_actions__action_id__run_post", "parameters": [ { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Action Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendActionRunRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/actions/{action_id}": { "get": { "tags": [ "backend" ], "summary": "Get Action", "description": "Read one backend action descriptor including schemas.", "operationId": "get_action_v1_backend_actions__action_id__get", "parameters": [ { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Action Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendActionOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/config-schemas/{config_id}": { "get": { "tags": [ "backend" ], "summary": "Get Config Schema", "description": "Read one backend-specific option schema.", "operationId": "get_config_schema_v1_backend_config_schemas__config_id__get", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendConfigSchemaOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/artifact-contracts/{contract_id}": { "get": { "tags": [ "backend" ], "summary": "Get Artifact Contract", "description": "Read one backend artifact input/output contract.", "operationId": "get_artifact_contract_v1_backend_artifact_contracts__contract_id__get", "parameters": [ { "name": "contract_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contract Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendArtifactContractOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/providers": { "get": { "tags": [ "backend" ], "summary": "List Providers", "description": "List enabled providers discovered from installed sfm_hub plugins.", "operationId": "list_providers_v1_backend_providers_get", "parameters": [ { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ProviderOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/backend/routing": { "get": { "tags": [ "backend" ], "summary": "Get Routing", "description": "Read provider priority and named routing-profile state.", "operationId": "get_routing_v1_backend_routing_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingOut" } } } } } } }, "/v1/camera-models": { "get": { "tags": [ "camera-models" ], "summary": "List Supported Camera Models", "description": "List portable camera model parameter layouts known to sfmapi.", "operationId": "list_supported_camera_models_v1_camera_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CameraModelOut_" } } } } } } }, "/v1/uploads": { "post": { "tags": [ "uploads" ], "summary": "Init", "description": "Open a chunked-upload session.\n\nReserves an ``upload_id`` for the caller to ``PATCH`` chunks into.\n``Idempotency-Key`` (recommended) makes init replay-safe \u2014 a retry\nwith the same key returns the same upload row. Returns\n:class:`UploadOut` with ``state=\"open\"``; the row expires at\n``expires_at`` if the client never finalizes.", "operationId": "init_v1_uploads_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadInit" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/uploads/{upload_id}": { "get": { "tags": [ "uploads" ], "summary": "Status Route", "description": "Read the current state of an upload session.\n\nUseful for resuming an interrupted upload \u2014 inspect\n``received_bytes`` and ``state`` to pick the next chunk offset.\nReturns 404 if the upload has expired or never existed.", "operationId": "status_route_v1_uploads__upload_id__get", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "uploads" ], "summary": "Patch Chunk", "description": "Append one chunk of bytes to the upload.\n\nRequires ``Content-Range: bytes -/`` (RFC 7233);\nthe body length MUST equal the byte range. 422\n``ValidationError`` on malformed Content-Range or length mismatch.\nChunks are idempotent at the same offset \u2014 retries are safe.", "operationId": "patch_chunk_v1_uploads__upload_id__patch", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } }, { "name": "Content-Range", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content-Range" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/uploads/{upload_id}:finalize": { "post": { "tags": [ "uploads" ], "summary": "Finalize", "description": "Seal an upload \u2014 verify the assembled bytes match the\nexpected size and (when supplied) ``X-Content-SHA256``, then\ntransition the row to ``finalized`` with the canonical\n``blob_sha``. AIP-136 ``:finalize`` colon verb (the operation\nhas side effects beyond a Standard Update).", "operationId": "finalize_v1_uploads__upload_id__finalize_post", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } }, { "name": "X-Content-SHA256", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Content-Sha256" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects/{project_id}/datasets": { "post": { "tags": [ "datasets" ], "summary": "Create", "description": "Create a Dataset under a project.\n\n``body.source`` is a discriminated :data:`SourceSpec` (``upload``\n| ``local`` | ``s3``); the source is materialized server-side and\nbound to the new Dataset. ``camera_model`` / ``intrinsics_mode`` /\n``is_spherical`` / ``rig_config`` configure the SfM pipeline\ndefaults. 404 if the project doesn't exist for this tenant.", "operationId": "create_v1_projects__project_id__datasets_post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "datasets" ], "summary": "List ", "description": "List datasets under a project (AIP-158 paginated).\n\nIterate by threading ``next_page_token`` back; ``null`` ends the\ncursor. ``total`` is omitted (returned as ``null``) \u2014 counting\nthe full collection is a separate query and is not always cheap.", "operationId": "list__v1_projects__project_id__datasets_get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_DatasetOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects/{project_id}/datasets/{dataset_id}": { "get": { "tags": [ "datasets" ], "summary": "Get", "description": "Read a single dataset by id.\n\n422 ``ValidationError`` if the dataset belongs to a different\nproject than the one in the path; 404 if it doesn't exist for\nthis tenant at all.", "operationId": "get_v1_projects__project_id__datasets__dataset_id__get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "datasets" ], "summary": "Delete", "description": "Delete a dataset.\n\nCascades through registered images, derived feature/match files,\nsimilarity indexes, and dependent reconstructions. 422 if the\ndataset belongs to a different project; 404 if it doesn't exist.", "operationId": "delete_v1_projects__project_id__datasets__dataset_id__delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "datasets" ], "summary": "Patch", "description": "Partially update a dataset.\n\nWithout ``update_mask``, only fields present in the request body\nare written. With ``update_mask``, only the named field paths are\napplied and they must also be present in the body.\n\nThe dataset's ``source_id`` is immutable; to change image inputs,\ncreate a new dataset. 422 if the row exists but belongs to another project.", "operationId": "patch_v1_projects__project_id__datasets__dataset_id__patch", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "update_mask", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional AIP-161 comma-separated field mask. Allowed paths: name, camera_model, intrinsics_mode, is_spherical, rig_config, respect_exif_orientation, active_maskset_id.", "title": "Update Mask" }, "description": "Optional AIP-161 comma-separated field mask. Allowed paths: name, camera_model, intrinsics_mode, is_spherical, rig_config, respect_exif_orientation, active_maskset_id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetPatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}:render_cubemap": { "post": { "tags": [ "datasets" ], "summary": "Render Cubemap", "description": "Render every spherical panorama in this dataset into 6 cubemap faces.\n\nRequires the dataset to be marked ``is_spherical=true``. The\noutput directory is returned in the task result; clients can then\nregister it as a new ``local`` source for downstream pinhole-only\npipelines.", "operationId": "render_cubemap_v1_datasets__dataset_id__render_cubemap_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "face_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 8192, "minimum": 64 }, { "type": "null" } ], "description": "Pixel edge length per cubemap face", "title": "Face Size" }, "description": "Pixel edge length per cubemap face" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CubemapProjectionRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}:project_images": { "post": { "tags": [ "datasets" ], "summary": "Project Images", "description": "Run a portable projection transform over the dataset images.", "operationId": "project_images_v1_datasets__dataset_id__project_images_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectionJobRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}:render_equirectangular": { "post": { "tags": [ "datasets" ], "summary": "Render Equirectangular", "description": "Render a cubemap dataset back to equirectangular panoramas.", "operationId": "render_equirectangular_v1_datasets__dataset_id__render_equirectangular_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EquirectangularProjectionRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}:render_perspective": { "post": { "tags": [ "datasets" ], "summary": "Render Perspective", "description": "Render pinhole perspective views from spherical panoramas.", "operationId": "render_perspective_v1_datasets__dataset_id__render_perspective_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PerspectiveProjectionRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/images": { "post": { "tags": [ "images" ], "summary": "Create", "description": "Register a single image in a dataset.\n\nProvide ``blob_sha`` for upload-source datasets (the value is the\ncanonical sha returned by ``POST /v1/uploads/{id}:finalize``) or\n``rel_path`` for local-source datasets (the path relative to the\nsource root). Exactly one MUST be set; 422 ``ValidationError``\notherwise. For batch ingestion use ``POST :batchCreate``.", "operationId": "create_v1_datasets__dataset_id__images_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "images" ], "summary": "List ", "description": "List images in a dataset (AIP-158 paginated).\n\nOrdered by ``created_at`` ascending \u2014 registration order. Iterate\nby threading ``next_page_token`` back; ``null`` ends the cursor.", "operationId": "list__v1_datasets__dataset_id__images_get", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ImageOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/images:batchCreate": { "post": { "tags": [ "images" ], "summary": "Batch Create", "description": "Bulk-register images in a single transaction (AIP-231).\n\nUp to 1000 ``requests`` per call. Each entry is a complete\n``ImageCreate``; failures abort the whole batch (atomic).", "operationId": "batch_create_v1_datasets__dataset_id__images_batchCreate_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateImagesRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateImagesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/images/{name}": { "delete": { "tags": [ "images" ], "summary": "Delete", "description": "Unregister an image from a dataset by ``name``.\n\nNOTE: addressed by the human-readable ``name`` here, not the\ncanonical ``image_id`` (the audit doc captures the ergonomic\ninconsistency \u2014 kept stable in place; reads + bytes routes\nuse ``image_id``). 204 on success, 404 if no image with that\nname exists in the dataset.", "operationId": "delete_v1_datasets__dataset_id__images__name__delete", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/images/{image_id}": { "get": { "tags": [ "images" ], "summary": "Get Image", "description": "Read one image's metadata by its canonical ``image_id``.\n\nReturns the same shape as :class:`ImageOut` \u2014 width / height /\nEXIF / source pointers \u2014 without the bytes themselves. Use\n``GET /v1/images/{id}/bytes`` for the original payload.", "operationId": "get_image_v1_images__image_id__get", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "images" ], "summary": "Delete Image By Id", "description": "Unregister an image by canonical ``image_id``.\n\nThis is the AIP-122-aligned delete path. The legacy\n``DELETE /v1/datasets/{dataset_id}/images/{name}`` route remains\nfor compatibility with clients that address images by label.", "operationId": "delete_image_by_id_v1_images__image_id__delete", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/images/{image_id}/bytes": { "get": { "tags": [ "images" ], "summary": "Get Image Bytes", "description": "Stream the original image bytes. Carries an ETag for HTTP caches.", "operationId": "get_image_bytes_v1_images__image_id__bytes_get", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } }, { "name": "download", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Download" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/images/{image_id}/thumbnail": { "get": { "tags": [ "images" ], "summary": "Get Image Thumbnail", "description": "JPEG thumbnail, max edge `size` (default 256, hard-cap from settings).", "operationId": "get_image_thumbnail_v1_images__image_id__thumbnail_get", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } }, { "name": "size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 16 }, { "type": "null" } ], "description": "Max edge length in pixels.", "title": "Size" }, "description": "Max edge length in pixels." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/images/{image_id}/exif": { "get": { "tags": [ "images" ], "summary": "Get Image Exif", "description": "Return the image's EXIF metadata as a free-form dict.\n\nUses the cached ``exif_json`` row when present; otherwise falls\nback to extracting from the on-disk bytes. Returns an empty\n``exif`` map (not 404) when the source has no EXIF or the bytes\ncan't be located.", "operationId": "get_image_exif_v1_images__image_id__exif_get", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageExifResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/images/{image_id}/pose_prior": { "get": { "tags": [ "images" ], "summary": "Get Pose Prior", "description": "Return the image's PosePrior (or `null` if none is set).", "operationId": "get_pose_prior_v1_images__image_id__pose_prior_get", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PosePrior" }, { "type": "null" } ], "title": "Response Get Pose Prior V1 Images Image Id Pose Prior Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "images" ], "summary": "Put Pose Prior", "description": "Set (or replace) the PosePrior on an image.", "operationId": "put_pose_prior_v1_images__image_id__pose_prior_put", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosePrior" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosePrior" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "images" ], "summary": "Delete Pose Prior", "description": "Clear the PosePrior on an image.", "operationId": "delete_pose_prior_v1_images__image_id__pose_prior_delete", "parameters": [ { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/pose_priors": { "get": { "tags": [ "images" ], "summary": "List Dataset Pose Priors", "description": "All PosePriors for the dataset, keyed by image_id.", "operationId": "list_dataset_pose_priors_v1_datasets__dataset_id__pose_priors_get", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosePriorsBulkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "images" ], "summary": "Bulk Set Pose Priors", "description": "Bulk-set PosePriors for the dataset. Body is `{image_id: PosePrior}`.\nExisting priors for image_ids not in the body are left untouched \u2014\nuse `DELETE /v1/images/{image_id}/pose_prior` to clear individuals.", "operationId": "bulk_set_pose_priors_v1_datasets__dataset_id__pose_priors_put", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PosePrior" }, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosePriorsBulkWriteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/jobs": { "get": { "tags": [ "jobs" ], "summary": "List ", "description": "List jobs for the caller's tenant (AIP-158 paginated).\n\nMost-recent first (sorted by ``job_id`` descending \u2014 ULIDs are\ntimestamp-prefixed). Pass ``status=running`` to find active work\nor ``status=failed`` to triage. Without ``status``, all jobs in\nevery state are returned. ``next_page_token=null`` ends the\ncursor.", "operationId": "list__v1_jobs_get", "parameters": [ { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Page Size" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "pending", "running", "succeeded", "failed", "cancelled", "cancelled_dirty" ], "type": "string" }, { "type": "null" } ], "description": "Filter to one lifecycle state. Closed set: pending | running | succeeded | failed | cancelled | cancelled_dirty.", "title": "Status" }, "description": "Filter to one lifecycle state. Closed set: pending | running | succeeded | failed | cancelled | cancelled_dirty." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_JobOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/jobs/{job_id}": { "get": { "tags": [ "jobs" ], "summary": "Get", "description": "Read a job + its constituent tasks.\n\nThe canonical AIP-151 LRO poll endpoint. Clients submitting work\nvia any ``POST`` that returns ``202`` follow the ``Location``\nheader here and poll until ``status`` reaches a terminal value\n(``succeeded`` | ``failed`` | ``cancelled`` | ``cancelled_dirty``).\nTask ``outputs_ref`` carries the typed result payload for stages\nthat return data (e.g. ``localize``).", "operationId": "get_v1_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/jobs/{job_id}/artifacts": { "get": { "tags": [ "jobs" ], "summary": "List Artifacts", "description": "List typed artifacts produced by a job's tasks.\n\nBackends may produce multiple feature sets, match sets, verified\npair sets, snapshots, or provider-specific sidecars. This endpoint\nis the stable discovery surface; task ``outputs_ref`` remains a\ncompatibility payload for polling clients.", "operationId": "list_artifacts_v1_jobs__job_id__artifacts_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Page Size" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional exact artifact kind filter, e.g. matches.verified.v1.", "title": "Kind" }, "description": "Optional exact artifact kind filter, e.g. matches.verified.v1." }, { "name": "task_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional producing task id filter.", "title": "Task Id" }, "description": "Optional producing task id filter." }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional exact artifact name filter.", "title": "Name" }, "description": "Optional exact artifact name filter." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_StageArtifactOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/jobs/{job_id}/progress": { "get": { "tags": [ "jobs" ], "summary": "Progress", "description": "Return a compact progress snapshot for a job.\n\nThis is the polling counterpart to ``GET /v1/jobs/{job_id}/events``.\nIt always works from durable state: task lifecycle rows plus the\nlatest persisted progress events. ``progress`` is a best-effort\nfraction, so clients should treat it as UI telemetry rather than a\nscheduling guarantee.", "operationId": "progress_v1_jobs__job_id__progress_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobProgressOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/jobs/{job_id}:cancel": { "post": { "tags": [ "jobs" ], "summary": "Cancel", "description": "Cooperatively cancel a long-running job (AIP-151, AIP-136\n``:cancel``). ``force=true`` SIGKILLs subprocesses immediately;\ndefault is the cooperative phase-boundary stop.\n\nReturns the up-to-date ``JobOut`` row. The terminal state lands\nasynchronously \u2014 clients should follow up with ``GET\n/v1/jobs/{job_id}`` (or watch the SSE stream) to observe the\ntransition to ``cancelled`` or ``cancelled_dirty``.", "operationId": "cancel_v1_jobs__job_id__cancel_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Force" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/jobs/{job_id}/events": { "get": { "tags": [ "jobs" ], "summary": "Events", "description": "SSE stream of progress events for the given job.\n\nBody\n----\n``Content-Type: text/event-stream``. Each event is one\n:class:`~app.schemas.progress_event.ProgressEvent` JSON-encoded\nin the SSE ``data:`` field, prefixed by an ``id:`` line carrying\nthe monotonic per-job event sequence.\n\nResume (``Last-Event-ID``)\n--------------------------\nClients reconnecting after a transient disconnect SHOULD pass the\nlast event id they observed via the standard ``Last-Event-ID``\nrequest header (browsers do this automatically). The server replays\nevery persisted event with ``event_id > last_event_id`` from the\nring buffer before resuming the live tail. Sending a value larger\nthan any persisted id yields an empty replay and the live tail.\n\nTermination\n-----------\nThe stream closes (server-side EOF) once the job's status reaches\na terminal value (``succeeded`` | ``failed`` | ``cancelled`` |\n``cancelled_dirty``) AND one final drain cycle has shipped any\npending events. Without this exit condition, ``submit_and_stream``\nconsumers would block forever waiting for EOF on a job that\nalready finished. The terminal vocabulary is shared with\n``app/workers/dispatcher.py::_maybe_finalize_job`` (see ``L13``,\n``L14`` in ``decisions.md``).\n\nMid-stream deletion\n-------------------\nIf the underlying job row vanishes while the stream is open\n(e.g., tenant teardown, DB GC), the next poll cycle observes a\n``None`` job and exits as if a terminal state were reached \u2014 the\nstream closes cleanly rather than 500-ing mid-flight. Clients see\nEOF; a follow-up ``GET /v1/jobs/{job_id}`` then returns 404.\n\nPhase 1 implementation tails by polling the DB on a 1s cadence;\nPhase 5 swaps to Redis pub/sub without changing the wire shape.", "operationId": "events_v1_jobs__job_id__events_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last-Event-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/features": { "post": { "tags": [ "sfm-stages" ], "summary": "Features", "description": "Enqueue local-feature extraction on every image in the dataset.\n\nReturns 202 with a ``Location`` header pointing at the job. The\nextractor type (``sift``, ``superpoint``, ``aliked``, ...) is\nchosen via :class:`FeaturesSpec.type`; backends advertise\nsupported types via the ``features.extract.{type}`` capability\nflags. Re-running with an identical spec hits the cache.", "operationId": "features_v1_datasets__dataset_id__features_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturesRequest", "default": { "spec": { "version": 1, "type": "sift", "max_num_features": 8192, "use_gpu": true, "seed": 0, "backend_options": {}, "input_artifacts": {} } } } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/matches": { "post": { "tags": [ "sfm-stages" ], "summary": "Matches", "description": "Enqueue feature-matching across image pairs in the dataset.\n\nPair selection (``body.pairs``) and per-pair matching\n(``body.matcher``) are independent shapes (AIP-202): pick pairs\nvia exhaustive / sequential / spatial / vocabtree / retrieval /\nfrom_poses / explicit, then run any of nn-mutual / nn-ratio /\nsuperglue / lightglue / loftr against them. Optional provider\nfields disambiguate mixed deployments such as hloc retrieval with\nCOLMAP SIFT. Requires features to have been extracted; returns\n202 + ``Location``.", "operationId": "matches_v1_datasets__dataset_id__matches_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchesRequest", "default": { "pairs": { "version": 1, "strategy": "exhaustive", "overlap": 10, "retrieval_strategy": "vlad", "retrieval_k": 20, "pairs_blob_format": "image_name_pairs_txt", "backend_options": {}, "input_artifacts": {} }, "matcher": { "version": 1, "type": "nn-mutual", "use_gpu": true, "cross_check": true, "max_ratio": 0.8, "max_distance": 0.7, "backend_options": {}, "input_artifacts": {} }, "input_artifacts": {} } } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/verify": { "post": { "tags": [ "sfm-stages" ], "summary": "Verify", "description": "Enqueue two-view geometric verification on the matched pairs.\n\nFilters raw matches with RANSAC / fundamental matrix / homography\nestimation and writes the verified inlier subset to\n``two_view_geometries.json``. Required before any mapping recipe.\nReturns 202 + ``Location`` pointing at the job.", "operationId": "verify_v1_datasets__dataset_id__verify_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest", "default": { "spec": { "version": 1, "use_gpu": true, "min_inlier_ratio": 0.25, "backend_options": {}, "input_artifacts": {} }, "input_artifacts": {} } } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}": { "get": { "tags": [ "reconstructions" ], "summary": "Get", "description": "Read one reconstruction's metadata.\n\nReturns 404 if the reconstruction doesn't exist for this tenant.\nUse ``links['snapshots']`` / ``links['submodels']`` from the\nresponse to navigate into the actual outputs.", "operationId": "get_v1_reconstructions__recon_id__get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconstructionOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/submodels": { "get": { "tags": [ "reconstructions" ], "summary": "List Submodels", "description": "List the SubModels (disconnected components) of a reconstruction.\n\nAIP-158 paginated; results within a page are presented in ``idx``\norder (COLMAP component index). Most reconstructions have a\nhandful of submodels \u2014 pagination matters only for hierarchical\nruns that produce hundreds.", "operationId": "list_submodels_v1_reconstructions__recon_id__submodels_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SubModelOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/artifacts": { "get": { "tags": [ "reconstructions" ], "summary": "List Reconstruction Artifacts", "description": "List all typed stage artifacts attached to a reconstruction.\n\nUse this when a pipeline produces multiple candidate outputs, such\nas dual matchers, alternate verified pair sets, or several mapping\ncomponents.", "operationId": "list_reconstruction_artifacts_v1_reconstructions__recon_id__artifacts_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Page Size" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional exact artifact kind filter, e.g. reconstruction.snapshot.", "title": "Kind" }, "description": "Optional exact artifact kind filter, e.g. reconstruction.snapshot." }, { "name": "task_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional producing task id filter.", "title": "Task Id" }, "description": "Optional producing task id filter." }, { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional exact artifact name filter.", "title": "Name" }, "description": "Optional exact artifact name filter." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_StageArtifactOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/snapshots": { "get": { "tags": [ "reconstructions" ], "summary": "List Snapshots", "description": "List sealed snapshots for a reconstruction.\n\nReturns the full sequence of ``seq`` ints + a HAL ``_links`` block\nkeyed by ``str(seq)`` plus a ``\"latest\"`` shortcut. Each link\nblock points at the per-snapshot files (``points.bin``,\n``cameras.json``, etc). Snapshots are immutable once sealed \u2014 the\nfile routes carry strong ETags + ``immutable`` Cache-Control.", "operationId": "list_snapshots_v1_reconstructions__recon_id__snapshots_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/snapshots/{seq}/{name}": { "get": { "tags": [ "reconstructions" ], "summary": "Read Snapshot File", "description": "Serve a single sealed-snapshot file. `name` is one of:\n`cameras.json | images.json | rigs.json | frames.json |\npose_graph.json | points.bin | points_preview.bin | summary.json`.\nAnything else returns 404. Sealed snapshots are immutable, so the\nresponse carries an `ETag` and honors `If-None-Match`.", "operationId": "read_snapshot_file_v1_reconstructions__recon_id__snapshots__seq___name__get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer", "title": "Seq" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } }, { "name": "download", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force Content-Disposition: attachment", "default": false, "title": "Download" }, "description": "Force Content-Disposition: attachment" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/snapshots/{seq}/submodels/{idx}/{name}": { "get": { "tags": [ "reconstructions" ], "summary": "Read Submodel Snapshot File", "description": "Serve one sealed-snapshot file for a specific disconnected component.\n\nMulti-model mapping snapshots store component sidecars under\n``submodels/{idx}`` links backed by ``snapshots/{seq}/{idx}/``. A\nsingle-model snapshot may only have files at the snapshot root; in\nthat case ``idx=0`` falls back to the root files.", "operationId": "read_submodel_snapshot_file_v1_reconstructions__recon_id__snapshots__seq__submodels__idx___name__get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer", "title": "Seq" } }, { "name": "idx", "in": "path", "required": true, "schema": { "type": "integer", "title": "Idx" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } }, { "name": "download", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force Content-Disposition: attachment", "default": false, "title": "Download" }, "description": "Force Content-Disposition: attachment" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/snapshots/{seq}/tiles/index.json": { "get": { "tags": [ "reconstructions" ], "summary": "Tiles Index", "description": "Octree tile index for the snapshot's `points.bin`. Tiles are\ngenerated lazily on first request, then cached on disk under\n`/tiles/`. Subsequent requests for tile bytes hit the\ncache directly.", "operationId": "tiles_index_v1_reconstructions__recon_id__snapshots__seq__tiles_index_json_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer", "title": "Seq" } }, { "name": "max_level", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 6, "minimum": 0, "default": 4, "title": "Max Level" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/snapshots/{seq}/tiles/{level}/{x}/{y}/{z}.bin": { "get": { "tags": [ "reconstructions" ], "summary": "Read Tile", "description": "Serve a single octree tile in `application/x-sfm-points-v1`.", "operationId": "read_tile_v1_reconstructions__recon_id__snapshots__seq__tiles__level___x___y___z__bin_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer", "title": "Seq" } }, { "name": "level", "in": "path", "required": true, "schema": { "type": "integer", "title": "Level" } }, { "name": "x", "in": "path", "required": true, "schema": { "type": "integer", "title": "X" } }, { "name": "y", "in": "path", "required": true, "schema": { "type": "integer", "title": "Y" } }, { "name": "z", "in": "path", "required": true, "schema": { "type": "integer", "title": "Z" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/snapshots/{seq}/images/{image_id}/observations": { "get": { "tags": [ "reconstructions" ], "summary": "Image Observations", "description": "Per-image observations: which 3D points the image sees.", "operationId": "image_observations_v1_reconstructions__recon_id__snapshots__seq__images__image_id__observations_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer", "title": "Seq" } }, { "name": "image_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Image Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageObservationsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/snapshots/{seq}/points/{point3d_id}/visibility": { "get": { "tags": [ "reconstructions" ], "summary": "Point Visibility", "description": "Per-point visibility: which images observe a given 3D point.", "operationId": "point_visibility_v1_reconstructions__recon_id__snapshots__seq__points__point3d_id__visibility_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } }, { "name": "seq", "in": "path", "required": true, "schema": { "type": "integer", "title": "Seq" } }, { "name": "point3d_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Point3D Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PointVisibilityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions:merge": { "post": { "tags": [ "reconstructions" ], "summary": "Merge Recons Endpoint", "description": "Merge several reconstructions into ``target_recon_id``.\n\nAll sources MUST belong to the same project as the target. The\nmerged result is sealed as a fresh snapshot under the target's\nworkspace; the source reconstructions are left intact.", "operationId": "merge_recons_endpoint_v1_reconstructions_merge_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequest" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/correspondence_graph.json": { "get": { "tags": [ "reconstructions" ], "summary": "Read Correspondence Graph", "description": "Serve the **raw** (pre-verification) correspondence graph.\n\nLives at the reconstruction level \u2014 emitted by the match worker\nafter every match run. Use ``two_view_geometries.json`` to see the\nverified inlier subset; use this file to debug \"why didn't this\npair survive verification?\"", "operationId": "read_correspondence_graph_v1_reconstructions__recon_id__correspondence_graph_json_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/two_view_geometries.json": { "get": { "tags": [ "reconstructions" ], "summary": "Read Two View Geometries", "description": "Serve the verified two-view geometries for this reconstruction.\n\nLives at the **reconstruction** level (not per snapshot) because the\nfile tracks the database state \u2014 every verify run can update it. The\nfile is emitted by the verify worker into the reconstruction root.", "operationId": "read_two_view_geometries_v1_reconstructions__recon_id__two_view_geometries_json_get", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/submodels/{submodel_id}": { "get": { "tags": [ "reconstructions" ], "summary": "Get Submodel", "description": "Read one SubModel by its canonical ``submodel_id``.\n\nDirect read of a single connected component without going through\n``GET /v1/reconstructions/{recon_id}/submodels``. 404 if absent.", "operationId": "get_submodel_v1_submodels__submodel_id__get", "parameters": [ { "name": "submodel_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Submodel Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubModelOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/projects/{project_id}/pipelines/{recipe}": { "post": { "tags": [ "pipelines" ], "summary": "Run Recipe", "description": "Run an end-to-end mapping recipe in one POST.\n\nComposes ``features -> matches -> verify -> map -> ba -> ...``\ninto a single job DAG keyed on ``recipe`` (one of ``incremental``\n| ``global`` | ``hierarchical`` | ``spherical``). The recipe MUST\nmatch ``body.spec.kind`` \u2014 422 ``ValidationError`` if not. Each\nstage spec keeps optional provider selectors\nso mixed deployments can route hloc and COLMAP implementations\nbehind the same portable capability names. Each backend advertises\nwhich recipes it implements via the\n``pipelines.{kind}`` capability flags; unsupported recipes\nreturn ``501 capability_unavailable``. Returns 202 + a\n``Location`` header pointing at the parent job.", "operationId": "run_recipe_v1_projects__project_id__pipelines__recipe__post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } }, { "name": "recipe", "in": "path", "required": true, "schema": { "enum": [ "incremental", "global", "hierarchical", "spherical" ], "type": "string", "title": "Recipe" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/jobs/{job_id}:resume": { "post": { "tags": [ "jobs" ], "summary": "Resume", "description": "Resume a previously-cancelled or failed job from its last\nsealed snapshot (AIP-136 ``:resume``). Spawns a fresh DAG that\npicks up after the saved checkpoint.", "operationId": "resume_v1_jobs__job_id__resume_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/api-keys": { "get": { "tags": [ "admin" ], "summary": "List Keys", "description": "List every API key on file (active + revoked).\n\nRaw-key material is NEVER returned; use :func:`issue` and capture\nthe value at creation time. Ordered by ``created_at`` ascending.\n\nSee WARNING on ``POST /v1/admin/api-keys``; this route is an\noperator route and must be protected by deployment infrastructure.", "operationId": "list_keys_v1_admin_api_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ApiKeyOut" }, "type": "array", "title": "Response List Keys V1 Admin Api Keys Get" } } } } } }, "post": { "tags": [ "admin" ], "summary": "Issue", "description": "Mint a fresh API key bound to a tenant.\n\nReturns the raw key in ``raw_key`` exactly once; only a salted hash\nis persisted, so callers MUST capture the value here. Use the key\nas the ``Bearer`` token in ``Authorization`` against tenant-scoped\nroutes once ``auth_mode == \"api_key\"``.\n\nWARNING - operator route\n------------------------\nThis route is not tenant-scoped and is not protected by sfmapi's\ntenant API-key dependency. Production deployments MUST front\n``/v1/admin/...`` with an admin-only auth layer (deploy-time\nmaster key, mesh-level mTLS, infra-network-only). See ``L2`` in\n``decisions.md``.", "operationId": "issue_v1_admin_api_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueKeyBody" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueKeyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/api-keys/{api_key_id}": { "delete": { "tags": [ "admin" ], "summary": "Revoke", "description": "Revoke a previously-issued API key.\n\nSoft-delete: the row stays for audit, ``revoked_at`` is stamped\nand ``revoked=true`` shipped on the next read. Subsequent auth\nattempts with that key will fail. Idempotent; revoking an\nalready-revoked key is a 200 no-op.\n\nSee WARNING on ``POST /v1/admin/api-keys``; this route is an\noperator route and must be protected by deployment infrastructure.", "operationId": "revoke_v1_admin_api_keys__api_key_id__delete", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Api Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/plugins": { "get": { "tags": [ "admin" ], "summary": "List Plugins", "description": "List sfm_hub registry entries and local install state.", "operationId": "list_plugins_v1_admin_plugins_get", "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" } }, { "name": "page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Token" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PluginRegistryItemOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/plugins/detect-tools": { "get": { "tags": [ "admin" ], "summary": "Detect Plugin Tools", "description": "Detect locally installed external SfM executables.", "operationId": "detect_plugin_tools_v1_admin_plugins_detect_tools_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDetectionOut" } } } } } } }, "/v1/admin/plugins/entry-points": { "get": { "tags": [ "admin" ], "summary": "List Plugin Entry Points", "description": "List installed Python entry points in the sfmapi backend group.", "operationId": "list_plugin_entry_points_v1_admin_plugins_entry_points_get", "parameters": [ { "name": "load", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Load" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PluginEntryPointOut_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/plugins/{plugin_id}": { "get": { "tags": [ "admin" ], "summary": "Get Plugin", "description": "Read one sfm_hub plugin manifest and local install state.", "operationId": "get_plugin_v1_admin_plugins__plugin_id__get", "parameters": [ { "name": "plugin_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plugin Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDetailOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/plugins/{plugin_id}:install": { "post": { "tags": [ "admin" ], "summary": "Install Plugin", "description": "Plan or run an operator-scoped plugin install.", "operationId": "install_plugin_v1_admin_plugins__plugin_id__install_post", "parameters": [ { "name": "plugin_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plugin Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginInstallRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginInstallResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/plugins/{plugin_id}:enable": { "post": { "tags": [ "admin" ], "summary": "Enable Plugin", "description": "Enable an installed plugin for provider discovery.", "operationId": "enable_plugin_v1_admin_plugins__plugin_id__enable_post", "parameters": [ { "name": "plugin_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plugin Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDetailOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/plugins/{plugin_id}:disable": { "post": { "tags": [ "admin" ], "summary": "Disable Plugin", "description": "Disable a plugin without uninstalling its Python package.", "operationId": "disable_plugin_v1_admin_plugins__plugin_id__disable_post", "parameters": [ { "name": "plugin_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plugin Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDetailOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/plugins/{plugin_id}:doctor": { "post": { "tags": [ "admin" ], "summary": "Doctor Plugin", "description": "Run local operator diagnostics for one plugin.", "operationId": "doctor_plugin_v1_admin_plugins__plugin_id__doctor_post", "parameters": [ { "name": "plugin_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Plugin Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDoctorOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/routing/profiles": { "post": { "tags": [ "admin" ], "summary": "Create Routing Profile", "description": "Create or replace a named provider routing profile.", "operationId": "create_routing_profile_v1_admin_routing_profiles_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/routing/default": { "post": { "tags": [ "admin" ], "summary": "Set Default Routing Profile", "description": "Set the default provider routing profile for this sfmapi process.", "operationId": "set_default_routing_profile_v1_admin_routing_default_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingProfileAssignmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/routing/projects/{project_id}": { "post": { "tags": [ "admin" ], "summary": "Set Project Routing Profile", "description": "Assign a provider routing profile to one project id.", "operationId": "set_project_routing_profile_v1_admin_routing_projects__project_id__post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingProfileAssignmentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/admin/routing/workspaces": { "post": { "tags": [ "admin" ], "summary": "Set Workspace Routing Profile", "description": "Assign a provider routing profile to the current workspace root.", "operationId": "set_workspace_routing_profile_v1_admin_routing_workspaces_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingProfileAssignmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/similarity": { "get": { "tags": [ "similarity" ], "summary": "Neighbors", "description": "Return the k images most similar to `image_id`.\n\nFor `strategy=dhash` the index is built lazily on first call and\ncached on disk; subsequent calls reuse the cache until the\ndataset's `manifest_hash` changes.", "operationId": "neighbors_v1_datasets__dataset_id__similarity_get", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "image_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The image to query against.", "title": "Image Id" }, "description": "The image to query against." }, { "name": "k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 5, "title": "K" } }, { "name": "strategy", "in": "query", "required": false, "schema": { "type": "string", "default": "dhash", "title": "Strategy" } }, { "name": "include_self", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Self" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarityQueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/datasets/{dataset_id}/similarity:build": { "post": { "tags": [ "similarity" ], "summary": "Build", "description": "Build (or rebuild) the similarity index for the dataset.\n\n`dhash` builds synchronously using the optional image-processing\ndependency. `vlad` enqueues a worker job (requires pycolmap + SIFT\nextraction per image) and returns ``202`` with a `Location` header\npointing at the job.", "operationId": "build_v1_datasets__dataset_id__similarity_build_post", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Id" } }, { "name": "strategy", "in": "query", "required": false, "schema": { "type": "string", "default": "dhash", "title": "Strategy" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Force" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarityBuildResponse" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } }, "description": "Accepted" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/localize": { "post": { "tags": [ "localize" ], "summary": "Localize", "description": "Localize a single query image against the reconstruction.\n\nThe job's task carries a :class:`~app.schemas.api.scene.LocalizationResult`-\nshaped payload in its ``outputs_ref`` once finished.", "operationId": "localize_v1_reconstructions__recon_id__localize_post", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalizationRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}/georegister": { "post": { "tags": [ "localize" ], "summary": "Georegister", "description": "Apply a Sim(3) similarity transform to the reconstruction.\n\nThe worker rewrites every camera + 3D point and seals a fresh\nsnapshot. Clients then read the new snapshot the same way they\nread post-mapping snapshots.", "operationId": "georegister_v1_reconstructions__recon_id__georegister_post", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sim3" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/reconstructions/{recon_id}:to_cubemap": { "post": { "tags": [ "localize" ], "summary": "To Cubemap", "description": "Convert a spherical reconstruction to a 6-face cubemap rig.\n\nRequires the dataset to be marked ``is_spherical=true``. The\nworker re-projects each panorama into 6 faces, builds a cubemap\nrig + frames, and seals a fresh snapshot whose ``rigs.json`` and\n``frames.json`` carry the cubemap layout.", "operationId": "to_cubemap_v1_reconstructions__recon_id__to_cubemap_post", "parameters": [ { "name": "recon_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Recon Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/capabilities": { "get": { "tags": [ "capabilities" ], "summary": "Capabilities", "description": "Discovery: backend identity + feature flags this deployment exposes.\n\nClients MUST hit this once at startup and cache the result for\nthe duration of the connection. Use it to gate UI affordances and\nshort-circuit against a 501 round-trip on unsupported operations.\n\nFeature names\n-------------\nThe ``features`` map keys are dot-notated, mirroring AIP-style\ncapability namespaces:\n\n- ``features.extract.{type}`` \u2014 feature extractor types\n (``sift`` | ``superpoint`` | ``aliked`` | ...).\n- ``matchers.{type}`` \u2014 per-pair matcher implementations.\n- ``pairs.{strategy}`` \u2014 pair-selection strategies\n (``exhaustive`` | ``vocabtree`` | ``retrieval`` | ...).\n- ``pipelines.{kind}`` \u2014 mapping recipes (``incremental`` |\n ``global`` | ``hierarchical`` | ``spherical``).\n- ``ba.{mode}`` \u2014 bundle-adjustment modes.\n- ``mesh.{method}`` / ``sources.{kind}`` \u2014 etc.\n\nAbsence rule\n------------\nA feature key absent from the map means **unsupported** by this\ndeployment. Endpoints that require an unsupported feature return\n``501 capability_unavailable`` with the canonical name in\n``capability``. Never assume unlisted keys are ``true``; SDK shims\nuse :func:`supports(name)` (Python / TS / C++) which checks for\nthe exact key + truthy value.", "operationId": "capabilities_v1_capabilities_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesOut" } } } } } } }, "/v1/oneshot/features": { "post": { "tags": [ "oneshot" ], "summary": "Oneshot Features", "description": "Extract local features from a single image. Bytes-in /\ntyped-result-out. No persistence.\n\nMirrors the parameter set of :class:`FeaturesSpec`. The image\nbytes are read from the request body; the ``Content-Type`` header\nis used to choose a tempfile extension if present, else the\nbytes are sniffed.\n\nReturns the keypoints + base64-encoded float32 descriptors\ninline. For batch / multi-image / multi-stage flows, use the\nresource API instead.", "operationId": "oneshot_features_v1_oneshot_features_post", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "sift", "superpoint", "aliked", "disk", "r2d2", "d2net" ], "type": "string", "description": "Local feature extractor.", "default": "sift", "title": "Type" }, "description": "Local feature extractor." }, { "name": "max_num_features", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 65536, "minimum": 1, "default": 8192, "title": "Max Num Features" } }, { "name": "use_gpu", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Use Gpu" } }, { "name": "seed", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Seed" } }, { "name": "Content-Type", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content-Type" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotFeaturesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/oneshot/localize": { "post": { "tags": [ "oneshot" ], "summary": "Oneshot Localize", "description": "Localize a single image against an existing reconstruction.\nBytes-in / typed-result-out. No persistence.\n\nCollapses the eight-step \"upload + register + submit-localize +\npoll-job + decode\" flow to one HTTP request. The query image is\nheld in memory and (briefly) on disk in a tempdir for pycolmap;\nno Image / Blob / Upload / Job row is created.", "operationId": "oneshot_localize_v1_oneshot_localize_post", "parameters": [ { "name": "recon_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Existing reconstruction to localize against.", "title": "Recon Id" }, "description": "Existing reconstruction to localize against." }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "sift", "superpoint", "aliked", "disk", "r2d2", "d2net" ], "type": "string", "description": "Local feature extractor.", "default": "sift", "title": "Type" }, "description": "Local feature extractor." }, { "name": "max_num_features", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 65536, "minimum": 1, "default": 8192, "title": "Max Num Features" } }, { "name": "use_gpu", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Use Gpu" } }, { "name": "seed", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Seed" } }, { "name": "Content-Type", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content-Type" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneShotLocalizeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ApiKeyOut": { "properties": { "api_key_id": { "type": "string", "title": "Api Key Id" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "revoked": { "type": "boolean", "title": "Revoked" } }, "type": "object", "required": [ "api_key_id", "tenant_id", "name", "revoked" ], "title": "ApiKeyOut" }, "ArtifactConversionOut": { "properties": { "from_format": { "type": "string", "title": "From Format" }, "to_format": { "type": "string", "title": "To Format" }, "lossless": { "type": "boolean", "title": "Lossless", "default": false }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "additionalProperties": false, "type": "object", "required": [ "from_format", "to_format" ], "title": "ArtifactConversionOut", "description": "Advertised conversion between artifact formats." }, "ArtifactConversionPlanOut": { "properties": { "artifact_id": { "type": "string", "title": "Artifact Id" }, "source_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Format" }, "target_format": { "type": "string", "title": "Target Format" }, "conversion_required": { "type": "boolean", "title": "Conversion Required" }, "executable": { "type": "boolean", "title": "Executable" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "steps": { "items": { "$ref": "#/components/schemas/ArtifactConversionStepOut" }, "type": "array", "title": "Steps" } }, "additionalProperties": false, "type": "object", "required": [ "artifact_id", "target_format", "conversion_required", "executable" ], "title": "ArtifactConversionPlanOut", "description": "Conversion compatibility result for an artifact." }, "ArtifactConversionPlanRequest": { "properties": { "to_format": { "anyOf": [ { "type": "string", "maxLength": 96, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }, { "type": "null" } ], "title": "To Format", "description": "Exact target format id. Mutually compatible with accepted_formats." }, "accepted_formats": { "items": { "type": "string" }, "type": "array", "title": "Accepted Formats", "description": "Acceptable target format ids in preference order." }, "require_lossless": { "type": "boolean", "title": "Require Lossless", "default": false } }, "additionalProperties": false, "type": "object", "title": "ArtifactConversionPlanRequest", "description": "Ask sfmapi to choose or validate an artifact format conversion." }, "ArtifactConversionStepOut": { "properties": { "contract_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contract Id" }, "backend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Backend" }, "from_format": { "type": "string", "title": "From Format" }, "to_format": { "type": "string", "title": "To Format" }, "lossless": { "type": "boolean", "title": "Lossless", "default": false }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "additionalProperties": false, "type": "object", "required": [ "from_format", "to_format" ], "title": "ArtifactConversionStepOut", "description": "One conversion step selected from backend contracts." }, "ArtifactConvertRequest": { "properties": { "to_format": { "anyOf": [ { "type": "string", "maxLength": 96, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }, { "type": "null" } ], "title": "To Format", "description": "Exact target format id. Mutually compatible with accepted_formats." }, "accepted_formats": { "items": { "type": "string" }, "type": "array", "title": "Accepted Formats", "description": "Acceptable target format ids in preference order." }, "require_lossless": { "type": "boolean", "title": "Require Lossless", "default": false }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "to_kind": { "anyOf": [ { "type": "string", "maxLength": 96, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }, { "type": "null" } ], "title": "To Kind" }, "options": { "additionalProperties": true, "type": "object", "title": "Options" } }, "additionalProperties": false, "type": "object", "title": "ArtifactConvertRequest", "description": "Submit a conversion job for one artifact." }, "ArtifactFileRef": { "properties": { "name": { "type": "string", "title": "Name" }, "uri": { "type": "string", "title": "Uri" }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Type" }, "sha256": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 64 }, { "type": "null" } ], "title": "Sha256" }, "byte_size": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Byte Size" } }, "additionalProperties": false, "type": "object", "required": [ "name", "uri" ], "title": "ArtifactFileRef", "description": "One file that belongs to a portable artifact manifest." }, "ArtifactFormatOut": { "properties": { "format_id": { "type": "string", "title": "Format Id" }, "artifact_type": { "type": "string", "title": "Artifact Type" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "schema_version": { "type": "integer", "title": "Schema Version" }, "media_types": { "items": { "type": "string" }, "type": "array", "title": "Media Types" }, "json_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Json Schema" }, "examples": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Examples" }, "portable": { "type": "boolean", "title": "Portable", "default": true } }, "additionalProperties": false, "type": "object", "required": [ "format_id", "artifact_type", "title", "description", "schema_version", "media_types" ], "title": "ArtifactFormatOut", "description": "Documented core artifact interchange format." }, "ArtifactImportRequest": { "properties": { "project_id": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Project Id" }, "recon_id": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Recon Id" }, "dataset_id": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Dataset Id" }, "kind": { "type": "string", "maxLength": 96, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$", "title": "Kind" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "uri": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Uri" }, "media_type": { "anyOf": [ { "type": "string", "maxLength": 127 }, { "type": "null" } ], "title": "Media Type" }, "artifact_format": { "anyOf": [ { "type": "string", "maxLength": 96, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }, { "type": "null" } ], "title": "Artifact Format" }, "artifact_type": { "anyOf": [ { "type": "string", "maxLength": 96, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }, { "type": "null" } ], "title": "Artifact Type" }, "schema_version": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Schema Version" }, "files": { "items": { "$ref": "#/components/schemas/ArtifactFileRef" }, "type": "array", "title": "Files" }, "sha256": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 64 }, { "type": "null" } ], "title": "Sha256" }, "byte_size": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Byte Size" }, "coordinate_frame": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Coordinate Frame" }, "producer": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Producer" }, "summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Summary" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "additionalProperties": false, "type": "object", "required": [ "project_id", "kind" ], "title": "ArtifactImportRequest", "description": "Register an existing artifact URI as a typed sfmapi artifact.\n\nImports do not copy bytes. They create a completed import job/task\nthat owns the artifact descriptor so the artifact can be validated,\nconverted, and used as a downstream stage input." }, "ArtifactKindOut": { "properties": { "kind": { "type": "string", "title": "Kind" }, "artifact_type": { "type": "string", "title": "Artifact Type" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "durable": { "type": "boolean", "title": "Durable" }, "artifact_format": { "type": "string", "title": "Artifact Format", "description": "Default canonical format id for this kind." }, "schema_version": { "type": "integer", "title": "Schema Version" } }, "additionalProperties": false, "type": "object", "required": [ "kind", "artifact_type", "title", "description", "durable", "artifact_format", "schema_version" ], "title": "ArtifactKindOut", "description": "Documented core artifact kind." }, "ArtifactRef": { "properties": { "artifact_id": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Artifact Id" }, "kind": { "anyOf": [ { "type": "string", "maxLength": 96, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$" }, { "type": "null" } ], "title": "Kind", "description": "Optional expected artifact kind. The request fails if it does not match." } }, "additionalProperties": false, "type": "object", "required": [ "artifact_id" ], "title": "ArtifactRef", "description": "Reference to a stage artifact used as a downstream stage input." }, "ArtifactValidationIssueOut": { "properties": { "level": { "type": "string", "pattern": "^(error|warning)$", "title": "Level" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Field" }, "message": { "type": "string", "title": "Message" } }, "additionalProperties": false, "type": "object", "required": [ "level", "message" ], "title": "ArtifactValidationIssueOut", "description": "One artifact validation problem or warning." }, "ArtifactValidationOut": { "properties": { "artifact_id": { "type": "string", "title": "Artifact Id" }, "valid": { "type": "boolean", "title": "Valid" }, "artifact_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Format" }, "artifact_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Type" }, "checked_content": { "type": "boolean", "title": "Checked Content", "default": false }, "issues": { "items": { "$ref": "#/components/schemas/ArtifactValidationIssueOut" }, "type": "array", "title": "Issues" } }, "additionalProperties": false, "type": "object", "required": [ "artifact_id", "valid" ], "title": "ArtifactValidationOut", "description": "Best-effort validation result for an artifact descriptor and bytes." }, "BackendActionOut": { "properties": { "action_id": { "type": "string", "title": "Action Id" }, "backend": { "type": "string", "title": "Backend" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "stability": { "type": "string", "enum": [ "stable", "experimental", "backend_extension", "deprecated" ], "title": "Stability", "default": "backend_extension" }, "side_effects": { "type": "string", "enum": [ "none", "read", "write", "unknown" ], "title": "Side Effects", "default": "unknown" }, "long_running": { "type": "boolean", "title": "Long Running", "default": true }, "supports_progress": { "type": "boolean", "title": "Supports Progress", "default": false }, "idempotent": { "type": "boolean", "title": "Idempotent", "default": false }, "gpu_required": { "type": "boolean", "title": "Gpu Required", "default": true }, "required_capabilities": { "items": { "type": "string" }, "type": "array", "title": "Required Capabilities" }, "input_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Schema" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "action_id", "backend", "display_name" ], "title": "BackendActionOut", "description": "Discoverable backend-native operation.\n\n``action_id`` is namespaced by the backend or tool family, for\nexample ``colmap.feature_extractor``. Portable clients should treat\naction ids as opaque strings and inspect ``input_schema`` before\npresenting a UI or constructing a request." }, "BackendActionRunRequest": { "properties": { "project_id": { "type": "string", "minLength": 1, "title": "Project Id" }, "inputs": { "additionalProperties": true, "type": "object", "title": "Inputs" } }, "additionalProperties": false, "type": "object", "required": [ "project_id" ], "title": "BackendActionRunRequest", "description": "Submit a backend-native action as an sfmapi job." }, "BackendActionValidateRequest": { "properties": { "inputs": { "additionalProperties": true, "type": "object", "title": "Inputs" } }, "additionalProperties": false, "type": "object", "title": "BackendActionValidateRequest", "description": "Validate action input without submitting work." }, "BackendActionValidateResponse": { "properties": { "action_id": { "type": "string", "title": "Action Id" }, "valid": { "type": "boolean", "title": "Valid" }, "errors": { "items": { "$ref": "#/components/schemas/BackendActionValidationErrorOut" }, "type": "array", "title": "Errors" }, "normalized_inputs": { "additionalProperties": true, "type": "object", "title": "Normalized Inputs" } }, "type": "object", "required": [ "action_id", "valid" ], "title": "BackendActionValidateResponse" }, "BackendActionValidationErrorOut": { "properties": { "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Field" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "BackendActionValidationErrorOut" }, "BackendArtifactContractOut": { "properties": { "contract_id": { "type": "string", "title": "Contract Id" }, "backend": { "type": "string", "title": "Backend" }, "stage": { "type": "string", "title": "Stage" }, "capability": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Capability" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "accepts": { "items": { "type": "string" }, "type": "array", "title": "Accepts" }, "emits": { "items": { "type": "string" }, "type": "array", "title": "Emits" }, "accepts_formats": { "items": { "type": "string" }, "type": "array", "title": "Accepts Formats" }, "emits_formats": { "items": { "type": "string" }, "type": "array", "title": "Emits Formats" }, "preferred": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preferred" }, "preferred_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preferred Format" }, "conversions": { "items": { "$ref": "#/components/schemas/ArtifactConversionOut" }, "type": "array", "title": "Conversions" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "contract_id", "backend", "stage", "display_name" ], "title": "BackendArtifactContractOut", "description": "Discoverable artifact input/output contract for a portable stage." }, "BackendConfigSchemaOut": { "properties": { "config_id": { "type": "string", "title": "Config Id" }, "backend": { "type": "string", "title": "Backend" }, "stage": { "type": "string", "title": "Stage" }, "capability": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Capability" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "option_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Option Schema" }, "defaults": { "additionalProperties": true, "type": "object", "title": "Defaults" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "config_id", "backend", "stage", "display_name" ], "title": "BackendConfigSchemaOut", "description": "Discoverable backend-specific options for a portable sfmapi stage.\n\nClients send these settings in the stage spec's ``backend_options``\nobject. Portable knobs stay on the top-level stage spec." }, "BackendInfoOut": { "properties": { "name": { "type": "string", "title": "Name" }, "version": { "type": "string", "title": "Version" }, "vendor": { "type": "string", "title": "Vendor", "default": "" } }, "additionalProperties": false, "type": "object", "required": [ "name", "version" ], "title": "BackendInfoOut" }, "BackendOut": { "properties": { "name": { "type": "string", "title": "Name" }, "version": { "type": "string", "title": "Version" }, "vendor": { "type": "string", "title": "Vendor", "default": "" }, "runtime_versions": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Runtime Versions" }, "action_count": { "type": "integer", "title": "Action Count", "default": 0 }, "config_schema_count": { "type": "integer", "title": "Config Schema Count", "default": 0 }, "artifact_contract_count": { "type": "integer", "title": "Artifact Contract Count", "default": 0 }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "name", "version" ], "title": "BackendOut", "description": "Active backend summary plus extension-action availability." }, "BackendVersion": { "properties": { "name": { "type": "string", "title": "Name" }, "version": { "type": "string", "title": "Version" }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vendor" }, "runtime_versions": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Runtime Versions" } }, "type": "object", "required": [ "name", "version" ], "title": "BackendVersion", "description": "Backend identity + freeform engine version map.\n\nsfmapi has no concrete backend; whatever real backend is\nregistered fills in its own ``runtime_versions`` keys (e.g.\n``{\"colmap_sha\": \"...\", \"cuda_arch\": \"120\"}``). ``None`` when\nno backend is registered." }, "BatchCreateImagesRequest": { "properties": { "requests": { "items": { "$ref": "#/components/schemas/ImageCreate" }, "type": "array", "maxItems": 1000, "title": "Requests" } }, "type": "object", "title": "BatchCreateImagesRequest", "description": "AIP-231 batch-create request body. Each entry is a complete\n``ImageCreate``; the server registers them all in a single\ntransaction." }, "BatchCreateImagesResponse": { "properties": { "images": { "items": { "$ref": "#/components/schemas/ImageOut" }, "type": "array", "title": "Images" } }, "type": "object", "title": "BatchCreateImagesResponse", "description": "AIP-231 batch-create response \u2014 the same shape every batch\nendpoint should return: a list of the created resources, in\nrequest-order." }, "CameraModelOut": { "properties": { "model": { "type": "string", "title": "Model" }, "projection": { "type": "string", "enum": [ "pinhole", "fisheye", "spherical", "omnidirectional", "other" ], "title": "Projection" }, "distortion": { "type": "string", "enum": [ "none", "radial", "opencv_brown", "opencv_fisheye", "other" ], "title": "Distortion" }, "params": { "items": { "type": "string" }, "type": "array", "title": "Params" }, "aliases": { "items": { "type": "string" }, "type": "array", "title": "Aliases" }, "spherical": { "type": "boolean", "title": "Spherical", "default": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } }, "additionalProperties": false, "type": "object", "required": [ "model", "projection", "distortion" ], "title": "CameraModelOut", "description": "Portable description of a camera model's parameter layout." }, "CapabilitiesOut": { "properties": { "schema_version": { "type": "integer", "title": "Schema Version", "default": 1 }, "backend": { "$ref": "#/components/schemas/BackendInfoOut" }, "features": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Features" } }, "additionalProperties": false, "type": "object", "required": [ "backend" ], "title": "CapabilitiesOut", "description": "Snapshot of what the current deployment supports.\n\n``schema_version`` tracks the wire envelope shape \u2014 independent\nof the feature flags themselves, which are negotiated via the\n``features`` dict." }, "Compatibility": { "properties": { "sfmapi": { "type": "string", "title": "Sfmapi", "default": ">=0.0.1" }, "python": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Python", "default": ">=3.12,<3.13" }, "os": { "items": { "type": "string" }, "type": "array", "title": "Os" }, "cuda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cuda" }, "tool_versions": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Tool Versions" } }, "additionalProperties": true, "type": "object", "title": "Compatibility" }, "Conformance": { "properties": { "status": { "type": "string", "enum": [ "not_run", "partial", "passing", "failing" ], "title": "Status", "default": "not_run" }, "suite": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suite" }, "report_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Url" }, "checked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checked At" } }, "additionalProperties": false, "type": "object", "title": "Conformance" }, "CubemapProjectionRequest": { "properties": { "operation": { "type": "string", "const": "equirectangular_to_cubemap", "title": "Operation", "default": "equirectangular_to_cubemap" }, "cubemap": { "anyOf": [ { "$ref": "#/components/schemas/CubemapProjectionSpec" }, { "type": "null" } ] }, "equirectangular": { "anyOf": [ { "$ref": "#/components/schemas/EquirectangularProjectionSpec" }, { "type": "null" } ] }, "perspective": { "anyOf": [ { "$ref": "#/components/schemas/PerspectiveProjectionSpec" }, { "type": "null" } ] } }, "type": "object", "title": "CubemapProjectionRequest" }, "CubemapProjectionSpec": { "properties": { "convention": { "type": "string", "const": "sfmapi-opencv", "title": "Convention", "default": "sfmapi-opencv" }, "face_size": { "type": "integer", "maximum": 8192.0, "minimum": 64.0, "title": "Face Size", "default": 1024 }, "face_order": { "items": { "type": "string", "enum": [ "front", "right", "back", "left", "up", "down" ] }, "type": "array", "title": "Face Order" }, "sampling": { "$ref": "#/components/schemas/ProjectionSampling" }, "output": { "$ref": "#/components/schemas/ProjectionOutputOptions" } }, "type": "object", "title": "CubemapProjectionSpec", "description": "Equirectangular panorama to six cubemap faces." }, "DatasetCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name" }, "source": { "oneOf": [ { "$ref": "#/components/schemas/UploadSourceSpec" }, { "$ref": "#/components/schemas/LocalSourceSpec" }, { "$ref": "#/components/schemas/S3SourceSpec" } ], "title": "Source", "discriminator": { "propertyName": "kind", "mapping": { "local": "#/components/schemas/LocalSourceSpec", "s3": "#/components/schemas/S3SourceSpec", "upload": "#/components/schemas/UploadSourceSpec" } } }, "camera_model": { "type": "string", "title": "Camera Model", "default": "SIMPLE_RADIAL" }, "intrinsics_mode": { "type": "string", "enum": [ "single_camera", "per_image", "per_folder" ], "title": "Intrinsics Mode", "default": "single_camera" }, "is_spherical": { "type": "boolean", "title": "Is Spherical", "default": false }, "rig_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Rig Config" }, "respect_exif_orientation": { "type": "boolean", "title": "Respect Exif Orientation", "default": false } }, "type": "object", "required": [ "name", "source" ], "title": "DatasetCreate" }, "DatasetOut": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "dataset_id": { "type": "string", "title": "Dataset Id" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "project_id": { "type": "string", "title": "Project Id" }, "source_id": { "type": "string", "title": "Source Id" }, "name": { "type": "string", "title": "Name" }, "camera_model": { "type": "string", "title": "Camera Model" }, "intrinsics_mode": { "type": "string", "title": "Intrinsics Mode" }, "is_spherical": { "type": "boolean", "title": "Is Spherical" }, "respect_exif_orientation": { "type": "boolean", "title": "Respect Exif Orientation" }, "rig_config_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Rig Config Json" }, "active_maskset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Active Maskset Id" }, "manifest_hash": { "type": "string", "title": "Manifest Hash" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "type": "object", "required": [ "created_at", "dataset_id", "tenant_id", "project_id", "source_id", "name", "camera_model", "intrinsics_mode", "is_spherical", "respect_exif_orientation", "manifest_hash" ], "title": "DatasetOut", "description": "Wire shape of a Dataset row.\n\nA Dataset binds an image source (``source_id`` -> one of the\n:data:`SourceSpec` variants) to per-dataset SfM settings:\n``camera_model`` (COLMAP camera-model string), ``intrinsics_mode``\n(single shared / per-image / per-folder), and the spherical /\nrig metadata. ``manifest_hash`` is the content-addressed\nfingerprint of the materialized image set; downstream stages\n(features, similarity) cache against it." }, "DatasetPatch": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "camera_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Camera Model" }, "intrinsics_mode": { "anyOf": [ { "type": "string", "enum": [ "single_camera", "per_image", "per_folder" ] }, { "type": "null" } ], "title": "Intrinsics Mode" }, "is_spherical": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Spherical" }, "rig_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Rig Config" }, "respect_exif_orientation": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Respect Exif Orientation" }, "active_maskset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Active Maskset Id" } }, "type": "object", "title": "DatasetPatch", "description": "Partial update. Unset fields are left untouched. The dataset's\n`source_id` is immutable \u2014 to change images, create a new dataset." }, "DockerRuntime": { "properties": { "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "build_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Build Context" } }, "additionalProperties": false, "type": "object", "title": "DockerRuntime" }, "DoctorCheck": { "properties": { "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "enum": [ "pass", "warn", "fail" ], "title": "Status" }, "detail": { "type": "string", "title": "Detail" } }, "additionalProperties": false, "type": "object", "required": [ "name", "status", "detail" ], "title": "DoctorCheck" }, "EquirectangularProjectionRequest": { "properties": { "operation": { "type": "string", "const": "cubemap_to_equirectangular", "title": "Operation", "default": "cubemap_to_equirectangular" }, "cubemap": { "anyOf": [ { "$ref": "#/components/schemas/CubemapProjectionSpec" }, { "type": "null" } ] }, "equirectangular": { "anyOf": [ { "$ref": "#/components/schemas/EquirectangularProjectionSpec" }, { "type": "null" } ] }, "perspective": { "anyOf": [ { "$ref": "#/components/schemas/PerspectiveProjectionSpec" }, { "type": "null" } ] } }, "type": "object", "title": "EquirectangularProjectionRequest" }, "EquirectangularProjectionSpec": { "properties": { "convention": { "type": "string", "const": "sfmapi-opencv", "title": "Convention", "default": "sfmapi-opencv" }, "width": { "anyOf": [ { "type": "integer", "maximum": 65536.0, "minimum": 64.0 }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer", "maximum": 32768.0, "minimum": 32.0 }, { "type": "null" } ], "title": "Height" }, "sampling": { "$ref": "#/components/schemas/ProjectionSampling" }, "output": { "$ref": "#/components/schemas/ProjectionOutputOptions" } }, "type": "object", "title": "EquirectangularProjectionSpec", "description": "Cubemap faces back to an equirectangular panorama." }, "ExternalToolRuntime": { "properties": { "executable_names": { "items": { "type": "string" }, "type": "array", "title": "Executable Names" }, "env_vars": { "items": { "type": "string" }, "type": "array", "title": "Env Vars" }, "version_args": { "items": { "type": "string" }, "type": "array", "title": "Version Args" } }, "additionalProperties": false, "type": "object", "title": "ExternalToolRuntime" }, "FeaturesRequest": { "properties": { "spec": { "$ref": "#/components/schemas/FeaturesSpec", "default": { "version": 1, "type": "sift", "max_num_features": 8192, "use_gpu": true, "seed": 0, "backend_options": {}, "input_artifacts": {} } } }, "additionalProperties": false, "type": "object", "title": "FeaturesRequest" }, "FeaturesSpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "type": { "type": "string", "enum": [ "sift", "superpoint", "aliked", "disk", "r2d2", "d2net" ], "title": "Type", "default": "sift" }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector when more than one registered provider can run the same feature type, for example 'colmap' or 'hloc'. Portable capability checks still use type." }, "max_num_features": { "type": "integer", "title": "Max Num Features", "default": 8192 }, "use_gpu": { "type": "boolean", "title": "Use Gpu", "default": true }, "seed": { "type": "integer", "title": "Seed", "default": 0 }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific feature-extraction options. Discover supported keys with GET /v1/backend/config-schemas." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references for advanced or backend-specific feature extraction flows." } }, "type": "object", "title": "FeaturesSpec", "description": "Type-tagged feature extractor request.\n\nBackends report which ``type`` values they support via the\n``features.extract.{type}`` capability flags. Unsupported types\nreturn 501 with the canonical capability name.\n\nBackend-specific extractor controls belong in ``backend_options``." }, "GlobalSpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector when more than one registered provider can run the same portable mapping recipe." }, "seed": { "type": "integer", "title": "Seed", "default": 0 }, "max_runtime_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Runtime Seconds" }, "snapshot_frames_freq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Snapshot Frames Freq", "default": 50 }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific mapping options. Discover supported keys with GET /v1/backend/config-schemas and keep portable settings in the top-level spec fields." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references. Core roles include verified_matches, snapshot, and submodel; backend-specific roles may use the same dot-key syntax as artifact kinds." }, "kind": { "type": "string", "const": "global", "title": "Kind", "default": "global" }, "backend": { "type": "string", "enum": [ "AUTO", "BAXX", "CERES" ], "title": "Backend", "default": "AUTO" }, "formulation": { "type": "string", "enum": [ "AUTO", "EXPLICIT_SCALE", "ELIMINATED_SCALE" ], "title": "Formulation", "default": "AUTO" }, "use_incremental_quality_fallback": { "type": "boolean", "title": "Use Incremental Quality Fallback", "default": true } }, "type": "object", "title": "GlobalSpec" }, "GpsCoord": { "properties": { "lat": { "type": "number", "title": "Lat" }, "lng": { "type": "number", "title": "Lng" }, "alt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Alt" }, "horiz_accuracy_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Horiz Accuracy M" }, "vert_accuracy_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Vert Accuracy M" } }, "type": "object", "required": [ "lat", "lng" ], "title": "GpsCoord", "description": "WGS84 geographic coordinate (lat/lng in degrees, alt in meters)." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "ok" } }, "type": "object", "title": "HealthResponse" }, "HierarchicalSpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector when more than one registered provider can run the same portable mapping recipe." }, "seed": { "type": "integer", "title": "Seed", "default": 0 }, "max_runtime_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Runtime Seconds" }, "snapshot_frames_freq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Snapshot Frames Freq", "default": 50 }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific mapping options. Discover supported keys with GET /v1/backend/config-schemas and keep portable settings in the top-level spec fields." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references. Core roles include verified_matches, snapshot, and submodel; backend-specific roles may use the same dot-key syntax as artifact kinds." }, "kind": { "type": "string", "const": "hierarchical", "title": "Kind", "default": "hierarchical" }, "cluster_max_size": { "type": "integer", "title": "Cluster Max Size", "default": 100 }, "cluster_overlap": { "type": "integer", "title": "Cluster Overlap", "default": 25 } }, "type": "object", "title": "HierarchicalSpec" }, "ImageCreate": { "properties": { "name": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Name" }, "blob_sha": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 64 }, { "type": "null" } ], "title": "Blob Sha" }, "rel_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rel Path" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "exif": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Exif" } }, "type": "object", "required": [ "name" ], "title": "ImageCreate" }, "ImageExifResponse": { "properties": { "exif": { "additionalProperties": true, "type": "object", "title": "Exif" } }, "type": "object", "title": "ImageExifResponse", "description": "EXIF metadata as a free-form dict. Empty when the source has\nno EXIF or when the bytes can't be located on the worker." }, "ImageObservationRow": { "properties": { "point3d_id": { "type": "integer", "title": "Point3D Id" }, "kp_idx": { "type": "integer", "title": "Kp Idx" }, "x": { "type": "number", "title": "X" }, "y": { "type": "number", "title": "Y" }, "error": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "point3d_id", "kp_idx", "x", "y" ], "title": "ImageObservationRow", "description": "One observation of a 3D point in one image, served from\n``observations_by_image.json``.\n\n``point3d_id`` is the COLMAP-assigned 3D point id; ``kp_idx`` is the\nindex into the image's keypoint list (matches ``ImagePose.points2D``);\n``x`` / ``y`` are the 2D pixel coordinates (origin = top-left,\nEXIF-oriented); ``error`` is the per-residual reprojection error in\npixels (``None`` when not produced by the worker)." }, "ImageObservationsResponse": { "properties": { "image_id": { "type": "string", "title": "Image Id" }, "observations": { "items": { "$ref": "#/components/schemas/ImageObservationRow" }, "type": "array", "title": "Observations" }, "count": { "type": "integer", "title": "Count", "default": 0 } }, "type": "object", "required": [ "image_id" ], "title": "ImageObservationsResponse", "description": "``GET .../images/{image_id}/observations`` envelope." }, "ImageOut": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "image_id": { "type": "string", "title": "Image Id" }, "dataset_id": { "type": "string", "title": "Dataset Id" }, "name": { "type": "string", "title": "Name" }, "content_sha": { "type": "string", "title": "Content Sha" }, "source_kind": { "type": "string", "title": "Source Kind" }, "rel_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rel Path" }, "byte_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Byte Size" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "type": "object", "required": [ "created_at", "image_id", "dataset_id", "name", "content_sha", "source_kind" ], "title": "ImageOut" }, "ImagePairRef": { "properties": { "image_name1": { "type": "string", "maxLength": 2048, "minLength": 1, "title": "Image Name1" }, "image_name2": { "type": "string", "maxLength": 2048, "minLength": 1, "title": "Image Name2" } }, "type": "object", "required": [ "image_name1", "image_name2" ], "title": "ImagePairRef", "description": "One explicit pair of dataset image names." }, "ImuMeasurement": { "properties": { "timestamp_ns": { "type": "integer", "title": "Timestamp Ns" }, "gyro": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 3, "minItems": 3, "title": "Gyro" }, "accel": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 3, "minItems": 3, "title": "Accel" } }, "type": "object", "required": [ "timestamp_ns", "gyro", "accel" ], "title": "ImuMeasurement", "description": "A single IMU sample.\n\nUsed for sequence/SLAM-leaning workflows where camera pose is\ncorrelated with an IMU stream. ``timestamp_ns`` is the nanosecond\ntimestamp on the IMU's clock; ``gyro`` is angular velocity\n(rad/s) and ``accel`` is linear acceleration (m/s\u00b2) in the IMU\nbody frame." }, "IncrementalSpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector when more than one registered provider can run the same portable mapping recipe." }, "seed": { "type": "integer", "title": "Seed", "default": 0 }, "max_runtime_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Runtime Seconds" }, "snapshot_frames_freq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Snapshot Frames Freq", "default": 50 }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific mapping options. Discover supported keys with GET /v1/backend/config-schemas and keep portable settings in the top-level spec fields." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references. Core roles include verified_matches, snapshot, and submodel; backend-specific roles may use the same dot-key syntax as artifact kinds." }, "kind": { "type": "string", "const": "incremental", "title": "Kind", "default": "incremental" }, "init_image_pair": { "anyOf": [ { "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array", "maxItems": 2, "minItems": 2 }, { "type": "null" } ], "title": "Init Image Pair" }, "multiple_models": { "type": "boolean", "title": "Multiple Models", "default": true }, "max_num_models": { "type": "integer", "title": "Max Num Models", "default": 50 }, "min_num_matches": { "type": "integer", "title": "Min Num Matches", "default": 15 }, "ba_global_use_pba": { "type": "boolean", "title": "Ba Global Use Pba", "default": true }, "extract_colors": { "type": "boolean", "title": "Extract Colors", "default": true } }, "type": "object", "title": "IncrementalSpec" }, "IssueKeyBody": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "tenant_id" ], "title": "IssueKeyBody" }, "IssueKeyResponse": { "properties": { "raw_key": { "type": "string", "title": "Raw Key" }, "api_key_id": { "type": "string", "title": "Api Key Id" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "raw_key", "api_key_id", "tenant_id", "name" ], "title": "IssueKeyResponse" }, "JobAcceptedResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "task_ids": { "items": { "type": "string" }, "type": "array", "title": "Task Ids" }, "recon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recon Id" }, "dataset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method" }, "applied_sim3": { "anyOf": [ { "$ref": "#/components/schemas/Sim3" }, { "type": "null" } ] }, "target_recon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Recon Id" }, "source_recon_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source Recon Ids" }, "strategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Strategy" }, "action_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Id" }, "backend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Backend" }, "artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Id" }, "target_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Format" } }, "type": "object", "required": [ "job_id" ], "title": "JobAcceptedResponse", "description": "Canonical 202 envelope for endpoints that submit a Job.\n\nReturned by every ``POST`` that enqueues SfM work\n(`/datasets/{id}/features`, `/matches`, `/verify`, the\n`/pipelines/{recipe}` recipes, and the localize / dense / mesh /\ncubemap stages). Clients should follow ``Location`` to ``GET\n/v1/jobs/{job_id}`` for status.\n\nStage-specific optional fields are typed here so SDK codegen can\nsurface them as named accessors:\n\n- ``recon_id`` \u2014 endpoints nested under a reconstruction\n- ``dataset_id`` / ``project_id`` \u2014 parent-pointer for top-level routes\n- ``method`` \u2014 mesh submission method\n- ``applied_sim3`` \u2014 georegister applied transform\n- ``target_recon_id`` / ``source_recon_ids`` \u2014 ``reconstructions:merge``\n- ``strategy`` \u2014 ``similarity:build``\n- ``action_id`` / ``backend`` \u2014 backend-native extension actions" }, "JobDetail": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "project_id": { "type": "string", "title": "Project Id" }, "recipe": { "type": "string", "title": "Recipe" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled", "cancelled_dirty" ], "title": "Status" }, "cancel_requested": { "type": "boolean", "title": "Cancel Requested" }, "cancel_force": { "type": "boolean", "title": "Cancel Force" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Class" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" }, "tasks": { "items": { "$ref": "#/components/schemas/TaskOut" }, "type": "array", "title": "Tasks", "default": [] } }, "type": "object", "required": [ "job_id", "tenant_id", "project_id", "recipe", "status", "cancel_requested", "cancel_force", "created_at" ], "title": "JobDetail", "description": "``GET /v1/jobs/{job_id}`` body \u2014 :class:`JobOut` plus the full\nconstituent task list. Use :class:`JobOut` (without ``tasks``) for\nlist endpoints; use :class:`JobDetail` for single-job reads." }, "JobOut": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "project_id": { "type": "string", "title": "Project Id" }, "recipe": { "type": "string", "title": "Recipe" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled", "cancelled_dirty" ], "title": "Status" }, "cancel_requested": { "type": "boolean", "title": "Cancel Requested" }, "cancel_force": { "type": "boolean", "title": "Cancel Force" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Class" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "type": "object", "required": [ "job_id", "tenant_id", "project_id", "recipe", "status", "cancel_requested", "cancel_force", "created_at" ], "title": "JobOut", "description": "Wire shape of a Job row.\n\nA Job is a long-running operation rolled up from N constituent\nTask rows (see :class:`TaskOut`). ``status`` reaches a terminal\nstate (see :data:`JobStatus`) once every Task is terminal; the\nrollup is driven by ``app/workers/dispatcher.py::_maybe_finalize_job``.\n``cancel_requested`` flips when ``POST /v1/jobs/{id}:cancel``\narrives; ``cancel_force`` flips when ``?force=true`` was passed.\n``error_class`` / ``error_message`` are populated only when the\njob ends in ``failed``." }, "JobProgressOut": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "recipe": { "type": "string", "title": "Recipe" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled", "cancelled_dirty" ], "title": "Status" }, "progress": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Progress" }, "total_tasks": { "type": "integer", "title": "Total Tasks" }, "completed_tasks": { "type": "integer", "title": "Completed Tasks" }, "task_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Task Counts" }, "current_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Task Id" }, "current_task_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Task Kind" }, "current_phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Phase" }, "latest_event_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latest Event Id" }, "latest_event": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Latest Event" }, "tasks": { "items": { "$ref": "#/components/schemas/TaskProgressOut" }, "type": "array", "title": "Tasks", "default": [] } }, "type": "object", "required": [ "job_id", "recipe", "status", "progress", "total_tasks", "completed_tasks", "task_counts" ], "title": "JobProgressOut", "description": "Compact polling snapshot for job progress.\n\nThis endpoint complements ``/events`` for dashboards and CLIs that\nprefer polling over holding an SSE connection open." }, "KaptureImportRequest": { "properties": { "archive_path": { "type": "string", "title": "Archive Path" } }, "type": "object", "required": [ "archive_path" ], "title": "KaptureImportRequest", "description": "``POST /v1/projects/{pid}/datasets:import_kapture``." }, "LicenseInfo": { "properties": { "name": { "type": "string", "title": "Name" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "LicenseInfo" }, "Link": { "properties": { "href": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Href" } }, "type": "object", "title": "Link" }, "LocalSourceSpec": { "properties": { "kind": { "type": "string", "const": "local", "title": "Kind", "default": "local" }, "root": { "type": "string", "title": "Root" }, "recursive": { "type": "boolean", "title": "Recursive", "default": true } }, "type": "object", "required": [ "root" ], "title": "LocalSourceSpec", "description": "Image source pointing at a worker-local directory tree. Bytes\nare NEVER copied \u2014 workers stream from ``root`` in place. Locked\nby ``L3`` in ``docs/guides/decisions.md`` (50GB local dirs)." }, "LocalizationRequest": { "properties": { "blob_sha": { "type": "string", "maxLength": 64, "minLength": 64, "title": "Blob Sha" }, "sift": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Sift" } }, "type": "object", "required": [ "blob_sha" ], "title": "LocalizationRequest", "description": "Request body for ``POST /v1/reconstructions/{rid}/localize``." }, "MatcherSpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "type": { "type": "string", "enum": [ "nn-mutual", "nn-ratio", "superglue", "lightglue", "loftr", "mast3r" ], "title": "Type", "default": "nn-mutual" }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector when more than one registered provider can run the same matcher type." }, "use_gpu": { "type": "boolean", "title": "Use Gpu", "default": true }, "cross_check": { "type": "boolean", "title": "Cross Check", "default": true }, "max_ratio": { "type": "number", "title": "Max Ratio", "default": 0.8 }, "max_distance": { "type": "number", "title": "Max Distance", "default": 0.7 }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific matcher options. Discover supported keys with GET /v1/backend/config-schemas." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references. Use role 'features' to select a feature artifact produced by another backend." } }, "type": "object", "title": "MatcherSpec", "description": "Per-pair feature matcher.\n\n``nn-mutual`` is the COLMAP default (mutual nearest-neighbor).\n``nn-ratio`` adds Lowe's ratio test. ``superglue`` / ``lightglue``\nare learned matchers. ``loftr`` is semi-dense (no separate\nextractor \u2014 set ``FeaturesSpec.type`` to a placeholder)." }, "MatchesRequest": { "properties": { "pairs": { "$ref": "#/components/schemas/PairsSpec", "default": { "version": 1, "strategy": "exhaustive", "overlap": 10, "retrieval_strategy": "vlad", "retrieval_k": 20, "pairs_blob_format": "image_name_pairs_txt", "backend_options": {}, "input_artifacts": {} } }, "matcher": { "$ref": "#/components/schemas/MatcherSpec", "default": { "version": 1, "type": "nn-mutual", "use_gpu": true, "cross_check": true, "max_ratio": 0.8, "max_distance": 0.7, "backend_options": {}, "input_artifacts": {} } }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts" } }, "additionalProperties": false, "type": "object", "title": "MatchesRequest", "description": "Match-stage request body \u2014 pair selection + per-pair matcher\nare independent shapes (AIP-202: one concept per type)." }, "MergeRequest": { "properties": { "target_recon_id": { "type": "string", "title": "Target Recon Id" }, "source_recon_ids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Source Recon Ids" }, "sim3_aligners": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Sim3 Aligners" } }, "type": "object", "required": [ "target_recon_id", "source_recon_ids" ], "title": "MergeRequest", "description": "Request body for ``POST /v1/reconstructions:merge``." }, "OneShotFeaturesPayload": { "properties": { "type": { "type": "string", "title": "Type" }, "count": { "type": "integer", "title": "Count" }, "descriptor_dim": { "type": "integer", "title": "Descriptor Dim" }, "keypoints": { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array", "title": "Keypoints" }, "descriptors_b64": { "type": "string", "title": "Descriptors B64", "default": "" } }, "type": "object", "required": [ "type", "count", "descriptor_dim" ], "title": "OneShotFeaturesPayload", "description": "The features themselves. ``keypoints`` is row-major\n``[[x, y, scale, angle], ...]``; ``descriptors_b64`` is\nbase64-encoded float32 descriptors of shape\n``(count, descriptor_dim)`` in row-major order. ``descriptor_dim``\nis implied by the extractor (128 for SIFT)." }, "OneShotFeaturesResponse": { "properties": { "schema_version": { "type": "integer", "const": 1, "title": "Schema Version", "default": 1 }, "kind": { "type": "string", "const": "oneshot.features", "title": "Kind", "default": "oneshot.features" }, "image": { "$ref": "#/components/schemas/OneShotImageInfo" }, "features": { "$ref": "#/components/schemas/OneShotFeaturesPayload" }, "runtime": { "$ref": "#/components/schemas/OneShotRuntimeInfo" }, "spec": { "additionalProperties": true, "type": "object", "title": "Spec" } }, "additionalProperties": false, "type": "object", "required": [ "image", "features", "runtime" ], "title": "OneShotFeaturesResponse", "description": "``POST /v1/oneshot/features`` envelope. No persistence \u2014\neverything the consumer needs is in this body. ``schema_version``\nversions the wire shape; bump on incompatible changes." }, "OneShotImageInfo": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "byte_size": { "type": "integer", "title": "Byte Size" } }, "type": "object", "required": [ "width", "height", "byte_size" ], "title": "OneShotImageInfo", "description": "Header-derived image metadata echoed back for caller sanity checks.\n\n``width`` and ``height`` are ``None`` when the server cannot read the\ndimensions cheaply from image headers. sfmapi does not decode pixels in\nthe API layer." }, "OneShotLocalizeResponse": { "properties": { "schema_version": { "type": "integer", "const": 1, "title": "Schema Version", "default": 1 }, "kind": { "type": "string", "const": "oneshot.localize", "title": "Kind", "default": "oneshot.localize" }, "recon_id": { "type": "string", "title": "Recon Id" }, "image": { "$ref": "#/components/schemas/OneShotImageInfo" }, "result": { "additionalProperties": true, "type": "object", "title": "Result" }, "runtime": { "$ref": "#/components/schemas/OneShotRuntimeInfo" }, "spec": { "additionalProperties": true, "type": "object", "title": "Spec" } }, "additionalProperties": false, "type": "object", "required": [ "recon_id", "image", "result", "runtime" ], "title": "OneShotLocalizeResponse", "description": "``POST /v1/oneshot/localize`` envelope. Single-frame pose\nagainst an existing reconstruction with no DB row, no Job row,\nno upload step. The ``result`` field re-uses the existing\n:class:`~app.schemas.api.scene.LocalizationResult` shape verbatim\nso SDK consumers can re-decode through the typed model." }, "OneShotRuntimeInfo": { "properties": { "backend": { "type": "string", "title": "Backend" }, "ms": { "type": "integer", "title": "Ms" } }, "type": "object", "required": [ "backend", "ms" ], "title": "OneShotRuntimeInfo" }, "Page_ArtifactFormatOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ArtifactFormatOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[ArtifactFormatOut]" }, "Page_ArtifactKindOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ArtifactKindOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[ArtifactKindOut]" }, "Page_BackendActionOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BackendActionOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[BackendActionOut]" }, "Page_BackendArtifactContractOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BackendArtifactContractOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[BackendArtifactContractOut]" }, "Page_BackendConfigSchemaOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BackendConfigSchemaOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[BackendConfigSchemaOut]" }, "Page_CameraModelOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CameraModelOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[CameraModelOut]" }, "Page_DatasetOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DatasetOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[DatasetOut]" }, "Page_ImageOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ImageOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[ImageOut]" }, "Page_JobOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/JobOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[JobOut]" }, "Page_PluginEntryPointOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PluginEntryPointOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[PluginEntryPointOut]" }, "Page_PluginRegistryItemOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PluginRegistryItemOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[PluginRegistryItemOut]" }, "Page_ProjectOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProjectOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[ProjectOut]" }, "Page_ProviderOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProviderOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[ProviderOut]" }, "Page_StageArtifactOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/StageArtifactOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[StageArtifactOut]" }, "Page_SubModelOut_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SubModelOut" }, "type": "array", "title": "Items" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "items" ], "title": "Page[SubModelOut]" }, "PairsSpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "strategy": { "type": "string", "enum": [ "exhaustive", "sequential", "spatial", "vocabtree", "retrieval", "from_poses", "explicit" ], "title": "Strategy", "default": "exhaustive" }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector for this pair-selection stage. Use only to disambiguate providers that expose the same portable pair capability." }, "overlap": { "type": "integer", "title": "Overlap", "default": 10 }, "vocab_tree_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vocab Tree Path" }, "retrieval_strategy": { "type": "string", "enum": [ "dhash", "vlad", "netvlad" ], "title": "Retrieval Strategy", "default": "vlad" }, "retrieval_k": { "type": "integer", "title": "Retrieval K", "default": 20 }, "overlap_distance_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Overlap Distance M" }, "max_angle_deg": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Angle Deg" }, "image_pairs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ImagePairRef" }, "type": "array" }, { "type": "null" } ], "title": "Image Pairs", "description": "Inline image-name pairs for strategy='explicit'. Intended for small lists; upload large hloc/COLMAP pair files and pass pairs_blob_sha instead." }, "pairs_blob_sha": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "title": "Pairs Blob Sha", "description": "Sha256 of a finalized upload containing newline-delimited image name pairs, one 'image1 image2' pair per line. Only valid with strategy='explicit'." }, "pairs_blob_format": { "type": "string", "const": "image_name_pairs_txt", "title": "Pairs Blob Format", "default": "image_name_pairs_txt" }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific pair-selection options. Discover supported keys with GET /v1/backend/config-schemas." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references. Use role 'pairs' for a previously generated pair-selection artifact." } }, "type": "object", "title": "PairsSpec", "description": "Pair-selection strategy. Decoupled from the matcher so the\nstandard supports \"select pairs with hloc-style retrieval, then\nmatch with any local-feature matcher\" workflows.\n\nCapability flag is ``pairs.{strategy}``." }, "PerspectiveProjectionRequest": { "properties": { "operation": { "type": "string", "const": "equirectangular_to_perspective", "title": "Operation", "default": "equirectangular_to_perspective" }, "cubemap": { "anyOf": [ { "$ref": "#/components/schemas/CubemapProjectionSpec" }, { "type": "null" } ] }, "equirectangular": { "anyOf": [ { "$ref": "#/components/schemas/EquirectangularProjectionSpec" }, { "type": "null" } ] }, "perspective": { "anyOf": [ { "$ref": "#/components/schemas/PerspectiveProjectionSpec" }, { "type": "null" } ] } }, "type": "object", "title": "PerspectiveProjectionRequest" }, "PerspectiveProjectionSpec": { "properties": { "convention": { "type": "string", "const": "sfmapi-opencv", "title": "Convention", "default": "sfmapi-opencv" }, "views": { "items": { "$ref": "#/components/schemas/PerspectiveViewSpec" }, "type": "array", "maxItems": 1024, "minItems": 1, "title": "Views" }, "sampling": { "$ref": "#/components/schemas/ProjectionSampling" }, "output": { "$ref": "#/components/schemas/ProjectionOutputOptions" } }, "type": "object", "title": "PerspectiveProjectionSpec", "description": "Equirectangular panorama to one or more perspective images." }, "PerspectiveViewSpec": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "yaw_deg": { "type": "number", "maximum": 360.0, "minimum": -360.0, "title": "Yaw Deg", "default": 0.0 }, "pitch_deg": { "type": "number", "maximum": 90.0, "minimum": -90.0, "title": "Pitch Deg", "default": 0.0 }, "roll_deg": { "type": "number", "maximum": 180.0, "minimum": -180.0, "title": "Roll Deg", "default": 0.0 }, "hfov_deg": { "type": "number", "maximum": 179.0, "exclusiveMinimum": 0.0, "title": "Hfov Deg", "default": 90.0 }, "width": { "type": "integer", "maximum": 16384.0, "minimum": 16.0, "title": "Width", "default": 1024 }, "height": { "type": "integer", "maximum": 16384.0, "minimum": 16.0, "title": "Height", "default": 1024 } }, "type": "object", "title": "PerspectiveViewSpec", "description": "One pinhole view sampled from an equirectangular panorama." }, "PipelineRequest": { "properties": { "dataset_id": { "type": "string", "title": "Dataset Id" }, "features": { "$ref": "#/components/schemas/FeaturesSpec", "default": { "version": 1, "type": "sift", "max_num_features": 8192, "use_gpu": true, "seed": 0, "backend_options": {}, "input_artifacts": {} } }, "pairs": { "$ref": "#/components/schemas/PairsSpec", "default": { "version": 1, "strategy": "exhaustive", "overlap": 10, "retrieval_strategy": "vlad", "retrieval_k": 20, "pairs_blob_format": "image_name_pairs_txt", "backend_options": {}, "input_artifacts": {} } }, "matcher": { "$ref": "#/components/schemas/MatcherSpec", "default": { "version": 1, "type": "nn-mutual", "use_gpu": true, "cross_check": true, "max_ratio": 0.8, "max_distance": 0.7, "backend_options": {}, "input_artifacts": {} } }, "verify": { "$ref": "#/components/schemas/VerifySpec", "default": { "version": 1, "use_gpu": true, "min_inlier_ratio": 0.25, "backend_options": {}, "input_artifacts": {} } }, "spec": { "oneOf": [ { "$ref": "#/components/schemas/IncrementalSpec" }, { "$ref": "#/components/schemas/GlobalSpec" }, { "$ref": "#/components/schemas/HierarchicalSpec" }, { "$ref": "#/components/schemas/SphericalSpec" } ], "title": "Spec", "discriminator": { "propertyName": "kind", "mapping": { "global": "#/components/schemas/GlobalSpec", "hierarchical": "#/components/schemas/HierarchicalSpec", "incremental": "#/components/schemas/IncrementalSpec", "spherical": "#/components/schemas/SphericalSpec" } } }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed artifact references shared by the recipe. Stage-local input_artifacts on features, pairs, matcher, verify, or spec are merged with this map." } }, "type": "object", "required": [ "dataset_id", "spec" ], "title": "PipelineRequest", "description": "End-to-end pipeline request \u2014 features + pair selection +\nmatcher + two-view verification + mapping spec, sent in one body\nfor the recipe routes (``/pipelines/{incremental|global|...}``).\n\nPair selection (``pairs``) and per-pair matching (``matcher``) are\nindependent shapes (AIP-202)." }, "PluginDetailOut": { "properties": { "manifest": { "$ref": "#/components/schemas/PluginManifest" }, "installed": { "type": "boolean", "title": "Installed", "default": false }, "enabled": { "type": "boolean", "title": "Enabled", "default": false }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "manifest" ], "title": "PluginDetailOut" }, "PluginDoctorOut": { "properties": { "plugin_id": { "type": "string", "title": "Plugin Id" }, "status": { "type": "string", "enum": [ "pass", "warn", "fail" ], "title": "Status" }, "checks": { "items": { "$ref": "#/components/schemas/DoctorCheck" }, "type": "array", "title": "Checks" } }, "additionalProperties": false, "type": "object", "required": [ "plugin_id", "status" ], "title": "PluginDoctorOut" }, "PluginEntryPointOut": { "properties": { "plugin_id": { "type": "string", "title": "Plugin Id" }, "entry_point": { "type": "string", "title": "Entry Point" }, "distribution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Distribution" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" }, "manifest": { "anyOf": [ { "$ref": "#/components/schemas/PluginManifest" }, { "type": "null" } ] }, "load_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Load Error" } }, "additionalProperties": false, "type": "object", "required": [ "plugin_id", "entry_point" ], "title": "PluginEntryPointOut" }, "PluginInstallRequest": { "properties": { "method": { "type": "string", "enum": [ "uv", "docker", "external_tool" ], "title": "Method", "default": "uv" }, "github_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Github Url" }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ref" }, "package_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Package Name" }, "dry_run": { "type": "boolean", "title": "Dry Run", "default": true }, "allow_unsafe_execution": { "type": "boolean", "title": "Allow Unsafe Execution", "default": false } }, "additionalProperties": false, "type": "object", "title": "PluginInstallRequest" }, "PluginInstallResponse": { "properties": { "plugin_id": { "type": "string", "title": "Plugin Id" }, "method": { "type": "string", "enum": [ "uv", "docker", "external_tool" ], "title": "Method" }, "dry_run": { "type": "boolean", "title": "Dry Run" }, "installed": { "type": "boolean", "title": "Installed" }, "command": { "items": { "type": "string" }, "type": "array", "title": "Command" }, "direct_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Direct Reference" }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings" }, "resolved_commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolved Commit" } }, "additionalProperties": false, "type": "object", "required": [ "plugin_id", "method", "dry_run", "installed" ], "title": "PluginInstallResponse" }, "PluginManifest": { "properties": { "plugin_id": { "type": "string", "title": "Plugin Id" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "type": "string", "title": "Description" }, "package_name": { "type": "string", "title": "Package Name" }, "github_url": { "type": "string", "title": "Github Url" }, "entry_points": { "items": { "type": "string" }, "type": "array", "title": "Entry Points" }, "providers": { "items": { "$ref": "#/components/schemas/ProviderManifest" }, "type": "array", "title": "Providers" }, "runtime_modes": { "$ref": "#/components/schemas/RuntimeModes" }, "capabilities": { "items": { "type": "string" }, "type": "array", "title": "Capabilities" }, "backend_actions": { "items": { "type": "string" }, "type": "array", "title": "Backend Actions" }, "config_schemas": { "items": { "type": "string" }, "type": "array", "title": "Config Schemas" }, "artifact_contracts": { "items": { "type": "string" }, "type": "array", "title": "Artifact Contracts" }, "licenses": { "items": { "$ref": "#/components/schemas/LicenseInfo" }, "type": "array", "title": "Licenses" }, "upstream_projects": { "items": { "$ref": "#/components/schemas/UpstreamProject" }, "type": "array", "title": "Upstream Projects" }, "compatibility": { "$ref": "#/components/schemas/Compatibility" }, "conformance": { "$ref": "#/components/schemas/Conformance" }, "trust_tier": { "type": "string", "enum": [ "official", "verified", "community", "local" ], "title": "Trust Tier", "default": "community" } }, "additionalProperties": false, "type": "object", "required": [ "plugin_id", "display_name", "description", "package_name", "github_url", "entry_points", "providers", "runtime_modes" ], "title": "PluginManifest" }, "PluginRegistryItemOut": { "properties": { "plugin_id": { "type": "string", "title": "Plugin Id" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "type": "string", "title": "Description" }, "package_name": { "type": "string", "title": "Package Name" }, "github_url": { "type": "string", "title": "Github Url" }, "trust_tier": { "type": "string", "title": "Trust Tier" }, "runtime_modes": { "items": { "type": "string" }, "type": "array", "title": "Runtime Modes" }, "providers": { "items": { "type": "string" }, "type": "array", "title": "Providers" }, "installed": { "type": "boolean", "title": "Installed", "default": false }, "enabled": { "type": "boolean", "title": "Enabled", "default": false }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "plugin_id", "display_name", "description", "package_name", "github_url", "trust_tier", "runtime_modes", "providers" ], "title": "PluginRegistryItemOut" }, "PointObservationRow": { "properties": { "image_id": { "type": "integer", "title": "Image Id" }, "kp_idx": { "type": "integer", "title": "Kp Idx" }, "x": { "type": "number", "title": "X" }, "y": { "type": "number", "title": "Y" }, "error": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "image_id", "kp_idx", "x", "y" ], "title": "PointObservationRow", "description": "One observation of a 3D point from one image, served from\n``observations_by_point.json``.\n\nMirror of :class:`ImageObservationRow` keyed on ``image_id``\ninstead of ``point3d_id`` (different join order)." }, "PointVisibilityResponse": { "properties": { "point3d_id": { "type": "string", "title": "Point3D Id" }, "observations": { "items": { "$ref": "#/components/schemas/PointObservationRow" }, "type": "array", "title": "Observations" }, "count": { "type": "integer", "title": "Count", "default": 0 } }, "type": "object", "required": [ "point3d_id" ], "title": "PointVisibilityResponse", "description": "``GET .../points/{point3d_id}/visibility`` envelope." }, "PosePrior": { "properties": { "cam_from_world": { "$ref": "#/components/schemas/Rigid3" }, "covariance": { "anyOf": [ { "items": { "type": "number" }, "type": "array", "maxItems": 36, "minItems": 36 }, { "type": "null" } ], "title": "Covariance" }, "gps": { "anyOf": [ { "$ref": "#/components/schemas/GpsCoord" }, { "type": "null" } ] }, "timestamp_ns": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Timestamp Ns" }, "imu": { "anyOf": [ { "$ref": "#/components/schemas/ImuMeasurement" }, { "type": "null" } ] } }, "type": "object", "required": [ "cam_from_world" ], "title": "PosePrior", "description": "Prior on a camera's ``cam_from_world`` pose.\n\n``covariance`` is a 36-float row-major 6x6 matrix (rx, ry, rz, tx,\nty, tz). Diagonal-only priors send only the six diagonal entries\ninside the 36-vector with off-diagonals zero. ``timestamp_ns`` is\nthe optional nanosecond timestamp the prior corresponds to \u2014\nneeded when the same image appears at multiple times in a\nsequence (rolling shutter, video). ``imu`` is an optional IMU\nsample colocated with the pose prior." }, "PosePriorsBulkResponse": { "properties": { "pose_priors": { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/PosePrior" }, { "type": "null" } ] }, "type": "object", "title": "Pose Priors" } }, "type": "object", "title": "PosePriorsBulkResponse", "description": "Per-image PosePrior map for ``GET /v1/datasets/{id}/pose_priors``." }, "PosePriorsBulkWriteResponse": { "properties": { "written": { "type": "integer", "title": "Written" } }, "type": "object", "required": [ "written" ], "title": "PosePriorsBulkWriteResponse", "description": "Outcome envelope for ``PUT /v1/datasets/{id}/pose_priors``." }, "ProjectCreate": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "name" ], "title": "ProjectCreate" }, "ProjectOut": { "properties": { "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "project_id": { "type": "string", "title": "Project Id" }, "tenant_id": { "type": "string", "title": "Tenant Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "type": "object", "required": [ "created_at", "project_id", "tenant_id", "name" ], "title": "ProjectOut" }, "ProjectPatch": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Description" } }, "type": "object", "title": "ProjectPatch", "description": "Partial update. Unset fields are left untouched." }, "ProjectionJobRequest": { "properties": { "operation": { "type": "string", "enum": [ "equirectangular_to_cubemap", "cubemap_to_equirectangular", "equirectangular_to_perspective" ], "title": "Operation", "default": "equirectangular_to_cubemap" }, "cubemap": { "anyOf": [ { "$ref": "#/components/schemas/CubemapProjectionSpec" }, { "type": "null" } ] }, "equirectangular": { "anyOf": [ { "$ref": "#/components/schemas/EquirectangularProjectionSpec" }, { "type": "null" } ] }, "perspective": { "anyOf": [ { "$ref": "#/components/schemas/PerspectiveProjectionSpec" }, { "type": "null" } ] } }, "type": "object", "title": "ProjectionJobRequest", "description": "Dataset-level projection job request.\n\nOnly the spec matching ``operation`` is used. Missing matching specs\nare filled with their portable defaults." }, "ProjectionOutputOptions": { "properties": { "format": { "type": "string", "enum": [ "source", "jpg", "png", "webp" ], "title": "Format", "default": "source" }, "jpeg_quality": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Jpeg Quality", "default": 92 }, "write_manifest": { "type": "boolean", "title": "Write Manifest", "default": true }, "create_dataset": { "type": "boolean", "title": "Create Dataset", "default": true }, "dataset_name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Dataset Name" } }, "type": "object", "title": "ProjectionOutputOptions", "description": "Portable output controls shared by projection jobs." }, "ProjectionSampling": { "properties": { "interpolation": { "type": "string", "enum": [ "nearest", "linear", "cubic", "lanczos" ], "title": "Interpolation", "default": "linear" }, "antialias": { "type": "boolean", "title": "Antialias", "default": true }, "seam_padding_px": { "type": "integer", "maximum": 256.0, "minimum": 0.0, "title": "Seam Padding Px", "default": 0 }, "overlap_px": { "type": "integer", "maximum": 1024.0, "minimum": 0.0, "title": "Overlap Px", "default": 0 } }, "type": "object", "title": "ProjectionSampling", "description": "Portable sampling controls for image projection jobs." }, "ProviderManifest": { "properties": { "provider_id": { "type": "string", "title": "Provider Id" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "capabilities": { "items": { "type": "string" }, "type": "array", "title": "Capabilities" }, "backend_actions": { "items": { "type": "string" }, "type": "array", "title": "Backend Actions" }, "priority_hint": { "type": "integer", "title": "Priority Hint", "default": 100 } }, "additionalProperties": false, "type": "object", "required": [ "provider_id", "display_name" ], "title": "ProviderManifest" }, "ProviderOut": { "properties": { "provider_id": { "type": "string", "title": "Provider Id" }, "plugin_id": { "type": "string", "title": "Plugin Id" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "capabilities": { "items": { "type": "string" }, "type": "array", "title": "Capabilities" }, "backend_actions": { "items": { "type": "string" }, "type": "array", "title": "Backend Actions" }, "runtime_modes": { "items": { "type": "string" }, "type": "array", "title": "Runtime Modes" }, "installed": { "type": "boolean", "title": "Installed", "default": true }, "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "provider_id", "plugin_id", "display_name" ], "title": "ProviderOut" }, "ReadyzResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "checks": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Checks" } }, "type": "object", "required": [ "status" ], "title": "ReadyzResponse", "description": "Readiness check envelope. ``status`` is ``\"ok\"`` when every\nbacking store reports healthy; ``\"degraded\"`` when one or more\nare unreachable. ``checks`` carries a per-component status string." }, "ReconstructionOut": { "properties": { "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" }, "recon_id": { "type": "string", "title": "Recon Id" }, "project_id": { "type": "string", "title": "Project Id" }, "dataset_id": { "type": "string", "title": "Dataset Id" }, "dataset_snapshot_hash": { "type": "string", "title": "Dataset Snapshot Hash" }, "spec": { "oneOf": [ { "$ref": "#/components/schemas/IncrementalSpec" }, { "$ref": "#/components/schemas/GlobalSpec" }, { "$ref": "#/components/schemas/HierarchicalSpec" }, { "$ref": "#/components/schemas/SphericalSpec" } ], "title": "Spec", "discriminator": { "propertyName": "kind", "mapping": { "global": "#/components/schemas/GlobalSpec", "hierarchical": "#/components/schemas/HierarchicalSpec", "incremental": "#/components/schemas/IncrementalSpec", "spherical": "#/components/schemas/SphericalSpec" } } }, "rv_id": { "type": "string", "title": "Rv Id" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "cancelled", "cancelled_dirty" ], "title": "Status" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "recon_id", "project_id", "dataset_id", "dataset_snapshot_hash", "spec", "rv_id", "status", "created_at" ], "title": "ReconstructionOut", "description": "Wire shape of a Reconstruction row.\n\nA Reconstruction is a single mapping run against a dataset. It\nproduces N :class:`SubModelOut` rows (one per disconnected\ncomponent COLMAP discovers). The reconstruction itself is\nmetadata; the actual outputs live as sealed snapshots reachable\nvia ``links['snapshots']``. ``rv_id`` is the runtime-version\nfingerprint that gates cache lookup; ``dataset_snapshot_hash``\npins the input image set for reproducibility." }, "Rigid3": { "properties": { "rotation": { "$ref": "#/components/schemas/Rotation" }, "translation": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 3, "minItems": 3, "title": "Translation" } }, "type": "object", "required": [ "rotation", "translation" ], "title": "Rigid3", "description": "Rigid SE(3) transform: ``y = R @ x + t``." }, "Rotation": { "properties": { "w": { "type": "number", "title": "W" }, "x": { "type": "number", "title": "X" }, "y": { "type": "number", "title": "Y" }, "z": { "type": "number", "title": "Z" } }, "type": "object", "required": [ "w", "x", "y", "z" ], "title": "Rotation", "description": "Hamilton quaternion stored ``(w, x, y, z)``." }, "RoutingOut": { "properties": { "default_profile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Profile" }, "provider_priority": { "items": { "type": "string" }, "type": "array", "title": "Provider Priority" }, "profiles": { "additionalProperties": { "$ref": "#/components/schemas/RoutingProfile" }, "type": "object", "title": "Profiles" }, "project_profiles": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Project Profiles" }, "workspace_profiles": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Workspace Profiles" } }, "additionalProperties": false, "type": "object", "title": "RoutingOut" }, "RoutingProfile": { "properties": { "name": { "type": "string", "title": "Name" }, "routes": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object", "title": "Routes" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "RoutingProfile" }, "RoutingProfileAssignmentRequest": { "properties": { "profile": { "type": "string", "title": "Profile" } }, "additionalProperties": false, "type": "object", "required": [ "profile" ], "title": "RoutingProfileAssignmentRequest" }, "RoutingProfileRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "routes": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object", "title": "Routes" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "RoutingProfileRequest" }, "RuntimeModes": { "properties": { "uv": { "anyOf": [ { "$ref": "#/components/schemas/UvRuntime" }, { "type": "null" } ] }, "docker": { "anyOf": [ { "$ref": "#/components/schemas/DockerRuntime" }, { "type": "null" } ] }, "external_tool": { "anyOf": [ { "$ref": "#/components/schemas/ExternalToolRuntime" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "title": "RuntimeModes" }, "S3SourceSpec": { "properties": { "kind": { "type": "string", "const": "s3", "title": "Kind", "default": "s3" }, "bucket": { "type": "string", "title": "Bucket" }, "prefix": { "type": "string", "title": "Prefix" } }, "type": "object", "required": [ "bucket", "prefix" ], "title": "S3SourceSpec", "description": "Image source backed by an S3 prefix. Bytes are lazy-downloaded\nto the worker's LRU cache on first read; remote-only by default." }, "Sim3": { "properties": { "rotation": { "$ref": "#/components/schemas/Rotation" }, "translation": { "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "type": "array", "maxItems": 3, "minItems": 3, "title": "Translation" }, "scale": { "type": "number", "title": "Scale" } }, "type": "object", "required": [ "rotation", "translation", "scale" ], "title": "Sim3", "description": "Similarity Sim(3) transform: ``y = s * R @ x + t``." }, "SimilarityBuildResponse": { "properties": { "strategy": { "type": "string", "title": "Strategy" }, "manifest_hash": { "type": "string", "title": "Manifest Hash" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "strategy", "manifest_hash", "count" ], "title": "SimilarityBuildResponse", "description": "``POST /v1/datasets/{id}/similarity:build`` synchronous build\nresponse (dhash). Async vlad path returns :class:`JobAcceptedResponse`." }, "SimilarityNeighborOut": { "properties": { "image_id": { "type": "string", "title": "Image Id" }, "distance": { "type": "integer", "title": "Distance" } }, "type": "object", "required": [ "image_id", "distance" ], "title": "SimilarityNeighborOut" }, "SimilarityQueryResponse": { "properties": { "query_image_id": { "type": "string", "title": "Query Image Id" }, "strategy": { "type": "string", "title": "Strategy" }, "k": { "type": "integer", "title": "K" }, "neighbors": { "items": { "$ref": "#/components/schemas/SimilarityNeighborOut" }, "type": "array", "title": "Neighbors" } }, "type": "object", "required": [ "query_image_id", "strategy", "k" ], "title": "SimilarityQueryResponse", "description": "``GET /v1/datasets/{id}/similarity?image_id=...`` envelope." }, "SnapshotListResponse": { "properties": { "seqs": { "items": { "type": "integer" }, "type": "array", "title": "Seqs" }, "_links": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Links" } }, "type": "object", "title": "SnapshotListResponse", "description": "``GET /v1/reconstructions/{recon_id}/snapshots`` envelope." }, "SpecResponse": { "properties": { "spec": { "type": "string", "title": "Spec" }, "spec_version": { "type": "string", "title": "Spec Version" }, "spec_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Spec Url", "default": "https://sfmapi.github.io/spec" }, "openapi_url": { "type": "string", "title": "Openapi Url" }, "server": { "$ref": "#/components/schemas/SpecServerInfo" } }, "type": "object", "required": [ "spec", "spec_version", "openapi_url", "server" ], "title": "SpecResponse", "description": "Discovery envelope for ``GET /spec``. Identifies which standard\nthis server implements so clients can pick a compatible SDK.\n\n``spec_url`` defaults to the canonical GitHub Pages doc site;\ndeployments may override via ``SFMAPI_SPEC_URL`` to point at a\nprivate mirror, or set it ``None`` to omit the field entirely." }, "SpecServerInfo": { "properties": { "name": { "type": "string", "title": "Name" }, "version": { "type": "string", "title": "Version" } }, "type": "object", "required": [ "name", "version" ], "title": "SpecServerInfo" }, "SphericalSpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector when more than one registered provider can run the same portable mapping recipe." }, "seed": { "type": "integer", "title": "Seed", "default": 0 }, "max_runtime_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Runtime Seconds" }, "snapshot_frames_freq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Snapshot Frames Freq", "default": 50 }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific mapping options. Discover supported keys with GET /v1/backend/config-schemas and keep portable settings in the top-level spec fields." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references. Core roles include verified_matches, snapshot, and submodel; backend-specific roles may use the same dot-key syntax as artifact kinds." }, "kind": { "type": "string", "const": "spherical", "title": "Kind", "default": "spherical" }, "panorama": { "type": "boolean", "title": "Panorama", "default": true } }, "type": "object", "title": "SphericalSpec" }, "StageArtifactOut": { "properties": { "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" }, "artifact_id": { "type": "string", "title": "Artifact Id" }, "job_id": { "type": "string", "title": "Job Id" }, "task_id": { "type": "string", "title": "Task Id" }, "recon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recon Id" }, "dataset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Id" }, "kind": { "type": "string", "title": "Kind" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Uri" }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Type" }, "artifact_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Format" }, "artifact_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Type" }, "schema_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Schema Version" }, "files": { "items": { "$ref": "#/components/schemas/ArtifactFileRef" }, "type": "array", "title": "Files" }, "sha256": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 64 }, { "type": "null" } ], "title": "Sha256" }, "byte_size": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Byte Size" }, "coordinate_frame": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Coordinate Frame" }, "producer": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Producer" }, "summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Summary" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "artifact_id", "job_id", "task_id", "kind", "created_at" ], "title": "StageArtifactOut", "description": "A typed worker output persisted independently of task logs.\n\nUnknown backends can emit multiple artifacts per stage. The API\nstores them here so clients can list and select exact outputs\ninstead of guessing from the latest task dictionary." }, "SubModelOut": { "properties": { "_links": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Links" }, "submodel_id": { "type": "string", "title": "Submodel Id" }, "recon_id": { "type": "string", "title": "Recon Id" }, "idx": { "type": "integer", "title": "Idx" }, "parent_submodel_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Submodel Id" }, "summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Summary" }, "rigidity": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Rigidity" }, "snapshot_seq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Snapshot Seq" }, "sealed_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sealed Path" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "submodel_id", "recon_id", "idx", "created_at" ], "title": "SubModelOut", "description": "Wire shape of a SubModel row.\n\nA SubModel is one disconnected component within a Reconstruction\n(``sparse/0``, ``sparse/1``, ...). ``idx`` is the COLMAP-assigned\ncomponent index; ``parent_submodel_id`` points at the source when\nthe model came out of a hierarchical merge / split. ``summary``\ncarries per-component stats (image count, point count, mean\nreprojection error) so collection endpoints don't need to crack\nthe snapshot. ``snapshot_seq`` / ``sealed_path`` point at the\non-disk sealed snapshot; clients read points / cameras / images\nfrom there." }, "TaskOut": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "job_id": { "type": "string", "title": "Job Id" }, "kind": { "type": "string", "title": "Kind" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled", "cancelled_dirty", "skipped" ], "title": "Status" }, "cache_key": { "type": "string", "title": "Cache Key" }, "inputs_hash": { "type": "string", "title": "Inputs Hash" }, "params_hash": { "type": "string", "title": "Params Hash" }, "outputs_ref": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Outputs Ref" } }, "type": "object", "required": [ "task_id", "job_id", "kind", "status", "cache_key", "inputs_hash", "params_hash" ], "title": "TaskOut", "description": "Wire shape of a Task row inside a Job.\n\nEach Task = one ARQ job (see ``L5`` in ``decisions.md``). ``kind``\nis the worker handler name (``extract`` | ``match`` | ``map`` |\n...). ``cache_key`` is the content-addressed lookup key; tasks\nthat hit cache transition straight to ``skipped``. ``outputs_ref``\ncarries the typed result payload \u2014 clients read this once\n``status`` is terminal (the localize / oneshot result lives here,\nfor instance)." }, "TaskProgressOut": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "kind": { "type": "string", "title": "Kind" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled", "cancelled_dirty", "skipped" ], "title": "Status" }, "progress": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Progress" }, "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phase" }, "current": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "latest_event_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latest Event Id" }, "latest_event_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Event Kind" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "elapsed_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Elapsed Seconds" } }, "type": "object", "required": [ "task_id", "kind", "status", "progress" ], "title": "TaskProgressOut", "description": "Per-task progress snapshot for polling clients.\n\n``progress`` is a best-effort fraction in ``[0, 1]``. It is ``1``\nfor terminal tasks, event-derived for running tasks when the\nlatest ``phase_progress`` event carries ``current`` / ``total``,\nand ``0`` otherwise." }, "ToolDetection": { "properties": { "name": { "type": "string", "title": "Name" }, "source": { "type": "string", "enum": [ "env", "path" ], "title": "Source" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Path" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "additionalProperties": false, "type": "object", "required": [ "name", "source" ], "title": "ToolDetection" }, "ToolDetectionOut": { "properties": { "tools": { "additionalProperties": { "items": { "$ref": "#/components/schemas/ToolDetection" }, "type": "array" }, "type": "object", "title": "Tools" } }, "additionalProperties": false, "type": "object", "required": [ "tools" ], "title": "ToolDetectionOut" }, "UploadEntrySpec": { "properties": { "name": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Name" }, "blob_sha": { "type": "string", "maxLength": 64, "minLength": 64, "title": "Blob Sha" } }, "type": "object", "required": [ "name", "blob_sha" ], "title": "UploadEntrySpec", "description": "One image entry in an :class:`UploadSourceSpec`. Each entry binds\na human-readable filename to a previously-finalized upload's\ncanonical content-addressed sha (returned by ``POST\n/v1/uploads/{id}:finalize``)." }, "UploadInit": { "properties": { "expected_size": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Expected Size" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type" }, "expected_sha": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 64 }, { "type": "null" } ], "title": "Expected Sha" } }, "type": "object", "required": [ "expected_size" ], "title": "UploadInit" }, "UploadOut": { "properties": { "upload_id": { "type": "string", "title": "Upload Id" }, "state": { "type": "string", "enum": [ "open", "received", "finalized", "expired" ], "title": "State" }, "expected_size": { "type": "integer", "title": "Expected Size" }, "received_bytes": { "type": "integer", "title": "Received Bytes" }, "blob_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Blob Sha" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" } }, "type": "object", "required": [ "upload_id", "state", "expected_size", "received_bytes", "expires_at" ], "title": "UploadOut" }, "UploadSourceSpec": { "properties": { "kind": { "type": "string", "const": "upload", "title": "Kind", "default": "upload" }, "entries": { "items": { "$ref": "#/components/schemas/UploadEntrySpec" }, "type": "array", "title": "Entries" } }, "type": "object", "title": "UploadSourceSpec", "description": "Image source backed by previously-uploaded blobs (sfmapi owns\nthe bytes via the content-addressed blob store)." }, "UpstreamProject": { "properties": { "name": { "type": "string", "title": "Name" }, "url": { "type": "string", "title": "Url" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License" } }, "additionalProperties": false, "type": "object", "required": [ "name", "url" ], "title": "UpstreamProject" }, "UvRuntime": { "properties": { "source": { "type": "string", "const": "git", "title": "Source", "default": "git" }, "url": { "type": "string", "title": "Url" }, "ref": { "type": "string", "title": "Ref", "default": "main" }, "package": { "type": "string", "title": "Package" } }, "additionalProperties": false, "type": "object", "required": [ "url", "package" ], "title": "UvRuntime" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifyRequest": { "properties": { "spec": { "$ref": "#/components/schemas/VerifySpec", "default": { "version": 1, "use_gpu": true, "min_inlier_ratio": 0.25, "backend_options": {}, "input_artifacts": {} } }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts" } }, "additionalProperties": false, "type": "object", "title": "VerifyRequest" }, "VerifySpec": { "properties": { "version": { "type": "integer", "const": 1, "title": "Version", "default": 1 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$" }, { "type": "null" } ], "title": "Provider", "description": "Optional backend implementation selector for geometric verification when multiple providers expose matches.verify." }, "use_gpu": { "type": "boolean", "title": "Use Gpu", "default": true }, "min_inlier_ratio": { "type": "number", "title": "Min Inlier Ratio", "default": 0.25 }, "backend_options": { "additionalProperties": true, "type": "object", "title": "Backend Options", "description": "Backend-specific geometric-verification options. Discover supported keys with GET /v1/backend/config-schemas." }, "input_artifacts": { "additionalProperties": { "$ref": "#/components/schemas/ArtifactRef" }, "type": "object", "title": "Input Artifacts", "description": "Optional role-keyed input artifact references. Use role 'matches' to verify a specific match artifact." } }, "type": "object", "title": "VerifySpec" }, "VersionResponse": { "properties": { "sfmapi": { "type": "string", "title": "Sfmapi" }, "backend": { "anyOf": [ { "$ref": "#/components/schemas/BackendVersion" }, { "type": "null" } ] } }, "type": "object", "required": [ "sfmapi" ], "title": "VersionResponse" }, "VideoFramesRequest": { "properties": { "video_path": { "type": "string", "title": "Video Path" }, "fps": { "type": "number", "maximum": 120.0, "exclusiveMinimum": 0.0, "title": "Fps", "default": 2.0 }, "max_frames": { "type": "integer", "maximum": 100000.0, "minimum": 1.0, "title": "Max Frames", "default": 1000 } }, "type": "object", "required": [ "video_path" ], "title": "VideoFramesRequest", "description": "``POST /v1/projects/{pid}/datasets:from_video`` \u2014 extract\nkeyframes from a worker-local video file." } } } }