{"openapi":"3.1.0","info":{"title":"CASRAI v1 API","version":"1.0.0","summary":"Programmatic access to the CASRAI Dictionary, the CRediT vocabulary, and a per-user contribution claim endpoint that writes through to ORCID.","description":"The CASRAI v1 HTTP API provides read access to the CASRAI Dictionary (operational definitions, domains, examples, relationships) and the canonical 14-role CRediT taxonomy (ANSI/NISO Z39.104-2022; see https://schema.org/Role and the NISO URI pattern https://casrai.org/credit/roles/{slug}). It also exposes a `write`-scoped endpoint that pushes contribution claims into the caller's ORCID record using a server-side Member API token, so applications never need to hold an ORCID token themselves.\n\nAuthentication is HTTP Bearer with a CASRAI plaintext key of the form `casrai_pk_<32-hex>` issued from /account/api-keys. Keys have either `read` or `write` scope; the only write endpoint is `POST /contributions`.\n\nA single rate limit of 60 requests per minute per key applies across all endpoints (sliding 60-second window). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; 429 responses also carry `Retry-After`. All payloads are JSON; the dictionary, CRediT vocabulary, and API responses themselves are licensed CC-BY-4.0.","termsOfService":"https://casrai.org/legal/terms","contact":{"name":"CASRAI editorial","email":"editorial@casrai.org","url":"https://casrai.org/contact/editorial"},"license":{"name":"CC-BY-4.0","identifier":"CC-BY-4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://casrai.org/api/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Meta","description":"Discovery and identity endpoints."},{"name":"CRediT","description":"ANSI/NISO Z39.104-2022 contributor roles."},{"name":"Dictionary","description":"CASRAI Dictionary terms, domains, and relationships."},{"name":"Contributions","description":"Per-user CRediT contribution claims pushed to ORCID."}],"paths":{"/":{"get":{"summary":"Discovery document","description":"Enumerates the v1 surface. Authentication is optional; sending a valid key adds an `authenticated` block reflecting the resolved identity.","tags":["Meta"],"security":[{"ApiKeyAuth":[]},{}],"responses":{"200":{"description":"Discovery document.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discovery"},"examples":{"anonymous":{"value":{"name":"CASRAI API","version":"v1","documentation":"https://casrai.org/implement/rest","endpoints":{"GET /api/v1/me":"Bearer-token owner identity","GET /api/v1/credit/roles":"List all 14 CRediT roles"},"auth":"Bearer your_casrai_pk_xxx_key","rate_limit":"60 req/min per key","license":"API responses are CC-BY 4.0","authenticated":null}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/me":{"get":{"summary":"Bearer key owner identity","description":"Returns the resolved identity for the bearer key on this request. Useful for verifying that a key is valid, has the expected scope, and is bound to the expected ORCID iD.","tags":["Meta"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Resolved identity for this bearer key.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"},"examples":{"sample":{"value":{"user_id":1429,"orcid_id":"0000-0002-1825-0097","scope":"read","key_prefix":"casrai_pk_a3f201bc","api_version":"v1"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/credit/roles":{"get":{"summary":"List all 14 CRediT roles","description":"Returns the canonical 14 CRediT roles in their NISO Z39.104-2022 order. Requires read scope.","tags":["CRediT"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Ordered list of all 14 roles.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditRoleList"},"examples":{"sample":{"value":{"version":"v2022.1","standard":"ANSI/NISO Z39.104-2022","license":"CC-BY-4.0","count":14,"roles":[{"slug":"conceptualization","name":"Conceptualization","definition":"Ideas; formulation or evolution of overarching research goals and aims.","group":"Planning & design","order":1}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/credit/roles/{slug}":{"get":{"summary":"Get one CRediT role by slug","description":"Returns a single CRediT role with its canonical NISO URI. 404 if the slug is not one of the 14 NISO roles.","tags":["CRediT"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"CRediT role slug.","schema":{"type":"string","enum":["conceptualization","data-curation","formal-analysis","funding-acquisition","investigation","methodology","project-administration","resources","software","supervision","validation","visualization","writing-original-draft","writing-review-editing"]},"example":"conceptualization"}],"responses":{"200":{"description":"One CRediT role.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditRole"},"examples":{"sample":{"value":{"slug":"conceptualization","name":"Conceptualization","definition":"Ideas; formulation or evolution of overarching research goals and aims.","group":"Planning & design","order":1,"canonical_uri":"https://casrai.org/credit/roles/conceptualization","standard":"ANSI/NISO Z39.104-2022","license":"CC-BY-4.0"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/dictionary/terms":{"get":{"summary":"List dictionary terms","description":"Paginated list of dictionary terms with optional domain filter and free-text search across slug and title. Results are returned in deterministic alphabetical order by slug so pagination is stable across requests.","tags":["Dictionary"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"domain","in":"query","required":false,"description":"Filter by dictionary-domain slug (exact match).","schema":{"type":"string"},"example":"knowledge-equity"},{"name":"search","in":"query","required":false,"description":"Case-insensitive substring match against slug and title.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (1-100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"Number of records to skip.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated dictionary-term page.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryTermList"},"examples":{"sample":{"value":{"count":47,"limit":20,"offset":0,"results":[{"slug":"open-access","title":"Open access","domain_slug":"knowledge-equity","domain_name":"Knowledge equity","track":"core","status":"stable","operational_definition":"Unrestricted online access to peer-reviewed scholarly research.","canonical_uri":"https://casrai.org/dictionary/term/open-access"}],"filters":{"domain":"knowledge-equity","search":null}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/dictionary/terms/{slug}":{"get":{"summary":"Get one dictionary term by slug","description":"Returns a single dictionary term with its full operational definition, examples, counter-examples, aliases, domain, status, version, and relationships.","tags":["Dictionary"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"Dictionary-term slug.","schema":{"type":"string"},"example":"genai-disclosure"}],"responses":{"200":{"description":"One dictionary term.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DictionaryTerm"},"examples":{"sample":{"value":{"slug":"genai-disclosure","title":"GenAI disclosure","status":"stable","version":"v2026.1","operational_definition":"A structured statement attached to a research output declaring the use of generative AI tools.","examples":["Manuscript declares use of GPT-4 for copy-editing."],"counter_examples":["Author lists 'ChatGPT' as a co-author."],"aliases":["AI disclosure","Generative AI statement"],"domain":{"slug":"genai-disclosure","name":"GenAI disclosure","track":"core"},"relationships":[{"type":"related","target_slug":"authorship","target_uri":null,"note":"Co-located disclosure block"}],"canonical_uri":"https://casrai.org/dictionary/term/genai-disclosure","license":"CC-BY-4.0"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/contributions":{"get":{"summary":"List the caller's CRediT contributions","description":"Lists the bearer key owner's previously-claimed CRediT contributions, sourced from the ORCID-linked WordPress record. Requires read scope.","tags":["Contributions"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Owner's claimed contributions.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributionList"},"examples":{"sample":{"value":{"user_id":1429,"orcid_id":"0000-0002-1825-0097","count":1,"contributions":[{"put_code":123456,"doi":"10.1234/example.2026.0001","title":"An open standards approach to research administration","journal":"Research Policy","date_published":"2026-04-12","roles":["conceptualization","writing-original-draft"],"pushed_at":"2026-05-21T11:14:02Z"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"summary":"Create a CRediT contribution claim","description":"Creates a CRediT contribution claim against the bearer key owner's ORCID iD. Roles must be a non-empty subset of the 14 CRediT slugs. **Requires the `write` scope** — a read-only key returns `403 insufficient_scope`.","tags":["Contributions"],"security":[{"ApiKeyAuth":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributionCreate"},"examples":{"twoRoles":{"value":{"doi":"10.1234/example.2026.0001","title":"An open standards approach to research administration","journal":"Research Policy","date_published":"2026-04-12","roles":["conceptualization","writing-original-draft"]}}}}}},"responses":{"201":{"description":"Contribution claim created and pushed to ORCID.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributionCreated"},"examples":{"sample":{"value":{"ok":true,"user_id":1429,"orcid_id":"0000-0002-1825-0097","contribution":{"put_code":123456,"doi":"10.1234/example.2026.0001","roles":["conceptualization","writing-original-draft"],"pushed_at":"2026-05-21T11:14:02Z"}}}}}}},"400":{"description":"Validation failed (invalid DOI shape, missing title, empty or unknown role slug).","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidDoi":{"value":{"error":"invalid_doi"}},"titleRequired":{"value":{"error":"title_required"}},"rolesRequired":{"value":{"error":"roles_required"}},"invalidRole":{"value":{"error":"invalid_role_slug"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable error code.","example":"invalid_or_revoked_key"},"message":{"type":"string","description":"Optional human-readable message."},"detail":{"description":"Optional structured detail from an upstream service."}}},"CreditRole":{"type":"object","required":["slug","name","definition","group","order"],"properties":{"slug":{"type":"string","enum":["conceptualization","data-curation","formal-analysis","funding-acquisition","investigation","methodology","project-administration","resources","software","supervision","validation","visualization","writing-original-draft","writing-review-editing"],"description":"Canonical CRediT role slug (ANSI/NISO Z39.104-2022).","example":"conceptualization"},"name":{"type":"string","description":"Human-readable role name.","example":"Conceptualization"},"definition":{"type":"string","description":"Operational definition of the role from the NISO standard."},"group":{"type":"string","description":"Higher-level grouping used in the printed standard.","example":"Planning & design"},"order":{"type":"integer","minimum":1,"maximum":14,"description":"Canonical ordering position (1-14)."},"canonical_uri":{"type":"string","format":"uri","description":"NISO canonical URI for the role. Present on single-role responses only.","example":"https://casrai.org/credit/roles/conceptualization"},"standard":{"type":"string","example":"ANSI/NISO Z39.104-2022"},"license":{"type":"string","example":"CC-BY-4.0"}}},"CreditRoleList":{"type":"object","required":["version","standard","license","count","roles"],"properties":{"version":{"type":"string","example":"v2022.1"},"standard":{"type":"string","example":"ANSI/NISO Z39.104-2022"},"license":{"type":"string","example":"CC-BY-4.0"},"count":{"type":"integer","example":14},"roles":{"type":"array","items":{"$ref":"#/components/schemas/CreditRole"}}}},"DictionaryDomain":{"type":"object","properties":{"slug":{"type":"string","example":"knowledge-equity"},"name":{"type":"string","example":"Knowledge equity"},"track":{"type":["string","null"],"example":"core"}}},"DictionaryTermSummary":{"type":"object","required":["slug","title"],"properties":{"slug":{"type":"string","example":"open-access"},"title":{"type":"string","example":"Open access"},"domain_slug":{"type":["string","null"],"example":"knowledge-equity"},"domain_name":{"type":["string","null"],"example":"Knowledge equity"},"track":{"type":["string","null"],"example":"core"},"status":{"type":"string","example":"stable"},"operational_definition":{"type":"string"},"canonical_uri":{"type":"string","format":"uri","example":"https://casrai.org/dictionary/term/open-access"}}},"DictionaryTerm":{"type":"object","required":["slug","title"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","example":"stable"},"version":{"type":["string","null"],"example":"v2026.1"},"operational_definition":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"counter_examples":{"type":"array","items":{"type":"string"}},"aliases":{"type":"array","items":{"type":"string"}},"domain":{"anyOf":[{"$ref":"#/components/schemas/DictionaryDomain"},{"type":"null"}]},"relationships":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"related"},"target_slug":{"type":"string","example":"authorship"},"target_uri":{"type":["string","null"],"format":"uri"},"note":{"type":["string","null"]}}}},"canonical_uri":{"type":"string","format":"uri"},"license":{"type":"string","example":"CC-BY-4.0"}}},"DictionaryTermList":{"type":"object","required":["count","limit","offset","results","filters"],"properties":{"count":{"type":"integer","description":"Total matching terms (before pagination).","example":47},"limit":{"type":"integer","minimum":1,"maximum":100,"example":20},"offset":{"type":"integer","minimum":0,"example":0},"results":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryTermSummary"}},"filters":{"type":"object","properties":{"domain":{"type":["string","null"]},"search":{"type":["string","null"]}}}}},"Contribution":{"type":"object","properties":{"put_code":{"type":["integer","string"],"description":"ORCID put-code returned by the ORCID Member API.","example":123456},"doi":{"type":"string","example":"10.1234/example.2026.0001"},"title":{"type":"string","example":"An open standards approach to research administration"},"journal":{"type":["string","null"],"example":"Research Policy"},"date_published":{"type":["string","null"],"example":"2026-04-12"},"roles":{"type":"array","items":{"type":"string","enum":["conceptualization","data-curation","formal-analysis","funding-acquisition","investigation","methodology","project-administration","resources","software","supervision","validation","visualization","writing-original-draft","writing-review-editing"]},"example":["conceptualization","writing-original-draft"]},"pushed_at":{"type":["string","null"],"format":"date-time","example":"2026-05-21T11:14:02Z"}}},"ContributionList":{"type":"object","required":["user_id","orcid_id","count","contributions"],"properties":{"user_id":{"type":"integer","example":1429},"orcid_id":{"type":["string","null"],"example":"0000-0002-1825-0097"},"count":{"type":"integer","example":3},"contributions":{"type":"array","items":{"$ref":"#/components/schemas/Contribution"}}}},"ContributionCreate":{"type":"object","required":["doi","title","roles"],"properties":{"doi":{"type":"string","pattern":"^10\\.\\d{4,9}/[^\\s]{1,200}$","description":"Crossref-shaped DOI of the work.","example":"10.1234/example.2026.0001"},"title":{"type":"string","minLength":1,"description":"Title of the work as it appears in publication metadata.","example":"An open standards approach to research administration"},"journal":{"type":"string","nullable":true,"example":"Research Policy"},"date_published":{"type":"string","nullable":true,"description":"ISO date or four-digit year.","example":"2026-04-12"},"roles":{"type":"array","minItems":1,"items":{"type":"string","enum":["conceptualization","data-curation","formal-analysis","funding-acquisition","investigation","methodology","project-administration","resources","software","supervision","validation","visualization","writing-original-draft","writing-review-editing"]},"description":"Non-empty subset of the 14 CRediT role slugs.","example":["conceptualization","writing-original-draft"]}}},"ContributionCreated":{"type":"object","required":["ok","user_id","orcid_id","contribution"],"properties":{"ok":{"type":"boolean","example":true},"user_id":{"type":"integer","example":1429},"orcid_id":{"type":["string","null"],"example":"0000-0002-1825-0097"},"contribution":{"$ref":"#/components/schemas/Contribution"}}},"Me":{"type":"object","required":["user_id","scope","key_prefix","api_version"],"properties":{"user_id":{"type":"integer","example":1429},"orcid_id":{"type":["string","null"],"example":"0000-0002-1825-0097"},"scope":{"type":"string","enum":["read","write"],"example":"read"},"key_prefix":{"type":"string","description":"Non-secret prefix of the bearer key for identification.","example":"casrai_pk_a3f201bc"},"api_version":{"type":"string","example":"v1"}}},"Discovery":{"type":"object","required":["name","version","endpoints"],"properties":{"name":{"type":"string","example":"CASRAI API"},"version":{"type":"string","example":"v1"},"documentation":{"type":"string","format":"uri","example":"https://casrai.org/implement/rest"},"endpoints":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of \"METHOD path\" -> short description."},"auth":{"type":"string","example":"Bearer your_casrai_pk_xxx_key"},"rate_limit":{"type":"string","example":"60 req/min per key"},"license":{"type":"string","example":"API responses are CC-BY 4.0"},"authenticated":{"anyOf":[{"type":"object","properties":{"user_id":{"type":"integer"},"orcid_id":{"type":["string","null"]},"scope":{"type":"string"},"key_prefix":{"type":"string"}}},{"type":"null"}]}}}},"responses":{"Unauthorized":{"description":"Missing, malformed, or revoked bearer key.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"value":{"error":"missing_authorization"}},"format":{"value":{"error":"invalid_key_format"}},"revoked":{"value":{"error":"invalid_or_revoked_key"}}}}}},"Forbidden":{"description":"The bearer key is valid but lacks the required scope.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientScope":{"value":{"error":"insufficient_scope","message":"This endpoint requires the write scope."}}}}}},"NotFound":{"description":"No record matches the requested slug.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"term":{"value":{"error":"term_not_found","slug":"no-such-term"}},"role":{"value":{"error":"role_not_found","slug":"no-such-role"}}}}}},"RateLimited":{"description":"Too many requests in the current 60-second sliding window.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."},"Retry-After":{"schema":{"type":"integer","example":22},"description":"Seconds the client must wait before retrying. Sent on 429 only."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"throttled":{"value":{"error":"rate_limit_exceeded","message":"Retry after the window resets."}}}}}},"ServerError":{"description":"Upstream backend (WordPress / WPGraphQL) is unavailable.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":60},"description":"Fixed window quota for this key (requests per 60-second sliding window)."},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":59},"description":"Requests remaining in the current window before a 429 is returned."},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1748781600},"description":"Unix timestamp (seconds since epoch) at which the current window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"backend":{"value":{"error":"dictionary_backend_unavailable"}},"authBackend":{"value":{"error":"auth_backend_unavailable"}}}}}}},"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"casrai_pk_<32-hex>","description":"CASRAI plaintext API key. Format: `casrai_pk_` prefix followed by 32 lowercase hexadecimal characters. Generated from /account/api-keys."}}},"externalDocs":{"description":"CASRAI developer hub","url":"https://casrai.org/implement"}}