admin.spec.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Amp Admin API",
    "description": "Administration API for Amp, a high-performance ETL system for blockchain data services on The Graph.\n\n## About\n\nThe Admin API provides a RESTful HTTP interface for managing Amp's ETL operations. This API serves as the primary administrative interface for monitoring and controlling the Amp data pipeline, allowing you to deploy datasets, trigger data extraction jobs, monitor job progress, manage distributed worker locations, configure external data providers, and perform operations on Parquet files and their metadata.\n\n## Key Capabilities\n\n### Dataset Management\nHandle the lifecycle of data extraction configurations and access dataset information:\n- List all registered datasets from the metadata database registry\n- Register new dataset configurations with versioning support\n- Trigger data extraction jobs for specific datasets or dataset versions\n- Retrieve dataset details including tables and active storage locations\n\n### Job Control\nControl and monitor data extraction and processing jobs:\n- List and retrieve job information with pagination\n- Trigger extraction jobs with optional end block configuration\n- Stop running jobs gracefully\n- Delete jobs in terminal states (Completed, Stopped, Failed)\n- Bulk cleanup operations for finalized jobs\n\n### Storage Management\nManage locations where dataset tables are stored:\n- Supports local filesystem, S3, GCS, and Azure Blob Storage\n- List storage locations and their associated files\n- Delete locations with comprehensive cleanup (removes files and metadata)\n- Query file information including Parquet metadata and statistics\n\n### Provider Configuration\nConfigure external blockchain data sources:\n- Create, retrieve, and delete provider configurations\n- Support for EVM RPC endpoints and Firehose streams\n- Providers are reusable across multiple dataset definitions\n- **Security Note**: Provider configurations may contain connection details; ensure sensitive information is properly managed\n\n### Schema Analysis\nValidate SQL queries and infer output schemas:\n- Validate queries against registered datasets without execution\n- Determine output schema using DataFusion's query planner\n- Useful for building dynamic query tools and validating dataset definitions\n\n## Pagination\n\nMost list endpoints use cursor-based pagination for efficient data retrieval:\n\n### Paginated Endpoints\nThe following endpoints support pagination:\n- Jobs: `/jobs`\n- Locations: `/locations`\n- Files: `/locations/{location_id}/files`\n\n### Non-Paginated Endpoints\nThe following endpoints return all results without pagination:\n- Datasets: `/datasets` (returns all datasets)\n- Dataset Versions: `/datasets/{name}/versions` (returns all versions for a dataset)\n\n### Query Parameters (Paginated Endpoints Only)\n- `limit`: Maximum items per page (default: 50, max: 1000)\n- `last_*_id`: Cursor from previous page's `next_cursor` field\n\n### Response Format\nPaginated responses include:\n- Array of items (e.g., `jobs`, `locations`, `files`)\n- `next_cursor`: Cursor for the next page (absent when no more results)\n\n### Usage Pattern\n\n**First Page Request:**\n```\nGET /jobs?limit=100\n```\n\n**First Page Response:**\n```json\n{\n  \"jobs\": [...],\n  \"next_cursor\": 12345\n}\n```\n\n**Next Page Request:**\n```\nGET /jobs?limit=100&last_job_id=12345\n```\n\n**Last Page Response:**\n```json\n{\n  \"jobs\": [...]\n  // No next_cursor field = end of results\n}\n```\n\n### Cursor Formats\n\nEndpoints use different cursor formats based on their data type:\n\n**Integer ID Cursors (64-bit integers):**\nMost paginated endpoints use simple integer IDs as cursors:\n- Jobs: `last_job_id=12345`\n- Locations: `last_location_id=67890`\n- Files: `last_file_id=54321`\n\n## Error Handling\n\nAll error responses follow a consistent format with:\n- `error_code`: Stable, machine-readable code (SCREAMING_SNAKE_CASE)\n- `error_message`: Human-readable error description\n\nError codes are stable across API versions and suitable for programmatic error handling. Messages may change and should only be used for display or logging.\n\n## Important Notes\n\n### Dataset Registration\nSupports two main scenarios:\n- **Derived datasets** (kind=\"manifest\"): Registered in both object store and metadata database\n- **SQL datasets** (other kinds): Dataset definitions stored in object store\n\n### Job Lifecycle\nJobs have the following terminal states that allow deletion:\n- **Completed**: Job finished successfully\n- **Stopped**: Job was manually stopped\n- **Failed**: Job encountered an error\n\nNon-terminal jobs (Scheduled, Running, StopRequested, Stopping) are protected from deletion.\n\n### Storage Locations\n- Locations can be active or inactive for queries\n- Deleting a location performs comprehensive cleanup including file removal from object store\n- Each location is associated with a specific dataset table and storage URL\n",
    "license": {
      "name": ""
    },
    "version": "1.0.0"
  },
  "paths": {
    "/datasets": {
      "get": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `GET /datasets` endpoint",
        "description": "Returns all registered datasets across all namespaces with their version information.\n\n## Response\n- **200 OK**: Successfully retrieved all datasets\n- **500 Internal Server Error**: Database query error\n\n## Error Codes\n- `LIST_ALL_DATASETS_ERROR`: Failed to list all datasets from dataset store\n\n## Behavior\nThis endpoint returns a comprehensive list of all datasets registered in the system,\ngrouped by namespace and name. For each dataset, it includes:\n- The latest semantic version (if any versions are tagged)\n- All available semantic versions in descending order\n\nThe response does not include special tags (\"latest\", \"dev\") as these are system-managed\nand can be queried via the versions endpoint for specific datasets.\n\nResults are ordered by namespace then by name (lexicographical).",
        "operationId": "list_all_datasets",
        "responses": {
          "200": {
            "description": "Successfully retrieved all datasets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetsResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `POST /datasets` endpoint",
        "description": "Registers a new dataset configuration in the server's local registry. Accepts a JSON payload\ncontaining the dataset registration configuration.\n\n**Note**: This endpoint only registers datasets and does NOT schedule data extraction.\nTo extract data after registration, make a separate call to:\n- `POST /datasets/{namespace}/{name}/versions/dev/deploy` - for dev tag\n- `POST /datasets/{namespace}/{name}/versions/latest/deploy` - for latest tag\n- `POST /datasets/{namespace}/{name}/versions/{version}/deploy` - for specific version\n\n## Request Body\n- `dataset_name`: Name of the dataset to be registered (must be valid dataset name)\n- `version`: Optional version of the dataset to register. If omitted, only the \"dev\" tag is updated.\n- `manifest`: JSON string representation of the dataset manifest\n\n## Response\n- **201 Created**: Dataset successfully registered (or updated if version tag already exists)\n- **400 Bad Request**: Invalid dataset name, version, or manifest format\n- **500 Internal Server Error**: Database or object store error\n\n## Error Codes\n- `INVALID_PAYLOAD_FORMAT`: Request JSON is malformed or invalid\n- `INVALID_MANIFEST`: Manifest JSON parsing or structure error\n- `DEPENDENCY_VALIDATION_ERROR`: SQL queries are invalid or reference undeclared dependencies\n- `MANIFEST_REGISTRATION_ERROR`: Failed to register manifest in system\n- `MANIFEST_LINKING_ERROR`: Failed to link manifest to dataset\n- `MANIFEST_NOT_FOUND`: Manifest hash provided but manifest doesn't exist\n- `VERSION_TAGGING_ERROR`: Failed to tag the manifest with the version\n- `UNSUPPORTED_DATASET_KIND`: Dataset kind is not supported\n- `STORE_ERROR`: Failed to load or access dataset store\n\n## Behavior\nThis handler supports multiple dataset kinds for registration:\n- **Derived dataset** (kind=\"manifest\"): Registers a derived dataset manifest that transforms data from other datasets using SQL queries\n- **EVM-RPC dataset** (kind=\"evm-rpc\"): Registers a raw dataset that extracts blockchain data directly from Ethereum-compatible JSON-RPC endpoints\n- **Firehose dataset** (kind=\"firehose\"): Registers a raw dataset that streams blockchain data from StreamingFast Firehose protocol\n- **Eth Beacon dataset** (kind=\"eth-beacon\"): Registers a raw dataset that extracts Ethereum Beacon Chain data\n- **Legacy SQL datasets** are **not supported** and will return an error\n\n## Registration Process\nThe registration process involves two or three steps depending on whether a version is provided:\n1. **Register or validate manifest**: Either stores a new manifest in hash-based storage and creates\n   a metadata database entry, or validates that a provided manifest hash exists in the system\n2. **Link manifest to dataset**: Links the manifest to the dataset namespace/name and automatically\n   updates the \"dev\" tag to point to this manifest (performed in a transaction for atomicity)\n3. **Tag version** (optional): If a version is provided, associates the version identifier with the\n   manifest hash, and updates the \"latest\" tag if this version is higher than the current latest\n\nThis approach enables:\n- Content-addressable storage by manifest hash\n- Deduplication of identical manifests\n- Separation of manifest storage, dataset linking, and version management\n- Development workflow: register without version to only update \"dev\" tag via linking\n- Release workflow: register with version to create semantic version tags and update \"latest\"\n- Reuse workflow: provide manifest hash to link existing manifest without re-registering it\n\nAll operations are idempotent:\n- **Manifest registration**: If the manifest already exists (same hash), the operation succeeds without changes\n- **Manifest linking**: If the manifest is already linked to the dataset, the operation succeeds without changes\n- **Dev tag update**: The dev tag is always updated to point to the linked manifest (last-write-wins)\n- **Version tag**: If the version tag doesn't exist, it is created; if it exists with the same hash, no changes;\n  if it exists with a different hash, it is updated to point to the new hash\n- **Latest tag**: Automatically updated only if the new version is higher than the current latest version\n\nThe handler:\n- Validates dataset name and version format\n- Checks that dataset kind is supported\n- Registers/validates the manifest, links it to the dataset, and optionally tags it with a version\n- Returns appropriate status codes and error messages\n\n## Typical Workflow\nFor users wanting both registration and data extraction:\n1. `POST /datasets` - Register the dataset (this endpoint)\n2. `POST /datasets/{namespace}/{name}/versions/{version}/deploy` - Schedule data extraction",
        "operationId": "datasets_register",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Dataset successfully registered or updated"
          },
          "400": {
            "description": "Invalid request format or manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{namespace}/{name}": {
      "delete": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `DELETE /datasets/{namespace}/{name}` endpoint",
        "description": "Removes all manifest links and version tags for a dataset.\n\n## Response\n- **204 No Content**: Dataset successfully deleted (or didn't exist)\n- **400 Bad Request**: Invalid path parameters\n- **500 Internal Server Error**: Database operation error\n\n## Error Codes\n- `INVALID_PATH`: Invalid namespace or name in path parameters\n- `UNLINK_DATASET_MANIFESTS_ERROR`: Failed to unlink dataset manifests from dataset store\n\n## Behavior\nThis endpoint deletes all metadata for a dataset including:\n- All manifest links in the dataset_manifests table\n- All version tags (cascaded automatically via foreign key constraint)\n- Orphaned manifest files (manifests not referenced by any other dataset)\n\nThis operation is fully idempotent - it returns 204 even if the dataset\ndoesn't exist. Manifests that are still referenced by other datasets are\npreserved.",
        "operationId": "delete_dataset",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "description": "Dataset namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "description": "Dataset name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Dataset successfully deleted"
          },
          "400": {
            "description": "Invalid path parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{namespace}/{name}/versions": {
      "get": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `GET /datasets/{namespace}/{name}/versions` endpoint",
        "description": "Returns all versions for a dataset with their metadata.\n\n## Response\n- **200 OK**: Successfully retrieved version list\n- **400 Bad Request**: Invalid path parameters\n- **500 Internal Server Error**: Database query error\n\n## Error Codes\n- `INVALID_PATH`: Invalid namespace or name in path parameters\n- `LIST_VERSION_TAGS_ERROR`: Failed to list version tags from dataset store\n- `RESOLVE_REVISION_ERROR`: Failed to resolve dev tag revision\n\n## Behavior\nThis endpoint returns comprehensive version information for a dataset:\n- All semantic versions sorted in descending order (newest first)\n- For each version: manifest hash, creation time, and last update time\n- Special tags: \"latest\" (if any semantic versions exist) and \"dev\" (if set)\n\nThe \"latest\" tag is automatically managed and always points to the highest\nsemantic version. The \"dev\" tag is explicitly managed via the registration\nendpoint and may point to any manifest hash.\n\nReturns an empty list if the dataset has no registered versions.",
        "operationId": "list_dataset_versions",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "description": "Dataset namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "description": "Dataset name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved versions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid path parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{namespace}/{name}/versions/{revision}": {
      "get": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `GET /datasets/{namespace}/{name}/versions/{revision}` endpoint",
        "description": "Returns detailed dataset information for the specified revision.\n\n## Response\n- **200 OK**: Successfully retrieved dataset information\n- **400 Bad Request**: Invalid path parameters\n- **404 Not Found**: Dataset or revision not found\n- **500 Internal Server Error**: Database or dataset store error\n\n## Error Codes\n- `INVALID_PATH`: Invalid namespace, name, or revision in path parameters\n- `DATASET_NOT_FOUND`: The specified dataset or revision does not exist\n- `RESOLVE_REVISION_ERROR`: Failed to resolve revision to manifest hash\n- `GET_MANIFEST_PATH_ERROR`: Failed to query manifest path from metadata database\n- `READ_MANIFEST_ERROR`: Failed to read manifest file from object store\n- `PARSE_MANIFEST_ERROR`: Failed to parse manifest JSON\n\n## Behavior\nThis endpoint retrieves detailed information about a specific dataset revision.\nThe revision parameter supports four types:\n- Semantic version (e.g., \"1.2.3\")\n- Manifest hash (SHA256 hash)\n- \"latest\" - resolves to the highest semantic version\n- \"dev\" - resolves to the development version\n\nThe endpoint first resolves the revision to a manifest hash, then returns\nbasic dataset information including namespace, name, revision, manifest hash, and kind.",
        "operationId": "get_dataset_by_revision",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "description": "Dataset namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "description": "Dataset name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revision",
            "in": "path",
            "description": "Revision (version, hash, latest, or dev)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetInfo"
                }
              }
            }
          },
          "400": {
            "description": "Invalid path parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Dataset or revision not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{namespace}/{name}/versions/{revision}/deploy": {
      "post": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `POST /datasets/{namespace}/{name}/versions/{revision}/deploy` endpoint",
        "description": "Schedules a data extraction job for the specified dataset revision.\n\n## Response\n- **202 Accepted**: Job successfully scheduled\n- **400 Bad Request**: Invalid path parameters or request body\n- **404 Not Found**: Dataset or revision not found\n- **500 Internal Server Error**: Database or scheduler error\n\n## Error Codes\n- `INVALID_PATH`: Invalid path parameters (namespace, name, or revision)\n- `INVALID_BODY`: Invalid request body (malformed JSON or missing required fields)\n- `DATASET_NOT_FOUND`: The specified dataset or revision does not exist\n- `LIST_VERSION_TAGS_ERROR`: Failed to list version tags from dataset store\n- `RESOLVE_REVISION_ERROR`: Failed to resolve revision to manifest hash\n- `GET_DATASET_ERROR`: Failed to load dataset from store\n- `SCHEDULER_ERROR`: Failed to schedule extraction job\n\n## Behavior\nThis endpoint schedules a data extraction job for a dataset:\n1. Resolves the revision to find the corresponding version tag\n2. Loads the full dataset configuration from the dataset store\n3. Schedules an extraction job with the specified parameters\n4. Returns job ID for tracking\n\nThe revision parameter supports four types:\n- Semantic version (e.g., \"1.2.3\") - uses that specific version\n- \"latest\" - resolves to the highest semantic version\n- \"dev\" - resolves to the development version tag\n- Manifest hash (SHA256 hash) - finds the version that points to this hash\n\nJobs are executed asynchronously by worker nodes. Use the returned job ID\nto track progress via the jobs endpoints.",
        "operationId": "deploy_dataset",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "description": "Dataset namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "description": "Dataset name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revision",
            "in": "path",
            "description": "Revision (version, hash, latest, or dev)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeployRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Job successfully scheduled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeployResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request (invalid parameters)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Dataset or revision not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{namespace}/{name}/versions/{revision}/manifest": {
      "get": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `GET /datasets/{namespace}/{name}/versions/{revision}/manifest` endpoint",
        "description": "Retrieves the raw manifest JSON for the specified dataset revision.\n\n## Response\n- **200 OK**: Successfully retrieved manifest\n- **404 Not Found**: Dataset, revision, or manifest not found\n- **500 Internal Server Error**: Database or object store error\n\n## Error Codes\n- `INVALID_PATH`: Invalid namespace, name, or revision in path parameters\n- `DATASET_NOT_FOUND`: The specified dataset or revision does not exist\n- `MANIFEST_NOT_FOUND`: The manifest file was not found in object storage\n- `RESOLVE_REVISION_ERROR`: Failed to resolve revision to manifest hash\n- `GET_MANIFEST_PATH_ERROR`: Failed to query manifest path from metadata database\n- `READ_MANIFEST_ERROR`: Failed to read manifest file from object store\n- `PARSE_MANIFEST_ERROR`: Failed to parse manifest JSON\n\n## Behavior\nThis endpoint returns the raw manifest JSON document for a dataset revision.\nThe revision parameter supports four types:\n- Semantic version (e.g., \"1.2.3\")\n- Manifest hash (SHA256 hash)\n- \"latest\" - resolves to the highest semantic version\n- \"dev\" - resolves to the development version\n\nThe endpoint first resolves the revision to a manifest hash, then retrieves\nthe manifest JSON from object storage. Manifests are immutable and\ncontent-addressable, identified by their SHA256 hash.",
        "operationId": "get_dataset_manifest",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "description": "Dataset namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "description": "Dataset name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revision",
            "in": "path",
            "description": "Revision (version, hash, latest, or dev)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Value"
                }
              }
            }
          },
          "404": {
            "description": "Dataset or revision not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/datasets/{namespace}/{name}/versions/{version}": {
      "delete": {
        "tags": [
          "datasets"
        ],
        "summary": "Handler for the `DELETE /datasets/{namespace}/{name}/versions/{version}` endpoint",
        "description": "Removes a semantic version tag from a dataset.\n\n## Response\n- **204 No Content**: Version successfully deleted (or didn't exist)\n- **400 Bad Request**: Invalid path parameters or attempting to delete the \"latest\" version\n- **500 Internal Server Error**: Database operation error\n\n## Error Codes\n- `INVALID_PATH`: Invalid namespace, name, or version in path parameters\n- `CANNOT_DELETE_LATEST_VERSION`: Cannot delete the version currently tagged as \"latest\"\n- `RESOLVE_LATEST_REVISION_ERROR`: Failed to resolve the \"latest\" tag to its manifest hash\n- `RESOLVE_VERSION_REVISION_ERROR`: Failed to resolve the requested version to its manifest hash\n- `DELETE_VERSION_TAG_ERROR`: Failed to delete version tag from dataset store\n\n## Behavior\nThis endpoint removes a semantic version tag from a dataset. The deletion follows this flow:\n\n1. **Check version existence**: Resolves the requested version to its manifest hash.\n   If the version doesn't exist, returns 204 immediately (idempotent).\n\n2. **Check \"latest\" protection**: Resolves the \"latest\" tag to its manifest hash and compares\n   with the requested version's hash. If they point to the same manifest, deletion is rejected\n   with a 400 error. You must create a newer version first to update the \"latest\" tag.\n\n3. **Delete version tag**: Removes only the version tag from the database. The underlying\n   manifest file is never deleted (manifests are content-addressable and may be referenced\n   by other versions or datasets).\n\nThis operation is fully idempotent - it returns 204 even if the version doesn't exist.",
        "operationId": "delete_dataset_version",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "description": "Dataset namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "description": "Dataset name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "description": "Semantic version (e.g., 1.2.3)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Version successfully deleted"
          },
          "400": {
            "description": "Invalid path parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/files/{file_id}": {
      "get": {
        "tags": [
          "files"
        ],
        "summary": "Handler for the `GET /files/{file_id}` endpoint",
        "description": "Retrieves and returns a specific file by its ID from the metadata database.\n\n## Path Parameters\n- `file_id`: The unique identifier of the file to retrieve (must be a positive integer)\n\n## Response\n- **200 OK**: Returns the file information as JSON\n- **400 Bad Request**: Invalid file ID format (not a number, zero, or negative)\n- **404 Not Found**: File with the given ID does not exist\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_FILE_ID`: The provided ID is not a valid positive integer\n- `FILE_NOT_FOUND`: No file exists with the given ID\n- `METADATA_DB_ERROR`: Internal database error occurred\n\nThis handler:\n- Validates and extracts the file ID from the URL path\n- Queries the metadata database for the file with location information\n- Returns appropriate HTTP status codes and error messages",
        "operationId": "files_get",
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "description": "File ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved file information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileInfo"
                }
              }
            }
          },
          "400": {
            "description": "Invalid file ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "File not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/jobs": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "Handler for the `GET /jobs` endpoint",
        "description": "Retrieves and returns a paginated list of jobs from the metadata database.\n\n## Query Parameters\n- `limit`: Maximum number of jobs to return (default: 50, max: 1000)\n- `last_job_id`: ID of the last job from previous page for cursor-based pagination\n\n## Response\n- **200 OK**: Returns paginated job data with next cursor\n- **400 Bad Request**: Invalid limit parameter (0, negative, or > 1000)\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_QUERY_PARAMETERS`: Invalid query parameters (malformed or unparseable)\n- `LIMIT_TOO_LARGE`: Limit exceeds maximum allowed value (>1000)\n- `LIMIT_INVALID`: Limit is zero\n- `LIST_JOBS_ERROR`: Failed to list jobs from scheduler (database error)",
        "operationId": "jobs_list",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of jobs to return (default: 50, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "last_job_id",
            "in": "query",
            "description": "ID of the last job from the previous page for pagination",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved jobs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "jobs"
        ],
        "summary": "Handler for the `DELETE /jobs?status=<filter>` endpoint",
        "description": "Deletes jobs based on status filter. Supports deleting jobs by various status criteria.\n\n## Query Parameters\n- `status=terminal`: Delete all jobs in terminal states (Completed, Stopped, Failed)\n- `status=completed`: Delete all completed jobs\n- `status=stopped`: Delete all stopped jobs\n- `status=error`: Delete all failed jobs\n\n## Response\n- **204 No Content**: Operation completed successfully\n- **400 Bad Request**: Invalid or missing status query parameter\n- **500 Internal Server Error**: Database error occurred\n\n## Error Codes\n- `INVALID_QUERY_PARAM`: Invalid or missing status parameter\n- `DELETE_JOBS_BY_STATUS_ERROR`: Failed to delete jobs by status from scheduler (database error)\n\n## Behavior\nThis handler provides bulk job cleanup with the following characteristics:\n- Only jobs in terminal states (Completed, Stopped, Failed) are deleted\n- Non-terminal jobs are completely protected from deletion\n- Database layer ensures atomic bulk deletion\n- Safe to call even when no terminal jobs exist\n\n## Terminal States\nJobs are deleted when in these states:\n- Completed → Safe to delete\n- Stopped → Safe to delete\n- Failed → Safe to delete\n\nProtected states (never deleted):\n- Scheduled → Job is waiting to run\n- Running → Job is actively executing\n- StopRequested → Job is being stopped\n- Stopping → Job is in process of stopping\n- Unknown → Invalid state\n\n## Usage\nThis endpoint is typically used for:\n- Periodic cleanup of completed jobs\n- Administrative maintenance\n- Freeing up database storage",
        "operationId": "jobs_delete_many",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Status filter for jobs to delete",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/String"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Jobs deleted successfully"
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "Handler for the `GET /jobs/{id}` endpoint",
        "description": "Retrieves and returns a specific job by its ID from the metadata database.\n\n## Path Parameters\n- `id`: The unique identifier of the job to retrieve (must be a valid JobId)\n\n## Response\n- **200 OK**: Returns the job information as JSON\n- **400 Bad Request**: Invalid job ID format (not parseable as JobId)\n- **404 Not Found**: Job with the given ID does not exist\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_JOB_ID`: The provided ID is not a valid job identifier\n- `JOB_NOT_FOUND`: No job exists with the given ID\n- `GET_JOB_ERROR`: Failed to retrieve job from scheduler (database error)",
        "operationId": "jobs_get",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved job information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobInfo"
                }
              }
            }
          },
          "400": {
            "description": "Invalid job ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Job not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "jobs"
        ],
        "summary": "Handler for the `DELETE /jobs/{id}` endpoint",
        "description": "Deletes a job by its ID if it's in a terminal state (Completed, Stopped, or Failed).\nThis is a safe, idempotent operation that only removes finalized jobs from the system.\n\n## Path Parameters\n- `id`: The unique identifier of the job to delete (must be a valid JobId)\n\n## Response\n- **204 No Content**: Job was successfully deleted or does not exist (idempotent)\n- **400 Bad Request**: Invalid job ID format (not parseable as JobId)\n- **409 Conflict**: Job exists but is not in a terminal state (cannot be deleted)\n- **500 Internal Server Error**: Database error occurred\n\n## Error Codes\n- `INVALID_JOB_ID`: The provided ID is not a valid job identifier\n- `JOB_CONFLICT`: Job exists but is not in a terminal state\n- `GET_JOB_ERROR`: Failed to retrieve job from scheduler (database error)\n- `DELETE_JOB_ERROR`: Failed to delete job from scheduler (database error)\n\n## Idempotent Behavior\nThis handler is idempotent - deleting a non-existent job returns 204 (success).\nThis allows clients to safely retry deletions without worrying about 404 errors.\n\n## Behavior\nThis handler provides safe job deletion with the following characteristics:\n- Only jobs in terminal states (Completed, Stopped, Failed) can be deleted\n- Non-terminal jobs are protected from accidental deletion\n- Non-existent jobs return success (idempotent behavior)\n- Database layer ensures atomic deletion\n\n## Terminal States\nJobs can only be deleted when in these states:\n- Completed → Safe to delete\n- Stopped → Safe to delete\n- Failed → Safe to delete\n\nProtected states (cannot be deleted):\n- Scheduled → Job is waiting to run\n- Running → Job is actively executing\n- StopRequested → Job is being stopped\n- Stopping → Job is in process of stopping\n- Unknown → Invalid state",
        "operationId": "jobs_delete",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Job deleted successfully or does not exist (idempotent)"
          },
          "400": {
            "description": "Invalid job ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Job cannot be deleted (not in terminal state)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}/stop": {
      "put": {
        "tags": [
          "jobs"
        ],
        "summary": "Handler for the `PUT /jobs/{id}/stop` endpoint",
        "description": "Stops a running job using the specified job ID. This is an idempotent\noperation that handles job termination requests safely.\n\n## Path Parameters\n- `id`: The unique identifier of the job to stop (must be a valid JobId)\n\n## Response\n- **200 OK**: Job stop request processed successfully, or job already in terminal state (idempotent)\n- **400 Bad Request**: Invalid job ID format (not parseable as JobId)\n- **404 Not Found**: Job with the given ID does not exist\n- **500 Internal Server Error**: Database connection or scheduler error\n\n## Error Codes\n- `INVALID_JOB_ID`: The provided ID is not a valid job identifier\n- `JOB_NOT_FOUND`: No job exists with the given ID\n- `STOP_JOB_ERROR`: Database error during stop operation execution\n- `UNEXPECTED_STATE_CONFLICT`: Internal state machine error (indicates a bug)\n\n## Idempotent Behavior\nThis handler is idempotent - stopping a job that's already in a terminal state returns success (200).\nThis allows clients to safely retry stop requests without worrying about conflict errors.\n\nThe desired outcome of a stop request is that the job is not running. If the job is already\nstopped, completed, or failed, this outcome is achieved, so we return success.\n\n## Behavior\nThis handler provides idempotent job stopping with the following characteristics:\n- Jobs already in terminal states (Stopped, Completed, Failed) return success (idempotent)\n- Only running/scheduled jobs transition to stop-requested state\n- Job lookup and stop request are performed atomically within a single transaction\n- Database layer validates state transitions and prevents race conditions\n\n## State Transitions\nValid stop transitions:\n- Scheduled → StopRequested (200 OK)\n- Running → StopRequested (200 OK)\n\nAlready terminal (idempotent - return success):\n- Stopped → no change (200 OK)\n- Completed → no change (200 OK)\n- Failed → no change (200 OK)\n\nThe handler:\n- Validates and extracts the job ID from the URL path\n- Delegates to scheduler for atomic stop operation (job lookup + stop + worker notification)\n- Returns success if job is already in terminal state (idempotent)\n- Returns appropriate HTTP status codes and error messages",
        "operationId": "jobs_stop",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Job ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job stop request processed successfully, or job already in terminal state (idempotent)"
          },
          "400": {
            "description": "Invalid job ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Job not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/locations": {
      "get": {
        "tags": [
          "locations"
        ],
        "summary": "Handler for the `GET /locations` endpoint",
        "description": "Retrieves and returns a paginated list of locations from the metadata database.\n\n## Query Parameters\n- `limit`: Maximum number of locations to return (default: 50, max: 1000)\n- `last_location_id`: ID of the last location from previous page for cursor-based pagination\n\n## Response\n- **200 OK**: Returns paginated location data with next cursor\n- **400 Bad Request**: Invalid limit parameter (0, negative, or > 1000)\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_REQUEST`: Invalid query parameters (limit out of range)\n- `METADATA_DB_ERROR`: Internal database error occurred\n\nThis handler:\n- Accepts query parameters for pagination (limit, last_location_id)\n- Validates the limit parameter (max 1000)\n- Calls the metadata DB to list locations with pagination\n- Returns a structured response with locations and next cursor",
        "operationId": "locations_list",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of locations to return (default: 50, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "last_location_id",
            "in": "query",
            "description": "ID of the last location from the previous page for pagination",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved locations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/locations/{id}": {
      "get": {
        "tags": [
          "locations"
        ],
        "summary": "Handler for the `GET /locations/{id}` endpoint",
        "description": "Retrieves and returns a specific location by its ID from the metadata database.\n\n## Path Parameters\n- `id`: The unique identifier of the location to retrieve (must be a positive integer)\n\n## Response\n- **200 OK**: Returns the location information as JSON\n- **400 Bad Request**: Invalid location ID format (not a number, zero, or negative)\n- **404 Not Found**: Location with the given ID does not exist\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_LOCATION_ID`: The provided ID is not a valid positive integer\n- `LOCATION_NOT_FOUND`: No location exists with the given ID\n- `METADATA_DB_ERROR`: Internal database error occurred\n\nThis handler:\n- Validates and extracts the location ID from the URL path\n- Queries the metadata database for the location\n- Returns appropriate HTTP status codes and error messages",
        "operationId": "locations_get",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Location ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved location information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationInfoWithDetails"
                }
              }
            }
          },
          "400": {
            "description": "Invalid location ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Location not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "locations"
        ],
        "summary": "Handler for the `DELETE /locations/{id}` endpoint",
        "description": "Deletes a specific location by its ID from the metadata database.\n\n## Path Parameters\n- `id`: The unique identifier of the location to delete (must be a positive integer)\n\n## Query Parameters\n- `force`: (optional, default: false) Force deletion even if location is active\n\n## Response\n- **204 No Content**: Location successfully deleted\n- **400 Bad Request**: Invalid location ID format or invalid query parameters\n- **404 Not Found**: Location with the given ID does not exist\n- **409 Conflict**: Location is active (without force=true) or has an ongoing job\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_LOCATION_ID`: The provided ID is not a valid positive integer\n- `INVALID_QUERY_PARAMETERS`: The query parameters cannot be parsed\n- `LOCATION_NOT_FOUND`: No location exists with the given ID\n- `ACTIVE_LOCATION_CONFLICT`: Location is active and cannot be deleted without force=true\n- `ONGOING_JOB_CONFLICT`: Location has an ongoing job and cannot be deleted\n- `METADATA_DB_ERROR`: Internal database error occurred\n\n## Safety Checks\n- Active locations require `force=true` to be deleted\n- Locations with ongoing jobs cannot be deleted (even with force=true)\n- Users must stop active jobs before deleting associated locations\n\nThis handler:\n- Validates and extracts the location ID from the URL path\n- Validates optional query parameters (force flag)\n- Performs safety checks for active locations and ongoing jobs\n- Deletes associated files from object store\n- Deletes the location from the metadata database\n- Returns appropriate HTTP status codes and error messages",
        "operationId": "locations_delete",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Location ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "force",
            "in": "query",
            "description": "Force deletion even if location is active",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Location successfully deleted"
          },
          "400": {
            "description": "Invalid location ID or query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Location not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Location is active or has ongoing job",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/locations/{location_id}/files": {
      "get": {
        "tags": [
          "locations"
        ],
        "summary": "Handler for the `GET /locations/{location_id}/files` endpoint",
        "description": "Retrieves and returns a paginated list of files for a specific location from the metadata database.\n\n## Path Parameters\n- `location_id`: The unique identifier of the location (must be a positive integer)\n\n## Query Parameters\n- `limit`: Maximum number of files to return (default: 50, max: 1000)\n- `last_file_id`: ID of the last file from previous page for cursor-based pagination\n\n## Response\n- **200 OK**: Returns paginated file data with next cursor\n- **400 Bad Request**: Invalid location ID format or invalid limit parameter\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_LOCATION_ID`: Invalid location ID format\n- `INVALID_QUERY_PARAMETERS`: Invalid query parameters (limit out of range)\n- `LIMIT_TOO_LARGE`: Limit exceeds maximum allowed value\n- `LIMIT_INVALID`: Limit is zero or negative\n- `METADATA_DB_ERROR`: Internal database error occurred\n\nThis handler:\n- Validates and extracts the location ID from the URL path\n- Accepts query parameters for pagination (limit, last_file_id)\n- Validates the limit parameter (max 1000)\n- Calls the metadata DB to list files with pagination for the specified location\n- Returns a structured response with minimal file info and next cursor",
        "operationId": "locations_list_files",
        "parameters": [
          {
            "name": "location_id",
            "in": "path",
            "description": "Location ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved location files",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationFilesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid location ID or query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/manifests": {
      "post": {
        "tags": [
          "manifests"
        ],
        "summary": "Handler for the `POST /manifests` endpoint",
        "description": "Registers a new manifest in content-addressable storage without linking to any dataset or creating version tags.\nThis endpoint is useful for pre-registering manifests before associating them with specific datasets.\n\n## Request Body\nThe request body should contain a complete manifest JSON object. The manifest kind determines\nthe validation rules:\n- `kind=\"manifest\"` (Derived): Validates SQL dependencies\n- `kind=\"evm-rpc\"`, `kind=\"firehose\"`, `kind=\"eth-beacon\"` (Raw): Validates structure only\n\n## Response\n- **201 Created**: Manifest successfully registered, returns the computed hash\n- **400 Bad Request**: Invalid JSON format, unsupported kind, or validation failure\n- **500 Internal Server Error**: Manifest store error\n\n## Error Codes\n- `INVALID_PAYLOAD_FORMAT`: Request JSON is malformed or invalid\n- `INVALID_MANIFEST`: Manifest JSON parsing or structure error\n- `DEPENDENCY_VALIDATION_ERROR`: SQL dependency validation failed (derived datasets only)\n- `UNSUPPORTED_DATASET_KIND`: Dataset kind is not supported\n- `MANIFEST_STORE_ERROR`: Failed to store manifest in object store or metadata database\n\n## Registration Process\nUnlike `POST /datasets`, this endpoint performs minimal registration:\n1. **Parse and validate**: Validates manifest structure and dependencies (for derived datasets)\n2. **Canonicalize**: Re-serializes manifest to canonical JSON format\n3. **Compute hash**: Generates content hash from canonical JSON\n4. **Store manifest**: Writes to object store and registers in metadata database\n\nThis handler:\n- Validates and extracts the manifest JSON from the request body\n- Parses and validates based on dataset kind\n- Stores the manifest in content-addressable storage\n- Returns the computed manifest hash",
        "operationId": "manifests_register",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {}
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Manifest successfully registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterManifestResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request format or manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "manifests"
        ],
        "summary": "Handler for the `DELETE /manifests` endpoint",
        "description": "Deletes all orphaned manifests (manifests with no dataset links).\nThis is a bulk cleanup operation for removing unused manifests and reclaiming storage space.\n\n## Response\n- **200 OK**: Returns JSON with count of deleted manifests\n- **500 Internal Server Error**: Database error\n\n## Error Codes\n- `LIST_ORPHANED_MANIFESTS_ERROR`: Failed to list orphaned manifests\n\n## Pruning Process\nThis handler:\n1. Queries the metadata database for all manifests not linked to any datasets\n2. Deletes each orphaned manifest concurrently from both object store and metadata database\n3. Logs individual deletion failures but continues processing remaining manifests\n4. Returns the count of successfully deleted manifests\n\nIndividual manifest deletion failures are logged as warnings but don't fail the entire operation,\nallowing partial cleanup even if some manifests cannot be removed.\nThe operation is idempotent - safe to call repeatedly.",
        "operationId": "manifests_prune",
        "responses": {
          "200": {
            "description": "Orphaned manifests pruned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PruneResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/manifests/{hash}": {
      "get": {
        "tags": [
          "manifests"
        ],
        "summary": "Handler for the `GET /manifests/{hash}` endpoint",
        "description": "Retrieves the raw manifest JSON for a specific manifest hash.\n\n## Path Parameters\n- `hash`: Manifest content hash (validated hash format)\n\n## Response\n- **200 OK**: Returns the raw manifest JSON\n- **400 Bad Request**: Invalid manifest hash format\n- **404 Not Found**: Manifest with the given hash does not exist\n- **500 Internal Server Error**: Manifest retrieval error\n\n## Error Codes\n- `INVALID_HASH`: The provided hash is not valid (invalid hash format or parsing error)\n- `MANIFEST_NOT_FOUND`: No manifest exists with the given hash\n- `MANIFEST_RETRIEVAL_ERROR`: Failed to retrieve manifest from the dataset manifests store\n\n## Retrieval Process\nThis handler retrieves manifests from content-addressable storage:\n- The dataset manifests store queries the metadata database internally to resolve the hash to a file path\n- Then fetches the manifest content from the object store\n\nThis handler:\n- Validates and extracts the manifest hash from the URL path\n- Retrieves the raw manifest JSON from the dataset manifests store using the hash\n- Returns the manifest as a JSON response with proper Content-Type header",
        "operationId": "manifests_get_by_hash",
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "description": "Manifest content hash",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved manifest JSON (schema varies by manifest kind)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid manifest hash",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Manifest not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Manifest retrieval error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "manifests"
        ],
        "summary": "Handler for the `DELETE /manifests/{hash}` endpoint",
        "description": "Deletes a manifest from both object store and metadata database.\n**Manifests linked to datasets cannot be deleted** (returns 409 Conflict).\n\nThis endpoint is idempotent: deleting a non-existent manifest returns success (204 No Content).\n\n## Path Parameters\n- `hash`: Manifest content hash to delete\n\n## Response\n- **204 No Content**: Manifest successfully deleted (or already deleted)\n- **400 Bad Request**: Invalid manifest hash format\n- **409 Conflict**: Manifest is linked to datasets and cannot be deleted\n- **500 Internal Server Error**: Store or database error\n\n## Error Codes\n- `INVALID_HASH`: Invalid hash format\n- `MANIFEST_LINKED`: Manifest is linked to datasets and cannot be deleted\n- `MANIFEST_DELETE_ERROR`: Failed to delete manifest\n\n## Deletion Flow\nThis handler:\n1. Validates and extracts the manifest hash from the URL path\n2. Checks if the manifest is linked to any datasets\n3. If linked: Returns 409 Conflict error (deletion not allowed)\n4. If not linked:\n   - Deletes manifest record from metadata database\n   - Deletes manifest file from object store\n   - Treats \"not found\" as success (idempotent behavior)\n5. Returns 204 No Content on success\n\n## Safety Notes\n- Only unlinked manifests can be deleted (no dataset dependencies)\n- To delete a linked manifest, first remove all dataset associations\n- Deletion is permanent and cannot be undone",
        "operationId": "manifests_delete",
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "description": "Manifest content hash",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Manifest successfully deleted (or already deleted)"
          },
          "400": {
            "description": "Invalid hash",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Manifest linked to datasets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/manifests/{hash}/datasets": {
      "get": {
        "tags": [
          "manifests"
        ],
        "summary": "Handler for the `GET /manifests/{hash}/datasets` endpoint",
        "description": "Lists all datasets that reference a specific manifest hash.\n\n## Path Parameters\n- `hash`: Manifest content hash (validated hash format)\n\n## Response\n- **200 OK**: Successfully retrieved datasets using manifest\n- **400 Bad Request**: Invalid manifest hash format\n- **404 Not Found**: Manifest with the given hash does not exist\n- **500 Internal Server Error**: Database query error\n\n## Error Codes\n- `INVALID_HASH`: The provided hash is not valid (invalid hash format or parsing error)\n- `MANIFEST_NOT_FOUND`: No manifest exists with the given hash\n- `QUERY_MANIFEST_PATH_ERROR`: Failed to query manifest path from metadata database\n- `LIST_DATASET_TAGS_ERROR`: Failed to list dataset tags from metadata database\n\n## Behavior\nThis handler queries the dataset store to find all datasets using a manifest:\n- Validates and extracts the manifest hash from the URL path\n- Queries dataset store for all dataset tags referencing this manifest\n- Returns 404 if the manifest doesn't exist\n- Returns list of datasets with their namespace, name, and version",
        "operationId": "list_manifest_datasets",
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "description": "Manifest hash (64-char hex)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved datasets using manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestDatasetsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid manifest hash",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Manifest not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/providers": {
      "get": {
        "tags": [
          "providers"
        ],
        "summary": "Handler for the `GET /providers` endpoint",
        "description": "Retrieves and returns complete information for all provider configurations from the dataset store.\n\n## Security Note\n\nThis endpoint returns the **complete provider configuration** including all configuration\ndetails stored in the provider files. Ensure that sensitive information such as API keys,\nconnection strings, and credentials are not stored in provider configuration files or\nare properly filtered before storage.\n\n## Response\n- **200 OK**: Returns provider metadata as JSON\n\nThis handler:\n- Accesses cached provider configurations from the dataset store\n- Transforms available provider configurations to API response format including full configuration\n- Cannot fail as it returns cached data; any store/parsing errors are logged during cache loading (explicit via `load_into_cache()` or lazy-loaded on first access)\n- Filters out providers that cannot be converted to valid API format (conversion errors are logged)",
        "operationId": "providers_list",
        "responses": {
          "200": {
            "description": "Successfully retrieved all providers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvidersResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "providers"
        ],
        "summary": "Handler for the `POST /providers` endpoint",
        "description": "Creates a new provider configuration and stores it in the dataset store.\n\n## Request Body\n- JSON object containing provider configuration with required fields:\n  - `name`: The unique identifier for the provider\n  - `kind`: The type of provider (e.g., \"evm-rpc\", \"firehose\")\n  - `network`: The blockchain network (e.g., \"mainnet\", \"goerli\", \"polygon\")\n  - Additional provider-specific configuration fields as needed\n\n## Response\n- **201 Created**: Provider created successfully\n- **400 Bad Request**: Invalid request body or provider configuration\n- **409 Conflict**: Provider with the same name already exists\n- **500 Internal Server Error**: Store error\n\n## Error Codes\n- `INVALID_REQUEST_BODY`: Malformed JSON request body\n- `DATA_CONVERSION_ERROR`: Failed to convert JSON to TOML format\n- `PROVIDER_CONFLICT`: Provider name already exists\n- `STORE_ERROR`: Failed to save provider configuration\n\nThis handler:\n- Validates and extracts the provider data from the JSON request body\n- Converts additional JSON configuration fields to TOML format\n- Registers the provider configuration in the dataset store\n- Returns HTTP 201 on successful creation",
        "operationId": "providers_create",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProviderInfo"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Provider created successfully"
          },
          "400": {
            "description": "Invalid request body or provider configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Provider with the same name already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/providers/{name}": {
      "get": {
        "tags": [
          "providers"
        ],
        "summary": "Handler for the `GET /providers/{name}` endpoint",
        "description": "Retrieves and returns complete information for a specific provider configuration by its name from the dataset store.\n\n## Security Note\n\nThis endpoint returns the **complete provider configuration** including all configuration\ndetails stored in the provider files. Ensure that sensitive information such as API keys,\nconnection strings, and credentials are not stored in provider configuration files or\nare properly filtered before storage.\n\n## Path Parameters\n- `name`: The unique name/identifier of the provider to retrieve\n\n## Response\n- **200 OK**: Returns the provider metadata as JSON\n- **400 Bad Request**: Invalid provider name format\n- **404 Not Found**: Provider with the given name does not exist\n\n## Error Codes\n- `INVALID_PROVIDER_NAME`: The provided name is invalid or malformed\n- `PROVIDER_NOT_FOUND`: No provider exists with the given name\n\nThis handler:\n- Validates and extracts the provider name from the URL path\n- Accesses cached provider configurations from the dataset store\n- Returns 404 if provider not found in cache; store/parsing errors are logged during cache loading\n- Converts provider configuration to API response format including full configuration details\n\nNote: Empty provider names (e.g., `GET /providers/`) are handled by Axum's routing layer\nand return 404 before reaching this handler, ensuring no conflict with the get_all endpoint.",
        "operationId": "providers_get",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Provider name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved provider information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProviderInfo"
                }
              }
            }
          },
          "400": {
            "description": "Invalid provider name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Provider not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "providers"
        ],
        "summary": "Handler for the `DELETE /providers/{name}` endpoint",
        "description": "Deletes a specific provider configuration by its name from the dataset store.\n\nThis operation is idempotent - deleting a non-existent provider returns success.\n\n## Path Parameters\n- `name`: The unique name/identifier of the provider to delete\n\n## Response\n- **204 No Content**: Provider successfully deleted (or did not exist)\n- **400 Bad Request**: Invalid provider name format\n- **500 Internal Server Error**: Store error occurred during deletion\n\n## Error Codes\n- `INVALID_PROVIDER_NAME`: The provided name is invalid or malformed\n- `STORE_ERROR`: Failed to delete provider configuration from store\n\nThis handler:\n- Validates and extracts the provider name from the URL path\n- Attempts to delete the provider configuration from both store and cache\n- Returns 204 even if the provider does not exist (idempotent behavior)\n\n## Safety Notes\n- Deletion removes both the configuration file from storage and the cached entry\n- Once deleted, the provider configuration cannot be recovered\n- Any datasets using this provider may fail until a new provider is configured",
        "operationId": "providers_delete",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Provider name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Provider successfully deleted (or did not exist)"
          },
          "400": {
            "description": "Invalid provider name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/schema": {
      "post": {
        "tags": [
          "schema"
        ],
        "summary": "Handler for the `/schema` endpoint that provides SQL schema analysis.",
        "description": "This endpoint performs comprehensive SQL validation and schema inference by:\n1. **Parsing SQL**: Validates syntax using DataFusion's SQL parser\n2. **Loading Datasets**: Retrieves actual dataset definitions from the registry\n3. **Schema Resolution**: Creates planning context with real table schemas from stored datasets\n4. **Schema Inference**: Uses DataFusion's query planner to determine output schema without execution\n5. **Special Fields**: Optionally prepends `SPECIAL_BLOCK_NUM` field for SQL datasets\n6. **Network Extraction**: Identifies which blockchain networks the query references\n\nThe validation works with real registered datasets and their actual schemas,\nensuring datasets exist, tables are valid, and column references are correct.\nThis enables accurate schema introspection for query builders and dataset development tools.\n\n## Request Body\n- `sql_query`: The SQL query to analyze\n- `is_sql_dataset`: (optional) Whether this is a SQL dataset (affects block number field inclusion)\n\n## Response\n- **200 OK**: Returns the schema and networks used by the query\n- **400 Bad Request**: SQL parse error\n- **500 Internal Server Error**: Dataset store or planning error\n\n## Error Codes\n- `SQL_PARSE_ERROR`: Failed to parse the SQL query\n- `DATASET_STORE_ERROR`: Failed to load datasets from store\n- `PLANNING_ERROR`: Failed to determine output schema",
        "operationId": "schema_analyze",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutputSchemaRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successfully analyzed SQL query and returned schema",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutputSchemaResponse"
                }
              }
            }
          },
          "400": {
            "description": "SQL parse error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Dataset store or planning error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/workers": {
      "get": {
        "tags": [
          "workers"
        ],
        "summary": "Handler for the `GET /workers` endpoint",
        "description": "Retrieves and returns a list of all workers from the metadata database.\n\n## Response\n- **200 OK**: Returns all workers with their information\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `METADATA_DB_LIST_ERROR`: Failed to retrieve workers list from database\n\nThis handler:\n- Fetches all workers from the metadata database\n- Converts worker records to API response format with ISO 8601 RFC3339 timestamps\n- Returns a structured response with worker information including node IDs and last heartbeat times",
        "operationId": "workers_list",
        "responses": {
          "200": {
            "description": "Successfully retrieved workers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkersResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/workers/{id}": {
      "get": {
        "tags": [
          "workers"
        ],
        "summary": "Handler for the `GET /workers/{id}` endpoint",
        "description": "Retrieves and returns a specific worker by its node ID from the metadata database.\n\n## Path Parameters\n- `id`: The unique node identifier of the worker to retrieve\n\n## Response\n- **200 OK**: Returns the worker information as JSON with detailed metadata\n- **400 Bad Request**: Invalid node ID format (not parseable as NodeId)\n- **404 Not Found**: Worker with the given node ID does not exist\n- **500 Internal Server Error**: Database connection or query error\n\n## Error Codes\n- `INVALID_WORKER_ID`: The provided ID is not a valid worker node identifier\n- `WORKER_NOT_FOUND`: No worker exists with the given node ID\n- `METADATA_DB_GET_BY_ID_ERROR`: Failed to retrieve worker from database",
        "operationId": "workers_get",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Worker node ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved worker information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkerDetailResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid worker ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Worker not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Dataset": {
        "type": "object",
        "description": "Dataset information\n\nRepresents a dataset tag with its namespace, name, and version.",
        "required": [
          "namespace",
          "name",
          "version"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Dataset name"
          },
          "namespace": {
            "type": "string",
            "description": "Dataset namespace"
          },
          "version": {
            "type": "string",
            "description": "Version tag"
          }
        }
      },
      "DatasetInfo": {
        "type": "object",
        "description": "Detailed dataset information",
        "required": [
          "namespace",
          "name",
          "revision",
          "manifest_hash",
          "kind"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "description": "Dataset kind"
          },
          "manifest_hash": {
            "type": "string",
            "description": "Manifest hash"
          },
          "name": {
            "type": "string",
            "description": "Dataset name"
          },
          "namespace": {
            "type": "string",
            "description": "Dataset namespace"
          },
          "revision": {
            "type": "string",
            "description": "Revision requested"
          }
        }
      },
      "DatasetSummary": {
        "type": "object",
        "description": "Summary information for a single dataset",
        "required": [
          "namespace",
          "name",
          "versions"
        ],
        "properties": {
          "latest_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latest semantic version (if any)"
          },
          "name": {
            "type": "string",
            "description": "Dataset name"
          },
          "namespace": {
            "type": "string",
            "description": "Dataset namespace"
          },
          "versions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All semantic versions (sorted descending)"
          }
        }
      },
      "DatasetsResponse": {
        "type": "object",
        "description": "Response for listing all datasets",
        "required": [
          "datasets"
        ],
        "properties": {
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DatasetSummary"
            },
            "description": "List of all datasets across all namespaces"
          }
        }
      },
      "DeployRequest": {
        "type": "object",
        "description": "Request for deploying a dataset",
        "properties": {
          "end_block": {
            "$ref": "#/components/schemas/EndBlock",
            "description": "The end block configuration for the deployment\n\nSupports multiple modes:\n- `null` or omitted: Continuous dumping (never stops)\n- `\"latest\"`: Stop at the latest available block\n- `<number>`: Stop at specific block number (e.g., `1000000`)\n- `<negative number>`: Stop N blocks before latest (e.g., `-100` means latest - 100)\n\nIf not specified, defaults to continuous mode."
          },
          "parallelism": {
            "type": "integer",
            "format": "int32",
            "description": "Number of parallel workers to run\n\nEach worker will be responsible for an equal number of blocks.\nFor example, if extracting blocks 0-10,000,000 with parallelism=10,\neach worker will handle a contiguous section of 1 million blocks.\n\nOnly applicable to raw datasets (EVM RPC, Firehose, etc.).\nDerived datasets ignore this parameter.\n\nDefaults to 1 if not specified.",
            "minimum": 0
          }
        }
      },
      "DeployResponse": {
        "type": "object",
        "description": "Response for deploy operation",
        "required": [
          "job_id"
        ],
        "properties": {
          "job_id": {
            "type": "integer",
            "format": "int64",
            "description": "The ID of the scheduled dump job (64-bit integer)"
          }
        }
      },
      "EndBlock": {
        "type": [
          "string",
          "null"
        ],
        "description": "End block configuration for API requests.\n\nDetermines when the dump process should stop extracting blocks.\nAccepts the following values:\n\n- `null` (or omitted): Continuous dumping - never stops, keeps extracting new blocks as they arrive\n- `\"latest\"`: Stop at the latest available block at the time the dump starts\n- A positive number as a string (e.g., `\"1000000\"`): Stop at the specified absolute block number\n- A negative number as a string (e.g., `\"-100\"`): Stop at (latest block - N), useful for staying N blocks behind the chain tip"
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response returned by the API\n\nThis struct represents error information returned in HTTP error responses.\nIt provides structured error details including a machine-readable error code\nand human-readable message.\n\n## Error Code Conventions\n- Error codes use SCREAMING_SNAKE_CASE (e.g., `DATASET_NOT_FOUND`)\n- Codes are stable and can be relied upon programmatically\n- Messages may change and should only be used for display/logging\n\n## Example JSON Response\n```json\n{\n  \"error_code\": \"DATASET_NOT_FOUND\",\n  \"error_message\": \"dataset 'eth_mainnet' version '1.0.0' not found\"\n}\n```",
        "required": [
          "error_code",
          "error_message"
        ],
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Machine-readable error code in SCREAMING_SNAKE_CASE format\n\nError codes are stable across API versions and should be used\nfor programmatic error handling. Examples: `INVALID_SELECTOR`,\n`DATASET_NOT_FOUND`, `METADATA_DB_ERROR`"
          },
          "error_message": {
            "type": "string",
            "description": "Human-readable error message\n\nMessages provide detailed context about the error but may change\nover time. Use `error_code` for programmatic decisions."
          }
        }
      },
      "FileInfo": {
        "type": "object",
        "description": "File information returned by the API\n\nThis struct represents file metadata from the database in a format\nsuitable for API responses. It contains all the essential information\nabout Parquet files and their associated metadata within locations.",
        "required": [
          "id",
          "location_id",
          "file_name",
          "url",
          "metadata"
        ],
        "properties": {
          "file_name": {
            "type": "string",
            "description": "Name of the file (e.g., \"blocks_0000000000_0000099999.parquet\")"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Unique identifier for this file (64-bit integer)"
          },
          "location_id": {
            "type": "integer",
            "format": "int64",
            "description": "Location ID this file belongs to (64-bit integer)"
          },
          "metadata": {
            "description": "Parquet file metadata as JSON containing schema and statistics"
          },
          "object_e_tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "ETag of the file object for caching and version identification"
          },
          "object_size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Size of the file object in bytes"
          },
          "object_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "Version identifier of the file object in the storage system"
          },
          "url": {
            "type": "string",
            "description": "Base location URL (e.g., \"s3://bucket/path/\") - combine with file_name for full file URL"
          }
        }
      },
      "FileListInfo": {
        "type": "object",
        "description": "Minimal file information for location file listings\n\nThis struct represents essential file metadata for list endpoints,\ncontaining only the most relevant information needed for file browsing\nwithin a location context.",
        "required": [
          "id",
          "file_name"
        ],
        "properties": {
          "file_name": {
            "type": "string",
            "description": "Name of the file (e.g., \"blocks_0000000000_0000099999.parquet\")"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Unique identifier for this file (64-bit integer)"
          },
          "object_size": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Size of the file object in bytes"
          }
        }
      },
      "JobInfo": {
        "type": "object",
        "description": "Job information returned by the API\n\nThis struct represents job metadata in a format suitable for API responses.\nIt contains essential information about a job without exposing internal\ndatabase implementation details.",
        "required": [
          "id",
          "node_id",
          "status",
          "descriptor"
        ],
        "properties": {
          "descriptor": {
            "description": "Job descriptor containing job-specific parameters as JSON"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Unique identifier for this job (64-bit integer)"
          },
          "node_id": {
            "type": "string",
            "description": "ID of the worker node this job is scheduled for"
          },
          "status": {
            "type": "string",
            "description": "Current status of the job (Scheduled, Running, Completed, Stopped, Failed, etc.)"
          }
        }
      },
      "JobsResponse": {
        "type": "object",
        "description": "API response containing job information",
        "required": [
          "jobs"
        ],
        "properties": {
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/JobInfo"
            },
            "description": "List of jobs"
          },
          "next_cursor": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Cursor for the next page of results (None if no more results)"
          }
        }
      },
      "LocationFilesResponse": {
        "type": "object",
        "description": "Collection response for location file listings\n\nThis response structure provides paginated file data with\ncursor-based pagination support for efficient traversal.",
        "required": [
          "files"
        ],
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileListInfo"
            },
            "description": "List of files in this page with minimal information"
          },
          "next_cursor": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Cursor for the next page of results - use as last_file_id in next request (None if no more results)"
          }
        }
      },
      "LocationInfo": {
        "type": "object",
        "description": "Location information returned by the API\n\nThis struct represents location metadata from the database in a format\nsuitable for API responses. It contains all the essential information\nabout where dataset table data is stored.",
        "required": [
          "id",
          "dataset",
          "dataset_version",
          "table",
          "url",
          "active"
        ],
        "properties": {
          "active": {
            "type": "boolean",
            "description": "Whether this location is currently active for queries"
          },
          "dataset": {
            "type": "string",
            "description": "Name of the dataset this location belongs to"
          },
          "dataset_version": {
            "type": "string",
            "description": "Version of the dataset using semantic versioning (e.g., \"1.0.0\", or empty string for unversioned)"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Unique identifier for this location (64-bit integer)"
          },
          "table": {
            "type": "string",
            "description": "Name of the table within the dataset (e.g., \"blocks\", \"transactions\")"
          },
          "url": {
            "type": "string",
            "description": "Full URL to the storage location (e.g., \"s3://bucket/path/table.parquet\", \"file:///local/path/table.parquet\")"
          },
          "writer": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Writer job ID (64-bit integer, if one exists)"
          }
        }
      },
      "LocationInfoWithDetails": {
        "type": "object",
        "description": "Location information with writer job details",
        "required": [
          "id",
          "dataset",
          "dataset_version",
          "table",
          "url",
          "active"
        ],
        "properties": {
          "active": {
            "type": "boolean",
            "description": "Whether this location is currently active for queries"
          },
          "dataset": {
            "type": "string",
            "description": "Name of the dataset this location belongs to"
          },
          "dataset_version": {
            "type": "string",
            "description": "Version of the dataset using semantic versioning (e.g., \"1.0.0\", or empty string for unversioned)"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Unique identifier for this location (64-bit integer)"
          },
          "table": {
            "type": "string",
            "description": "Name of the table within the dataset (e.g., \"blocks\", \"transactions\")"
          },
          "url": {
            "type": "string",
            "description": "Full URL to the storage location (e.g., \"s3://bucket/path/table.parquet\", \"file:///local/path/table.parquet\")"
          },
          "writer": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/JobInfo",
                "description": "Writer job information with full details (if one exists)"
              }
            ]
          }
        }
      },
      "LocationsResponse": {
        "type": "object",
        "description": "API response containing location information\n\nThis response structure provides paginated location data with\ncursor-based pagination support for efficient traversal.",
        "required": [
          "locations"
        ],
        "properties": {
          "locations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LocationInfo"
            },
            "description": "List of locations in this page"
          },
          "next_cursor": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Cursor for the next page of results (None if no more results)"
          }
        }
      },
      "ManifestDatasetsResponse": {
        "type": "object",
        "description": "Response for listing datasets using a manifest",
        "required": [
          "hash",
          "datasets"
        ],
        "properties": {
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dataset"
            },
            "description": "List of datasets using this manifest"
          },
          "hash": {
            "type": "string",
            "description": "Manifest hash"
          }
        }
      },
      "ManifestResponse": {
        "type": "object",
        "description": "Response wrapper for manifest content"
      },
      "OutputSchemaRequest": {
        "type": "object",
        "description": "Request payload for output schema analysis\n\nContains the SQL query to analyze and optional configuration flags.",
        "required": [
          "sql_query"
        ],
        "properties": {
          "is_sql_dataset": {
            "type": "boolean",
            "description": "Whether this is a SQL dataset (affects block number field inclusion)\n\nWhen true, a special block number field is prepended to the schema.\nThis field tracks the block number for each row in SQL datasets."
          },
          "sql_query": {
            "type": "string",
            "description": "The SQL query to analyze for output schema determination"
          }
        }
      },
      "OutputSchemaResponse": {
        "type": "object",
        "description": "Response returned by the output schema endpoint\n\nContains the determined schema and list of networks referenced by the query.",
        "required": [
          "schema",
          "networks"
        ],
        "properties": {
          "networks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of networks referenced by the query\n\nContains the network names of all datasets/tables referenced\nin the SQL query (e.g., \"mainnet\", \"polygon\", etc.)."
          },
          "schema": {
            "description": "The output schema for the SQL query\n\nDescribes the structure and types of columns that will be returned\nwhen executing the provided SQL query against the dataset."
          }
        }
      },
      "ProviderInfo": {
        "type": "object",
        "description": "Provider information used for both API requests and responses\n\nThis struct represents provider metadata and configuration in a format\nsuitable for both creating providers (POST requests) and retrieving them\n(GET responses). It includes the complete provider configuration.\n\n## Security Note\n\nThe `rest` field contains the full provider configuration. Ensure that\nsensitive information like API keys and tokens are not stored in the\nprovider configuration if this data will be exposed through APIs.",
        "required": [
          "name",
          "kind",
          "network"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "description": "The type of provider (e.g., \"evm-rpc\", \"firehose\")"
          },
          "name": {
            "type": "string",
            "description": "The name/identifier of the provider"
          },
          "network": {
            "type": "string",
            "description": "The blockchain network (e.g., \"mainnet\", \"goerli\", \"polygon\")"
          }
        },
        "additionalProperties": {
          "description": "Additional provider-specific configuration fields"
        }
      },
      "ProvidersResponse": {
        "type": "object",
        "description": "API response containing complete provider information\n\nThis response structure provides all provider configurations\navailable in the system, including their full configuration details.",
        "required": [
          "providers"
        ],
        "properties": {
          "providers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProviderInfo"
            },
            "description": "List of all provider configurations with complete configuration details"
          }
        }
      },
      "PruneResponse": {
        "type": "object",
        "description": "Response payload for manifest pruning operation\n\nContains the count of successfully deleted orphaned manifests.",
        "required": [
          "deleted_count"
        ],
        "properties": {
          "deleted_count": {
            "type": "integer",
            "description": "Number of orphaned manifests successfully deleted",
            "minimum": 0
          }
        }
      },
      "RegisterManifestResponse": {
        "type": "object",
        "description": "Response payload for manifest registration\n\nContains the computed hash of the registered manifest.",
        "required": [
          "hash"
        ],
        "properties": {
          "hash": {
            "type": "string",
            "description": "The computed content hash of the manifest (used as unique identifier)"
          }
        }
      },
      "RegisterRequest": {
        "type": "object",
        "description": "Request payload for dataset registration\n\nContains the dataset namespace, name, version, and manifest.\nThe manifest will be registered (or validated if hash provided), linked to the dataset,\nand optionally tagged with a semantic version.",
        "required": [
          "namespace",
          "name",
          "manifest"
        ],
        "properties": {
          "manifest": {
            "oneOf": [
              {
                "type": "string",
                "description": "A manifest hash (64-character SHA-256 hex string)",
                "maxLength": 64,
                "minLength": 64,
                "pattern": "[0-9a-fA-F]{64}"
              },
              {
                "type": "object",
                "description": "Full manifest JSON content"
              }
            ],
            "description": "Either a manifest hash (64-char hex string) or full manifest JSON content"
          },
          "name": {
            "type": "string",
            "description": "Name of the dataset to be registered (validated identifier format)"
          },
          "namespace": {
            "type": "string",
            "description": "Namespace for the dataset (validated identifier format)"
          },
          "version": {
            "type": "string",
            "description": "Optional version of the dataset to register using semantic versioning (e.g., \"1.0.0\").\n\nIf omitted, only the manifest linking and \"dev\" tag update are performed.\nIf provided, the manifest is also tagged with this semantic version, and \"latest\" tag is\nupdated if this version is higher than the current latest."
          }
        }
      },
      "SpecialTags": {
        "type": "object",
        "description": "Special tags pointing to versions or hashes",
        "properties": {
          "dev": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dev tag pointing to manifest hash (if any)"
          },
          "latest": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latest semantic version (if any)"
          }
        }
      },
      "String": {
        "type": "string",
        "description": "Status filter options for job deletion",
        "enum": [
          "Terminal",
          "Completed",
          "Stopped",
          "Error"
        ]
      },
      "Value": {},
      "VersionInfo": {
        "type": "object",
        "description": "Version information",
        "required": [
          "version",
          "manifest_hash",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "created_at": {
            "type": "string",
            "description": "When this version was created"
          },
          "manifest_hash": {
            "type": "string",
            "description": "Manifest hash for this version"
          },
          "updated_at": {
            "type": "string",
            "description": "When this version was last updated"
          },
          "version": {
            "type": "string",
            "description": "Semantic version"
          }
        }
      },
      "VersionsResponse": {
        "type": "object",
        "description": "Response for listing dataset versions",
        "required": [
          "namespace",
          "name",
          "versions",
          "special_tags"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Dataset name"
          },
          "namespace": {
            "type": "string",
            "description": "Dataset namespace"
          },
          "special_tags": {
            "$ref": "#/components/schemas/SpecialTags",
            "description": "Special tags (latest and dev)"
          },
          "versions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VersionInfo"
            },
            "description": "List of semantic versions (sorted descending)"
          }
        }
      },
      "WorkerDetailResponse": {
        "type": "object",
        "description": "Detailed worker information returned by the API\n\nContains comprehensive information about a worker node including its identity,\nlifecycle timestamps, and build metadata. This response enables monitoring of\nworker health, version tracking, and operational status.",
        "required": [
          "node_id",
          "info",
          "created_at",
          "registered_at",
          "heartbeat_at"
        ],
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the worker was first created in the system (RFC3339 format)\n\nThe initial registration time of this worker. This timestamp never changes\nand represents when the worker first appeared in the system.",
            "examples": [
              "2025-01-15T14:30:00.123456Z"
            ]
          },
          "heartbeat_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last heartbeat timestamp (RFC3339 format)\n\nThe most recent time this worker sent a heartbeat signal. Workers send\nperiodic heartbeats to indicate they are alive and processing work.\nA stale heartbeat indicates the worker may be down or unreachable.",
            "examples": [
              "2025-01-15T17:20:15.456789Z"
            ]
          },
          "info": {
            "$ref": "#/components/schemas/WorkerMetadata",
            "description": "Worker metadata including version and build information\n\nContains detailed build and version information for this worker,\nincluding git version, commit details, and build timestamps."
          },
          "node_id": {
            "type": "string",
            "description": "Unique identifier for the worker node\n\nA persistent identifier that uniquely identifies this worker across registrations\nand heartbeats. Used for tracking and managing individual worker instances.\n\nMust start with a letter and contain only alphanumeric characters, underscores,\nhyphens, and dots.",
            "examples": [
              "worker-01h2xcejqtf2nbrexx3vqjhp41",
              "indexer-node-1",
              "amp_worker.prod"
            ],
            "pattern": "^[a-zA-Z][a-zA-Z0-9_\\-\\.]*$"
          },
          "registered_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the worker last registered (RFC3339 format)\n\nUpdated each time a worker re-registers with the system. Workers typically\nre-register on startup or reconnection. Use this to track worker restarts.",
            "examples": [
              "2025-01-15T16:45:30.789012Z"
            ]
          }
        }
      },
      "WorkerInfo": {
        "type": "object",
        "description": "Worker information returned by the API\n\nContains basic identification and liveness information for a worker node.\nThis is a lightweight summary view suitable for list endpoints.",
        "required": [
          "node_id",
          "heartbeat_at"
        ],
        "properties": {
          "heartbeat_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last heartbeat timestamp (RFC3339 format)\n\nThe most recent time this worker sent a heartbeat signal. Workers send\nperiodic heartbeats to indicate they are alive and processing work.\nA stale heartbeat indicates the worker may be down or unreachable.",
            "examples": [
              "2025-01-15T17:20:15.456789Z"
            ]
          },
          "node_id": {
            "type": "string",
            "description": "Unique identifier for the worker node\n\nA persistent identifier that uniquely identifies this worker across registrations\nand heartbeats. Used for tracking and managing individual worker instances.\n\nMust start with a letter and contain only alphanumeric characters, underscores,\nhyphens, and dots.",
            "examples": [
              "worker-01h2xcejqtf2nbrexx3vqjhp41",
              "indexer-node-1",
              "amp_worker.prod"
            ],
            "pattern": "^[a-zA-Z][a-zA-Z0-9_\\-\\.]*$"
          }
        }
      },
      "WorkerMetadata": {
        "type": "object",
        "description": "Worker metadata containing build and version information\n\nThis struct captures comprehensive build and version details for a worker node,\nenabling tracking of deployed versions and troubleshooting version-specific issues.",
        "required": [
          "version",
          "commit_sha",
          "commit_timestamp",
          "build_date"
        ],
        "properties": {
          "build_date": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time when the worker binary was built (RFC3339 format)\n\nThe timestamp when the build process completed. May differ from commit\ntimestamp, especially for CI/CD builds or local development builds.\n\nReturns \"unknown\" if build date is not available.",
            "examples": [
              "2025-01-15T15:45:30Z",
              "2025-01-15T10:45:30-05:00",
              "unknown"
            ]
          },
          "commit_sha": {
            "type": "string",
            "description": "Full Git commit SHA (40-character hexadecimal)\n\nThe complete SHA-1 hash of the commit from which this worker was built.\nUsed for precise version identification and source code correlation.\n\nReturns \"unknown\" if commit information is not available.",
            "examples": [
              "8b065bde9c1a2f3e4d5c6b7a8e9f0a1b2c3d4e5f",
              "unknown"
            ]
          },
          "commit_timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the commit was created (RFC3339 format)\n\nThe date and time when the source code commit was made to the repository.\nHelps correlate worker versions with development timeline.\n\nReturns \"unknown\" if timestamp is not available.",
            "examples": [
              "2025-01-15T14:30:00Z",
              "2025-01-15T09:30:00-05:00",
              "unknown"
            ]
          },
          "version": {
            "type": "string",
            "description": "Version string including git describe output\n\nFormat: `v{major}.{minor}.{patch}[-{commits_since_tag}-g{short_sha}][-dirty]`\n\nThe \"-dirty\" suffix indicates uncommitted changes in the working directory.\nReturns \"unknown\" if version information is not available.",
            "examples": [
              "v0.0.22",
              "v0.0.22-dirty",
              "v0.0.22-15-g8b065bde",
              "v0.0.22-15-g8b065bde-dirty",
              "unknown"
            ]
          }
        }
      },
      "WorkersResponse": {
        "type": "object",
        "description": "Collection response for worker listings\n\nContains a list of all registered workers in the system with their\nbasic information including node identifiers and last heartbeat times.",
        "required": [
          "workers"
        ],
        "properties": {
          "workers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkerInfo"
            },
            "description": "List of all registered workers\n\nEach worker entry contains the node ID and last heartbeat timestamp.\nWorkers are ordered by their database insertion order."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "datasets",
      "description": "Dataset management endpoints"
    },
    {
      "name": "jobs",
      "description": "Job management endpoints"
    },
    {
      "name": "locations",
      "description": "Location management endpoints"
    },
    {
      "name": "manifests",
      "description": "Manifest management endpoints"
    },
    {
      "name": "providers",
      "description": "Provider management endpoints"
    },
    {
      "name": "files",
      "description": "File access endpoints"
    },
    {
      "name": "schema",
      "description": "Schema generation endpoints"
    },
    {
      "name": "workers",
      "description": "Worker management endpoints"
    }
  ]
}