{
  "openapi": "3.1.0",
  "info": {
    "title": "SpatialData-DB catalog",
    "version": "catalog-2026-11-01",
    "description": "Read-only routes to the SpatialData-DB catalog (8,471 spatial omics datasets, release catalog-2026-11-01). The guide with SQL examples is /llms.txt. Every route is a static file, so there are no query parameters: query the Parquet files with DuckDB, e.g. SELECT technology, count(*) FROM read_parquet('https://github.com/theislab/spatialdata-db-client/releases/download/catalog-2026-11-01/catalog.parquet') GROUP BY 1.",
    "license": {
      "name": "CC BY 4.0 for the catalog metadata; each dataset keeps its own licence (column license)",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "This website."
    }
  ],
  "security": [],
  "paths": {
    "/llms.txt": {
      "get": {
        "summary": "The short guide for agents: what this is, how to query, columns, how to load and cite.",
        "responses": {
          "200": {
            "description": "The guide.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "llms_txt"
      }
    },
    "/llms-full.txt": {
      "get": {
        "summary": "The full guide: every column and more queries.",
        "responses": {
          "200": {
            "description": "The full guide.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "llms_full_txt"
      }
    },
    "/index.md": {
      "get": {
        "summary": "The front page as Markdown (the same text as /llms.txt).",
        "responses": {
          "200": {
            "description": "Markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "index_md"
      }
    },
    "/datasets/md/{shard}.md": {
      "get": {
        "summary": "Datasets as Markdown, about 33 per file. A dataset's shard is the first 2 hex digits of sha1(slug); each section is anchored by the slug, and each dataset page links its section in its head.",
        "parameters": [
          {
            "name": "shard",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One shard of dataset sections.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "datasets_md_shard_md"
      }
    },
    "/collections/md/{shard}.md": {
      "get": {
        "summary": "Collections as Markdown. A collection's shard is the first hex digit of sha1(slug).",
        "parameters": [
          {
            "name": "shard",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One shard of collection sections.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "collections_md_shard_md"
      }
    },
    "/datasets/{slug}": {
      "get": {
        "summary": "A dataset's web page (HTML); the site redirects to /datasets/{slug}/.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "datasets_slug"
      }
    },
    "/catalog.parquet": {
      "servers": [
        {
          "url": "https://github.com/theislab/spatialdata-db-client/releases/download/{release}",
          "description": "A catalog release on GitHub. Query the Parquet files with DuckDB over HTTPS.",
          "variables": {
            "release": {
              "default": "catalog-2026-11-01",
              "description": "A catalog release tag, catalog-YYYY-MM-DD."
            }
          }
        }
      ],
      "get": {
        "summary": "One row per dataset, with every catalog column (see /llms-full.txt).",
        "responses": {
          "200": {
            "description": "The file (GitHub redirects to its storage).",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "catalog_parquet"
      }
    },
    "/collections.parquet": {
      "servers": [
        {
          "url": "https://github.com/theislab/spatialdata-db-client/releases/download/{release}",
          "description": "A catalog release on GitHub. Query the Parquet files with DuckDB over HTTPS.",
          "variables": {
            "release": {
              "default": "catalog-2026-11-01",
              "description": "A catalog release tag, catalog-YYYY-MM-DD."
            }
          }
        }
      ],
      "get": {
        "summary": "One row per collection.",
        "responses": {
          "200": {
            "description": "The file (GitHub redirects to its storage).",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "collections_parquet"
      }
    },
    "/citations.bib": {
      "servers": [
        {
          "url": "https://github.com/theislab/spatialdata-db-client/releases/download/{release}",
          "description": "A catalog release on GitHub. Query the Parquet files with DuckDB over HTTPS.",
          "variables": {
            "release": {
              "default": "catalog-2026-11-01",
              "description": "A catalog release tag, catalog-YYYY-MM-DD."
            }
          }
        }
      ],
      "get": {
        "summary": "BibTeX entries keyed by study_id.",
        "responses": {
          "200": {
            "description": "The file (GitHub redirects to its storage).",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "citations_bib"
      }
    },
    "/gene_index.parquet": {
      "servers": [
        {
          "url": "https://github.com/theislab/spatialdata-db-client/releases/download/{release}",
          "description": "A catalog release on GitHub. Query the Parquet files with DuckDB over HTTPS.",
          "variables": {
            "release": {
              "default": "catalog-2026-11-01",
              "description": "A catalog release tag, catalog-YYYY-MM-DD."
            }
          }
        }
      ],
      "get": {
        "summary": "One row per gene and dataset (about 1 GB). It is not sorted by gene, so a gene filter reads the whole file; the gene-sorted table comes with the HF dataset.",
        "responses": {
          "200": {
            "description": "The file (GitHub redirects to its storage).",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "No such file, shard or release."
          }
        },
        "operationId": "gene_index_parquet"
      }
    }
  }
}