{"openapi":"3.1.0","info":{"title":"Kent Nimmo Public Research API","version":"0.2.0","description":"Public catalogue, source metadata and budgeted Research AI discussion. Catalogue reads require no sign-in or model call. Full originals remain external. Research AI shares atomic daily, visitor, agent and IP spending limits; see /api/research-capacity for availability. Owner financial controls remain authenticated."},"servers":[{"url":"https://kentnimmo.com","description":"Canonical public website"}],"paths":{"/api/v1/manifest":{"get":{"operationId":"getManifest","summary":"List actually supported interfaces and current public snapshot","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["service","source_snapshot_id","capabilities"],"properties":{"service":{"type":"string"},"source_snapshot_id":{"type":"string"},"capabilities":{"type":"array","items":{"type":"object","required":["name","status"],"properties":{"name":{"type":"string"},"status":{"enum":["available","disabled","private-test-only"]},"url":{"type":["string","null"],"format":"uri"},"protocol_version":{"type":["string","null"]},"verified_at":{"type":["string","null"],"format":"date-time"}}}}}}}}}}}},"/api/v1/works":{"get":{"operationId":"searchWorks","summary":"Search approved public works without a model call","security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":300}},{"name":"programme","in":"query","schema":{"type":"string","enum":["bridge-theory","quantum-foundations","astronomy-cosmology","mathematics","philosophy"]}},{"name":"type","in":"query","schema":{"enum":["research-paper","research-record","preregistration","dataset","software","article","video","other"]}},{"name":"status","in":"query","schema":{"enum":["unknown","preprint","accepted","journal-published","superseded","withdrawn"]}},{"name":"year","in":"query","schema":{"type":"integer","minimum":1900,"maximum":2200}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"source","in":"query","schema":{"type":"string","enum":["figshare.com","osf.io","philarchive.org","doi.org"]}},{"name":"coverage","in":"query","schema":{"type":"string","enum":["metadata-only","abstract-only","partial-text","full-text","extraction-error"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["year","title"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","source_snapshot_id"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Work"}},"next_cursor":{"type":["string","null"]},"source_snapshot_id":{"type":"string"},"total":{"type":"integer","minimum":0}}}}}},"304":{"description":"If-None-Match matches the current snapshot and query"},"400":{"description":"Invalid filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared rolling catalogue quota; Retry-After gives retry guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Shared quota store unavailable; static paper browsing remains available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/works/{work_id}":{"get":{"operationId":"getWork","security":[],"parameters":[{"name":"work_id","in":"path","required":true,"schema":{"type":"string","maxLength":160}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Work"}}}},"404":{"description":"Work not public or not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared rolling catalogue quota; Retry-After gives retry guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Shared quota store unavailable; static paper browsing remains available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sources/{source_id}":{"get":{"operationId":"getSource","summary":"Return approved source information and permitted text; never proxy an arbitrary URL","security":[],"parameters":[{"name":"source_id","in":"path","required":true,"schema":{"type":"string","maxLength":160}},{"name":"locator","in":"query","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"404":{"description":"Source not public or not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared rolling catalogue quota; Retry-After gives retry guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Shared quota store unavailable; static paper browsing remains available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/query":{"post":{"operationId":"askResearch","summary":"Research discussion through the shared Research AI service, with source navigation available during generation pauses","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchAnswer"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared application quota; Retry-After indicates retry guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation disabled, budget unavailable or provider unavailable","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"fallback":{"$ref":"#/components/schemas/ResearchAnswer"}}}]}}}}},"parameters":[{"name":"X-Research-Session","in":"header","description":"Opaque session identifier, up to 160 letters/digits/underscore/colon/hyphen. Required for anonymous generated questions; metadata lookup needs no session. Never a raw email address.","schema":{"type":"string","maxLength":160}},{"name":"Idempotency-Key","in":"header","description":"Up to 100 characters. Reuse for the same attempted question; already-processed or uncertain attempts are never sent to the provider twice.","schema":{"type":"string","maxLength":100}}]}},"/api/v1/health":{"get":{"operationId":"getHealth","security":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["status","generation"],"properties":{"status":{"enum":["ok","degraded"]},"generation":{"enum":["available","disabled","limited"]}}}}}}}}},"/api/v1/works/{work_id}/citation":{"get":{"operationId":"exportCitation","parameters":[{"name":"work_id","in":"path","required":true,"schema":{"type":"string","maxLength":160}},{"name":"format","in":"query","schema":{"type":"string","enum":["text","bibtex","ris"],"default":"text"}}],"responses":{"200":{"description":"Citation download; only known fields, selected source edition","content":{"text/plain":{"schema":{"type":"string"}},"application/x-bibtex":{"schema":{"type":"string"}},"application/x-research-info-systems":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared rolling catalogue quota; Retry-After gives retry guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Shared quota store unavailable; static paper browsing remains available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/programmes/{programme_id}":{"get":{"operationId":"getProgramme","parameters":[{"name":"programme_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["id","title","route","description","editorial_status","work_ids"]}}}},"404":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared rolling catalogue quota; Retry-After gives retry guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Shared quota store unavailable; static paper browsing remains available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/research-index.json":{"get":{"operationId":"getApprovedIndex","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["schema_version","snapshot_id","generated_on","works"],"properties":{"works":{"type":"array","items":{"$ref":"#/components/schemas/Work"}}}}}}},"429":{"description":"Shared rolling catalogue quota; Retry-After gives retry guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Shared quota store unavailable; static paper browsing remains available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/research-capacity":{"get":{"operationId":"getResearchCapacity","summary":"Read current paid-generation availability without a model call","security":[],"responses":{"200":{"description":"Current availability and source-browsing status","content":{"application/json":{"schema":{"type":"object","required":["paid_generation","source_browsing"],"properties":{"paid_generation":{"type":"string"},"reason":{"type":["string","null"]},"source_browsing":{"type":"string"}}}}}}}}},"/api/research":{"post":{"operationId":"discussResearch","summary":"Contextual research conversation within shared daily and visitor or agent limits","security":[],"parameters":[{"name":"X-Research-Session","in":"header","required":true,"description":"Stable session identifier for this discussion. It does not bypass common IP or daily spending limits.","schema":{"type":"string","pattern":"^[A-Za-z0-9_:-]{1,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["operation","args"],"properties":{"operation":{"const":"ask_research"},"args":{"type":"object","additionalProperties":false,"required":["question"],"properties":{"question":{"type":"string","minLength":1,"maxLength":4000},"work_id":{"type":["string","null"]},"edition_id":{"type":["string","null"]}}},"conversation_context":{"type":"string","maxLength":44000,"description":"Opaque server-signed recent context from the previous reply; never fabricate client history."}}},"example":{"operation":"ask_research","args":{"question":"What is Bridge Theory in plain language?"}}}}},"responses":{"200":{"description":"Generated answer, clarification, source response or budget pause. Preserve the returned conversation_context for follow-ups.","content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string"},"data":{"type":"object"},"conversation_context":{"type":"string"},"error":{"type":["object","null"]}}}}}},"400":{"description":"Invalid operation or arguments"},"403":{"description":"Disallowed browser origin"},"429":{"description":"Request quota reached"},"503":{"description":"Service temporarily unavailable"}}}}},"components":{"schemas":{"Work":{"type":"object","additionalProperties":false,"required":["id","slug","title","authors","programmes","work_type","public_status","status_evidence","editorial_state","visibility","source_coverage","editions","relations","source_ids","provenance","approved_for_public_ai"],"properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]+$"},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"title":{"type":"string","minLength":1},"authors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1},"orcid":{"type":["string","null"],"pattern":"^\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]$"}}},"minItems":1},"programmes":{"type":"array","uniqueItems":true,"items":{"enum":["bridge-theory","quantum-foundations","astronomy-cosmology","mathematics","philosophy"]}},"work_type":{"enum":["research-paper","research-record","preregistration","dataset","software","article","video","other"]},"public_status":{"enum":["unknown","preprint","accepted","journal-published","superseded","withdrawn"]},"status_evidence":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["source_id","observed_on","notes"],"properties":{"source_id":{"type":"string"},"observed_on":{"type":"string","format":"date"},"notes":{"type":"string"}}}},"abstract":{"type":["string","null"]},"summary":{"type":["string","null"]},"year":{"type":["integer","null"],"minimum":1900,"maximum":2200},"editorial_state":{"enum":["draft","staged","approved","superseded","withdrawn"]},"visibility":{"enum":["private","preview","public"]},"source_coverage":{"enum":["metadata-only","abstract-only","full-text","partial-text","extraction-error"]},"editions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","label","kind","record_url","source_ids","coverage"],"properties":{"id":{"type":"string","minLength":1},"label":{"type":"string"},"kind":{"enum":["preprint","accepted-manuscript","version-of-record","supplement","dataset","software","research-record","other"]},"record_url":{"type":"string","format":"uri"},"full_text_url":{"type":["string","null"],"format":"uri"},"doi":{"type":["string","null"]},"version":{"type":["string","null"]},"published_date":{"type":["string","null"],"format":"date"},"license":{"type":["string","null"]},"sha256":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$"},"source_ids":{"type":"array","items":{"type":"string"},"minItems":1},"coverage":{"enum":["metadata-only","abstract-only","full-text","partial-text","extraction-error"]},"notes":{"type":"string"},"registered_date":{"type":["string","null"],"format":"date","description":"Public OSF registration date, kept separate from manuscript publication date."}}}},"relations":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["type","target_id","evidence_note"],"properties":{"type":{"enum":["is-version-of","mirror-of","supplements","has-record","explains","supersedes","extends","related-to","depends-on"]},"target_id":{"type":"string"},"evidence_note":{"type":"string"}}}},"discovery_urls":{"type":"array","items":{"type":"string","format":"uri"}},"source_ids":{"type":"array","minItems":1,"items":{"type":"string"}},"provenance":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["source_id","observed_on","fields","notes"],"properties":{"source_id":{"type":"string"},"observed_on":{"type":"string","format":"date"},"fields":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}}},"approved_for_public_ai":{"type":"boolean"}},"allOf":[{"if":{"properties":{"approved_for_public_ai":{"const":true}},"required":["approved_for_public_ai"]},"then":{"properties":{"visibility":{"const":"public"},"editorial_state":{"const":"approved"}}}},{"if":{"properties":{"public_status":{"enum":["accepted","journal-published"]}},"required":["public_status"]},"then":{"properties":{"status_evidence":{"minItems":1}}}}]},"ResearchAnswer":{"title":"ResearchAnswer","type":"object","additionalProperties":false,"required":["request_id","answer","coverage","citations","relevant_work_ids","navigation","caveats","source_snapshot_id"],"properties":{"request_id":{"type":"string","minLength":1},"answer":{"type":"string","maxLength":30000},"coverage":{"enum":["sufficient","limited","none"]},"source_snapshot_id":{"type":"string","minLength":1},"citations":{"type":"array","maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["citation_id","source_id","title","url","support_type"],"properties":{"citation_id":{"type":"string"},"source_id":{"type":"string"},"work_id":{"type":["string","null"]},"edition_id":{"type":["string","null"]},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"locator":{"type":["string","null"]},"support_type":{"enum":["explicit-source","conditional-result","interpretation","metadata"]},"excerpt":{"type":["string","null"],"maxLength":400}}}},"relevant_work_ids":{"type":"array","maxItems":20,"items":{"type":"string"}},"navigation":{"type":"array","maxItems":8,"items":{"type":"object","additionalProperties":false,"required":["label","path"],"properties":{"label":{"type":"string","maxLength":120},"path":{"type":"string","pattern":"^/(?!/)[A-Za-z0-9/_-]*$"}}}},"caveats":{"type":"array","maxItems":12,"items":{"type":"string","maxLength":1200}}}},"QueryRequest":{"type":"object","additionalProperties":false,"required":["question"],"properties":{"question":{"type":"string","minLength":3,"maxLength":3000},"scope":{"type":"string","enum":["research","ar-background"],"default":"research"},"work_ids":{"type":"array","maxItems":8,"uniqueItems":true,"items":{"type":"string"}},"detail":{"type":"string","enum":["brief","standard","technical"],"default":"standard"},"history":{"type":"array","maxItems":4,"default":[],"description":"Optional session-local conversation context; treated as untrusted data, never stored by the application.","items":{"type":"object","additionalProperties":false,"required":["question","answer"],"properties":{"question":{"type":"string","maxLength":3000},"answer":{"type":"string","maxLength":4000}}}}}},"Error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"retry_after_seconds":{"type":"integer","minimum":0}}},"Source":{"type":"object","required":["source_id","title","url","coverage","text_available"],"properties":{"source_id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"coverage":{"type":"string","enum":["metadata-only","abstract-only","full-text","partial-text","extraction-error"]},"text_available":{"type":"boolean"},"text":{"type":["string","null"],"maxLength":60000},"locator":{"type":["string","null"]},"truncated":{"type":"boolean"},"license":{"type":["string","null"]},"pages":{"type":"array","maxItems":3,"items":{"type":"object","required":["locator","text"],"properties":{"locator":{"type":"string"},"text":{"type":"string"}}}},"available_locators":{"type":"array","items":{"type":"string"}}},"description":"At most the first three pages are returned by default; request a known locator for another page. Top-level text belongs to its stated locator and is omitted when another page is selected. Verified author abstracts have real PDF page locators; remaining mathematical text is partial extraction. No arbitrary source fetching."}}},"security":[],"x-rate-limits":{"catalogue":{"requests":60,"rolling_window_seconds":60,"shared_across":["REST","MCP HTTP messages","A2A","web query","approved index"],"identity":"Cloudflare connection IP; a shared conservative bucket when absent","on_store_failure":"503; static library pages remain available"},"generation":{"note":"Shared daily credit allowance and separate visitor/agent limits; no bypass through REST, MCP or A2A."}},"x-verification":{"scope":"Public catalogue and discovery; current runtime state is available from /api/v1/manifest and /api/research-capacity.","content":"Only approved public records and bounded source selections; full originals external."}}