{"openapi":"3.0.0","info":{"title":"RealUFO Public API","version":"1.0.0","description":"Read-only API over realufo.org — the declassified UAP archive (war.gov, AARO, NARA, NASA, DoD FOIA and more). Keyless, CORS-open, rate-limited (600 req/60s per IP). Mirrored official-source fields match the sources exactly; AI summaries and TL;DRs are site-generated. Please attribute realufo.org.","contact":{"url":"https://realufo.org/developers"}},"servers":[{"url":"https://realufo.org/api/v1"}],"paths":{"/records":{"get":{"summary":"Search and filter records","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Full-text search (FTS5 + metadata)"},{"name":"archive","in":"query","schema":{"type":"string"},"description":"e.g. wargov, aaro, nara, nasa"},{"name":"type","in":"query","schema":{"type":"string"},"description":"pdf | video | image | shorts | audio"},{"name":"agency","in":"query","schema":{"type":"string"}},{"name":"location","in":"query","schema":{"type":"string"}},{"name":"year","in":"query","schema":{"type":"string"},"description":"e.g. 1947"},{"name":"decade","in":"query","schema":{"type":"string"},"description":"e.g. 1940"},{"name":"release","in":"query","schema":{"type":"string"},"description":"war.gov release number"},{"name":"sort","in":"query","schema":{"type":"string","enum":["new","az","release","old","recent","random"]},"description":"random: shuffled, never cached"},{"name":"has","in":"query","schema":{"type":"string"},"description":"comma list: text, ai, moments, featured"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"archive":{"type":"string"},"agency":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"kind":{"type":"string"},"redacted":{"type":"integer"},"location":{"type":"string","nullable":true},"incident_date":{"type":"string","nullable":true},"doc_date":{"type":"string","nullable":true},"thumb":{"type":"string","nullable":true},"duration":{"type":"number","nullable":true},"crop":{"type":"string","nullable":true},"oneLiner":{"type":"string","nullable":true}},"required":["id","archive","kind"]}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}}}}}}}}}}},"/records/{id}":{"get":{"summary":"One record, full detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"record not found"}}}},"/records/{id}/text":{"get":{"summary":"OCR full text pages of a record","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"no full text"}}}},"/archives":{"get":{"summary":"Filter facets: releases, kinds, agencies, decades, locations","responses":{"200":{"description":"ok"}}}},"/releases":{"get":{"summary":"war.gov release list","responses":{"200":{"description":"ok"}}}},"/cases":{"get":{"summary":"Case stories (slug + title)","responses":{"200":{"description":"ok"}}}},"/cases/{slug}":{"get":{"summary":"One case story with resolved sources","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"case not found"}}}},"/shorts":{"get":{"summary":"Short clips","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"ok"}}}},"/hubs":{"get":{"summary":"Curated hub list (agency / location / release / decade / topic)","responses":{"200":{"description":"ok"}}}},"/hubs/{kind}/{slug}":{"get":{"summary":"One hub with its records","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"hub not found"}}}},"/usage":{"get":{"summary":"Aggregate API usage (last 30 days, per endpoint)","description":"Privacy-safe liveness signal: day + endpoint + hit counts only. No IPs, user agents or query strings are logged.","responses":{"200":{"description":"ok"}}}},"/webhooks":{"post":{"summary":"Subscribe a URL to archive events","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"https URL receiving POSTs"},"events":{"type":"array","items":{"type":"string","enum":["records.created","release.created"]},"description":"default: both"}}}}}},"responses":{"201":{"description":"created — the secret is shown once","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string"}}}}}}}}}}},"/webhooks/{id}":{"get":{"summary":"Subscription status (X-Webhook-Secret header)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Webhook-Secret","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"not found or wrong secret"}}},"delete":{"summary":"Delete a subscription (X-Webhook-Secret header)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Webhook-Secret","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deleted"},"404":{"description":"not found or wrong secret"}}}}}}