{"openapi":"3.1.0","info":{"title":"Esheria Global Constitutions API","version":"1.0.0","description":"Rights-aware, release-scoped access to Esheria's immutable global constitution dataset. Availability follows the ordinary legal-corpus dependency and release contract."},"servers":[{"url":"https://chat.esheria.ai"}],"tags":[{"name":"Constitutions"}],"paths":{"/api/constitutions/v1/health":{"get":{"tags":["Constitutions"],"operationId":"constitutionHealth","summary":"Check release, MongoDB, and search readiness","responses":{"200":{"$ref":"#/components/responses/Health"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}}}},"/api/constitutions/v1/countries":{"get":{"tags":["Constitutions"],"operationId":"listConstitutionCountries","summary":"List all 200 constitutional systems","responses":{"200":{"$ref":"#/components/responses/Countries"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}}}},"/api/constitutions/v1/countries/{countryCode}":{"get":{"tags":["Constitutions"],"operationId":"getConstitutionCountry","summary":"Get a constitutional system and its current instruments","parameters":[{"$ref":"#/components/parameters/Country"}],"responses":{"200":{"$ref":"#/components/responses/Country"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}}}},"/api/constitutions/v1/countries/{countryCode}/articles":{"get":{"tags":["Constitutions"],"operationId":"listConstitutionArticles","summary":"List current provisions in natural order","parameters":[{"$ref":"#/components/parameters/Country"},{"$ref":"#/components/parameters/Instrument"},{"$ref":"#/components/parameters/Version"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/ArticleLimit"}],"responses":{"200":{"$ref":"#/components/responses/ArticleList"},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}}}},"/api/constitutions/v1/countries/{countryCode}/articles/{articleNumberOrKey}":{"get":{"tags":["Constitutions"],"operationId":"getConstitutionArticle","summary":"Get a current provision by stable key or unambiguous label","description":"Canonical links use p- or s-prefixed stable keys. A repeated bare label returns HTTP 409 with safe candidates; it never selects an arbitrary provision.","parameters":[{"$ref":"#/components/parameters/Country"},{"name":"articleNumberOrKey","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"$ref":"#/components/parameters/Instrument"},{"$ref":"#/components/parameters/Version"}],"responses":{"200":{"$ref":"#/components/responses/Article"},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}}}},"/api/constitutions/v1/search":{"post":{"tags":["Constitutions"],"operationId":"searchConstitutions","summary":"Search all rights-eligible constitutional provisions","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/Search"},"400":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"413":{"$ref":"#/components/responses/Problem"},"415":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}}}}},"components":{"parameters":{"Country":{"name":"countryCode","in":"path","required":true,"description":"ISO alpha-2 code, stable ISO-based slug, or registered legacy alias","schema":{"type":"string","minLength":2,"maxLength":100}},"Instrument":{"name":"instrumentId","in":"query","schema":{"type":"string","pattern":"^urn:esheria:constitution-instrument:[a-zA-Z]{2}:[0-9a-fA-F]{64}$","maxLength":180}},"Version":{"name":"versionId","in":"query","schema":{"type":"string","pattern":"^urn:esheria:constitution-version:[a-zA-Z]{2}:[0-9a-fA-F]{64}$","maxLength":180}},"Cursor":{"name":"cursor","in":"query","description":"Opaque, signed, release- and filter-bound cursor","schema":{"type":"string","minLength":1,"maxLength":4096}},"ArticleLimit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"schemas":{"ReleaseId":{"type":"string","const":"constitutions-global-20260821-v2"},"Country":{"type":"object","required":["code","slug","name","systemId","systemType","status","freshnessStatus","officialLanguages","instrumentCount","articleCount","releaseId"],"properties":{"code":{"type":"string","pattern":"^[A-Z]{2}$"},"slug":{"type":"string","pattern":"^[a-z]{2}$"},"name":{"type":"string","maxLength":200},"systemId":{"type":"string","maxLength":180},"systemType":{"type":"string","maxLength":100},"status":{"type":"string","maxLength":100},"freshnessStatus":{"type":["string","null"],"maxLength":100},"officialLanguages":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":200}},"instrumentCount":{"type":"integer","minimum":0,"maximum":100},"articleCount":{"type":["integer","null"],"minimum":0},"releaseId":{"$ref":"#/components/schemas/ReleaseId"}}},"Instrument":{"type":"object","additionalProperties":false,"required":["instrumentId","title","citation","role","status","current","versionId","versionDate","language","languageTag","sourceUrl"],"properties":{"instrumentId":{"type":"string","maxLength":180},"title":{"type":"string","maxLength":1000},"citation":{"type":["string","null"],"maxLength":500},"role":{"type":["string","null"],"maxLength":200},"status":{"type":["string","null"],"maxLength":100},"current":{"type":"boolean"},"versionId":{"type":["string","null"],"maxLength":180},"versionDate":{"type":["string","null"],"maxLength":100},"language":{"type":["string","null"],"maxLength":200},"languageTag":{"type":["string","null"],"maxLength":100},"sourceUrl":{"type":["string","null"],"format":"uri","maxLength":4096}}},"ArticleSummary":{"type":"object","required":["articleKey","provisionId","servingDocumentId","countryCode","countrySlug","instrumentId","versionId","instrumentTitle","articleNumber","label","heading","chapter","naturalOrder","language","languageTag","legalStatus","retrievalDate","canonicalPath","restricted"],"properties":{"articleKey":{"type":"string","pattern":"^[ps]-[0-9a-f]{64}$"},"provisionId":{"type":"string","maxLength":180},"servingDocumentId":{"type":"string","pattern":"^constitution-serving:sha256:[0-9a-f]{64}$"},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"countrySlug":{"type":"string","pattern":"^[a-z]{2}$"},"instrumentId":{"type":"string","maxLength":180},"versionId":{"type":"string","maxLength":180},"instrumentTitle":{"type":"string","maxLength":1000},"articleNumber":{"type":["string","null"],"maxLength":128},"label":{"type":"string","maxLength":1000},"heading":{"type":["string","null"],"maxLength":1000},"chapter":{"type":["string","null"],"maxLength":1000},"naturalOrder":{"type":"integer","minimum":0},"language":{"type":["string","null"],"maxLength":200},"languageTag":{"type":["string","null"],"maxLength":100},"legalStatus":{"type":"string","maxLength":100},"retrievalDate":{"type":"string","maxLength":100},"canonicalPath":{"type":"string","pattern":"^/constitutions/[a-z]{2}/[ps]-[0-9a-f]{64}$"},"restricted":{"type":"boolean"}}},"RightsSummary":{"type":"object","additionalProperties":false,"required":["metadata","apiDelivery","fullText","excerpt","publicSearch","modelContext","attributionRequired","policyVersion"],"properties":{"metadata":{"$ref":"#/components/schemas/RightState"},"apiDelivery":{"$ref":"#/components/schemas/RightState"},"fullText":{"$ref":"#/components/schemas/RightState"},"excerpt":{"$ref":"#/components/schemas/RightState"},"publicSearch":{"$ref":"#/components/schemas/RightState"},"modelContext":{"$ref":"#/components/schemas/RightState"},"attributionRequired":{"type":"boolean"},"policyVersion":{"type":["string","null"],"maxLength":128}}},"RightState":{"type":"string","enum":["allowed","allowed_with_attribution","metadata_only","prohibited","unknown"]},"KanonGroup":{"type":"object","additionalProperties":false,"required":["items","returned","total","truncated"],"properties":{"items":{"type":"array","maxItems":20,"items":{"type":"object","maxProperties":11}},"returned":{"type":"integer","minimum":0,"maximum":20},"total":{"type":"integer","minimum":0},"truncated":{"type":"boolean"}}},"Article":{"allOf":[{"$ref":"#/components/schemas/ArticleSummary"},{"type":"object","required":["releaseId","bodyText","restrictionReason","sourceHash","sourceUrl","provenance","rights","kanonStatus","kanon"],"properties":{"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"bodyText":{"type":["string","null"],"maxLength":1048576},"restrictionReason":{"type":["string","null"],"maxLength":500},"sourceHash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"sourceUrl":{"type":"string","format":"uri","maxLength":4096},"provenance":{"type":"object","maxProperties":8,"additionalProperties":{"type":["string","null"],"maxLength":1024}},"rights":{"$ref":"#/components/schemas/RightsSummary"},"kanonStatus":{"type":"string","maxLength":100},"kanon":{"type":"object","additionalProperties":false,"required":["segments","mentions","crossReferences"],"properties":{"segments":{"$ref":"#/components/schemas/KanonGroup"},"mentions":{"$ref":"#/components/schemas/KanonGroup"},"crossReferences":{"$ref":"#/components/schemas/KanonGroup"}}}}}]},"SearchHit":{"allOf":[{"$ref":"#/components/schemas/ArticleSummary"},{"type":"object","required":["releaseId","excerpt","sourceHash","sourceUrl","provenance","hydrationVerified"],"properties":{"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"excerpt":{"type":["string","null"],"maxLength":420},"sourceHash":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"sourceUrl":{"type":"string","format":"uri","maxLength":4096},"provenance":{"type":"object","maxProperties":8,"additionalProperties":{"type":["string","null"],"maxLength":1024}},"hydrationVerified":{"type":"boolean","const":true}}}]},"SearchRequest":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":512},"country":{"type":"string","minLength":2,"maxLength":100},"instrumentId":{"type":"string","pattern":"^urn:esheria:constitution-instrument:[a-zA-Z]{2}:[0-9a-fA-F]{64}$","maxLength":180},"versionId":{"type":"string","pattern":"^urn:esheria:constitution-version:[a-zA-Z]{2}:[0-9a-fA-F]{64}$","maxLength":180},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10},"cursor":{"type":"string","minLength":1,"maxLength":4096}}},"HealthResponse":{"type":"object","additionalProperties":false,"required":["status","ready","expectedReleaseId","activeReleaseId","releaseId","manifestValid","mongoConnected","searchReady","checkedAt","requestId"],"properties":{"status":{"type":"string","const":"ok"},"ready":{"type":"boolean","const":true},"expectedReleaseId":{"$ref":"#/components/schemas/ReleaseId"},"activeReleaseId":{"$ref":"#/components/schemas/ReleaseId"},"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"manifestValid":{"type":"boolean"},"mongoConnected":{"type":"boolean"},"searchReady":{"type":"boolean"},"checkedAt":{"type":"string","format":"date-time"},"requestId":{"type":"string"}}},"CountriesResponse":{"type":"object","additionalProperties":false,"required":["releaseId","total","countries","requestId"],"properties":{"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"total":{"type":"integer","const":200},"countries":{"type":"array","minItems":200,"maxItems":200,"items":{"$ref":"#/components/schemas/Country"}},"requestId":{"type":"string"}}},"CountryResponse":{"type":"object","additionalProperties":false,"required":["releaseId","country","requestId"],"properties":{"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"country":{"allOf":[{"$ref":"#/components/schemas/Country"},{"type":"object","required":["instruments"],"properties":{"instruments":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Instrument"}}}}]},"requestId":{"type":"string"}}},"ArticleListResponse":{"type":"object","additionalProperties":false,"required":["releaseId","country","filters","articles","pagination","requestId"],"properties":{"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"country":{"$ref":"#/components/schemas/Country"},"filters":{"type":"object","additionalProperties":false,"required":["instrumentId","versionId"],"properties":{"instrumentId":{"type":["string","null"]},"versionId":{"type":["string","null"]}}},"articles":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/ArticleSummary"}},"pagination":{"type":"object","additionalProperties":false,"required":["limit","nextCursor","hasMore"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"nextCursor":{"type":["string","null"],"maxLength":4096},"hasMore":{"type":"boolean"}}},"requestId":{"type":"string"}}},"ArticleResponse":{"type":"object","additionalProperties":false,"required":["releaseId","article","requestId"],"properties":{"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"article":{"$ref":"#/components/schemas/Article"},"requestId":{"type":"string"}}},"SearchResponse":{"type":"object","additionalProperties":false,"required":["releaseId","query","filters","hits","total","totalRelation","nextCursor","facets","diagnostics","requestId"],"properties":{"releaseId":{"$ref":"#/components/schemas/ReleaseId"},"query":{"type":"string","maxLength":512},"filters":{"type":"object","additionalProperties":false,"required":["countryCode","instrumentId","versionId"],"properties":{"countryCode":{"type":["string","null"],"pattern":"^[A-Z]{2}$"},"instrumentId":{"type":["string","null"],"maxLength":512},"versionId":{"type":["string","null"],"maxLength":512}}},"hits":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/SearchHit"}},"total":{"type":"integer","minimum":0},"totalRelation":{"type":"string","enum":["eq","gte"]},"nextCursor":{"type":["string","null"],"maxLength":4096},"facets":{"type":"object","additionalProperties":false,"required":["countries","instruments"],"properties":{"countries":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/Facet"}},"instruments":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Facet"}}}},"diagnostics":{"type":"object","additionalProperties":false,"required":["hydrated","rejected"],"properties":{"hydrated":{"type":"integer","minimum":0,"maximum":50},"rejected":{"type":"integer","minimum":0,"maximum":50}}},"requestId":{"type":"string"}}},"Facet":{"type":"object","additionalProperties":false,"required":["value","count"],"properties":{"value":{"type":"string","maxLength":512},"count":{"type":"integer","minimum":0}}},"Problem":{"type":"object","additionalProperties":false,"required":["type","title","status","code","requestId","retryable"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"}}}},"responses":{"Health":{"description":"Safe service readiness state","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"Countries":{"description":"All release-scoped constitutional systems","headers":{"ETag":{"$ref":"#/components/headers/ETag"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Esheria-Release-Id":{"$ref":"#/components/headers/ReleaseId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"}}}},"Country":{"description":"One system and its current instruments","headers":{"ETag":{"$ref":"#/components/headers/ETag"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Esheria-Release-Id":{"$ref":"#/components/headers/ReleaseId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryResponse"}}}},"ArticleList":{"description":"One natural-order keyset page","headers":{"ETag":{"$ref":"#/components/headers/ETag"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Esheria-Release-Id":{"$ref":"#/components/headers/ReleaseId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleListResponse"}}}},"Article":{"description":"One rights-aware provision","headers":{"ETag":{"$ref":"#/components/headers/ETag"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Esheria-Release-Id":{"$ref":"#/components/headers/ReleaseId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleResponse"}}}},"Search":{"description":"Hydrated and rights-revalidated search results","headers":{"ETag":{"$ref":"#/components/headers/ETag"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Esheria-Release-Id":{"$ref":"#/components/headers/ReleaseId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"Problem":{"description":"Problem Details response without infrastructure detail","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"headers":{"ETag":{"schema":{"type":"string"}},"RequestId":{"schema":{"type":"string"}},"ReleaseId":{"schema":{"$ref":"#/components/schemas/ReleaseId"}}}}}