{
  "citation": "Specimen Registry v0.0.7 (2026). Maintained by Michael Gonzalez with AI assistance. https://specimenregistry.org. Data licensed under CC BY 4.0.",
  "license": "https://specimenregistry.org/license",
  "openapi": "3.1.0",
  "info": {
    "title": "Specimen Registry (SAR) API",
    "version": "0.0.12-neon",
    "description": "Public read-only registry of archaic hominin (and select ancient modern human) specimens, publications, sites, analyses, and cross-specimen comparisons. Every row carries a verification_state (draft | pending-verification | source-locked) and every material claim is source-quoted verbatim from primary literature. Data licensed under CC BY 4.0.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/legalcode"
    },
    "contact": {
      "name": "Michael Gonzalez",
      "url": "https://specimenregistry.org/license"
    }
  },
  "servers": [
    {
      "url": "https://specimenregistry.org"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Liveness probe",
        "responses": {
          "200": {
            "description": "ok"
          }
        }
      }
    },
    "/version": {
      "get": {
        "summary": "Service version and capability set",
        "responses": {
          "200": {
            "description": "version JSON"
          }
        }
      }
    },
    "/license": {
      "get": {
        "summary": "CC BY 4.0 attribution disclosure",
        "responses": {
          "200": {
            "description": "license JSON or HTML"
          }
        }
      }
    },
    "/stats": {
      "get": {
        "summary": "Corpus rollups: totals + specimens by state/site + pubs by year",
        "responses": {
          "200": {
            "description": "stats JSON"
          }
        }
      }
    },
    "/timeline": {
      "get": {
        "summary": "Specimens with their earliest describing publication, ordered by publication year",
        "responses": {
          "200": {
            "description": "timeline JSON"
          }
        }
      }
    },
    "/random": {
      "get": {
        "summary": "Random specimen. HTML mode 302-redirects to /specimens/:id; JSON mode returns the specimen row.",
        "responses": {
          "200": {
            "description": "random specimen JSON"
          },
          "302": {
            "description": "redirect to specimen detail"
          }
        }
      }
    },
    "/audit": {
      "get": {
        "summary": "Recent access log entries (last N=20 default, max 100). Only public routes; IPs are one-way hashed.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "audit JSON"
          }
        }
      }
    },
    "/methods": {
      "get": {
        "summary": "Distinct assignment methods (how specimens were taxonomically assigned) and analysis types (techniques applied in individual papers), with counts.",
        "responses": {
          "200": {
            "description": "methods JSON"
          }
        }
      }
    },
    "/related/{id}": {
      "get": {
        "summary": "Neighbor specimens across three relatedness surfaces: shared publication, same site, and specimen_comparisons row.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "related JSON"
          },
          "404": {
            "description": "specimen not found"
          }
        }
      }
    },
    "/export.csv": {
      "get": {
        "summary": "Bulk CSV export. Provide ?table=publications or ?table=specimens (default: specimens).",
        "parameters": [
          {
            "name": "table",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "publications",
                "specimens",
                "analyses",
                "comparisons"
              ],
              "default": "specimens"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV body"
          }
        }
      }
    },
    "/publications": {
      "get": {
        "summary": "List publications (paginated)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "publications JSON"
          }
        }
      }
    },
    "/publications/{doi}": {
      "get": {
        "summary": "Single publication by DOI",
        "parameters": [
          {
            "name": "doi",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "publication JSON or HTML"
          }
        }
      }
    },
    "/specimens": {
      "get": {
        "summary": "List specimens (paginated)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "specimens JSON"
          }
        }
      }
    },
    "/specimens/{id}": {
      "get": {
        "summary": "Single specimen by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "specimen JSON or HTML"
          }
        }
      }
    },
    "/sites": {
      "get": {
        "summary": "List sites",
        "responses": {
          "200": {
            "description": "sites JSON"
          }
        }
      }
    },
    "/sites/{id}": {
      "get": {
        "summary": "Single site by ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "site JSON or HTML"
          }
        }
      }
    },
    "/analyses": {
      "get": {
        "summary": "List analyses (filter by specimen_id or publication_id)",
        "parameters": [
          {
            "name": "specimen_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "publication_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "analyses JSON"
          }
        }
      }
    },
    "/comparisons": {
      "get": {
        "summary": "List cross-specimen comparison rows",
        "parameters": [
          {
            "name": "specimen_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "publication_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "genome-relatedness",
                "sister-lineage",
                "introgression-source",
                "related-population",
                "kin-relationship",
                "contemporaneous"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "comparisons JSON or HTML"
          }
        }
      }
    },
    "/graph/{specimen_id}": {
      "get": {
        "summary": "Provenance chain: specimen → papers → site → related specimens",
        "parameters": [
          {
            "name": "specimen_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "nodes + edges JSON"
          }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Full-text search over publications + specimens",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "publication",
                "specimen",
                "all"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "search JSON or HTML"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VerificationState": {
        "type": "string",
        "enum": [
          "draft",
          "pending-verification",
          "source-locked"
        ],
        "description": "Human-review state on a row. Only source-locked rows are safe to cite; draft/pending-verification await Michael Gonzalez's primary-source sign-off."
      }
    }
  }
}