HTTP + JSON · OpenAPI 3.1
CASRAI API v1 Reference
Seven bearer-gated JSON endpoints for the CASRAI Dictionary, the 14-role CRediT vocabulary, and per-user contribution claims that push through to ORCID. Every response carries explicit rate-limit headers; the full surface is documented as an OpenAPI 3.1 spec you can feed straight into a code generator.
The v1 surface lives at https://casrai.org/api/v1/. Authentication is HTTP Bearer using a CASRAI plaintext key (casrai_pk_<32-hex>). Read endpoints accept any valid key; POST /contributions requires the write scope. Rate limit: 60 requests per minute per key.
curl -H "Authorization: Bearer casrai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
https://casrai.org/api/v1/credit/rolesVerify your API key
Paste a key to call GET /api/v1/me from this page. The key stays in your browser and is sent only to the CASRAI server. Generate a key at /account/api-keys.
Show equivalent curl
curl -H "Authorization: Bearer casrai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
https://casrai.org/api/v1/meEndpoints
The full v1 surface
Seven endpoints; one authentication scheme; one rate limit; one license.
Frequently asked
API reference FAQ
How do I authenticate?+
Every request (except GET /api/v1/) carries an HTTP Authorization header of the form Authorization: Bearer casrai_pk_<32-hex>. Keys are issued from /account/api-keys with either read scope (default) or write scope. Only POST /contributions requires write; everything else accepts a read key.
What are the rate limits?+
Every key has a fixed 60 requests per minute (sliding 60-second window). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response adds Retry-After (seconds). There is no separate per-IP cap on top of the per-key one.
Is CORS supported?+
Yes. All /api/v1/* endpoints respond with Access-Control-Allow-Origin: * and accept the Authorization and Content-Type headers from any origin. Pre-flight OPTIONS returns 204. Bearer keys are user-scoped — store them on a server, not in a public browser bundle.
How are errors structured?+
All non-2xx responses return application/json with a body of { "error": "<machine_readable_code>", "message"?: "...", "detail"?: ... }. The error code is the stable contract; the message is human prose. See the OpenAPI spec for the per-endpoint enum of error codes.
Are there official SDKs?+
Not yet. The OpenAPI 3.1 specification at /api/v1/openapi.json is suitable input for openapi-generator, Stainless, Speakeasy, Fern, or any toolchain that supports OAS 3.1. The Phase-5 roadmap (see /implement/sdks) covers maintained TypeScript, Python, and R clients.
Keep exploring
