Build on Psychedex
8 live endpoints for substance, effect, interaction, and legal-status data. Every endpoint requires a key, issued during private preview.
8 endpoints serve production traffic today, and every one of them requires an API key. There is no self-serve signup. Write to contact@psychedex.org with what you are building and we will issue a key or tell you we cannot yet.
APIs
General data API
Seven endpoints, key-gated.
Jurisdiction-aware legal status
One endpoint, key-gated. Jurisdiction coverage is thin — most substances answer 'unknown' for most jurisdictions.
Multi-substance interaction checking
No Nexus route. Pairwise checking across up to 10 substances ships today at /api/v1/curiosity/interactions/check.
Effects taxonomy
No Prism route. Effect lookup and effect-to-substance links ship today under /api/v1/curiosity/effects.
Substance name resolution
No route. Slug and PSX ID are the only accepted identifiers today.
Provenance and version history
No route. Provenance and version history are published as pages instead: /substances/<slug>/evidence and /substances/<slug>/history.
Real-time supply monitoring
No route and no data sources contracted. See /sentinel for the design and scope.
Emergency response protocols
No route. Emergency guidance is published as pages at /harm-reduction/emergency.
Access
| Item | Value | Detail |
|---|---|---|
| Auth | API key, every endpoint | Send Authorization: Bearer <key>. There is no anonymous tier. |
| Getting a key | Manual, private preview | There is no self-serve signup. Write to contact@psychedex.org with what you are building and we will issue a key or tell you we cannot yet. |
| Rate limit | 120 requests/minute | Per IP, shared across every /api/v1 endpoint. The limiter runs before the key check, so an over-limit request returns 429 even with a valid key. |
| Over limit | 429 + Retry-After | Body is {"error":"rate_limited"}. There are no X-RateLimit-* headers. |
| Success shape | { data, meta } | meta carries version and a generated timestamp. |
| Error shape | { error: { code, message }, meta } | Four codes: UNAUTHORIZED, BAD_REQUEST, NOT_FOUND, INTERNAL_ERROR. |
| Versioning | In the path | Breaking changes get a new prefix. /api/v1 stays as it is. |
| Licensing | Not finalized | User-contributed content is CC BY 4.0 (see Terms). A licence for the dataset as a whole has not been set, so treat reuse terms as open questions and attribute Psychedex. |
Authentication
A key is an opaque string. Its first eight characters are the lookup prefix; the full value is stored only as a SHA-256 hash, so a lost key is reissued, never recovered. Keys can carry an expiry and can be revoked at any time.
Getting a key
Keys are provisioned manually while the program is in private preview.
There is no signup form, no dashboard, and no self-serve rotation yet. Write to contact@psychedex.org describing what you are building. Harm reduction tools get priority.
Error responses
| Code | HTTP | When |
|---|---|---|
| UNAUTHORIZED | 401 | Missing, malformed, revoked, or expired key. |
| BAD_REQUEST | 400 | A required parameter is missing or fails validation. |
| NOT_FOUND | 404 | The slug or PSX ID matches no published record. |
| INTERNAL_ERROR | 500 | The query failed. Nothing partial is returned. |
{
"error": {
"code": "NOT_FOUND",
"message": "Substance 'not-a-substance' not found"
},
"meta": {
"version": "1.0",
"generated": "2026-08-13T09:41:07.201Z"
}
}Attribution
A licence for the dataset as a whole has not been set. User-contributed content is CC BY 4.0 — see the terms.
Not part of this API
Routes under /api/public/ support the Psychedex app, which is being rebuilt. They are app-support endpoints, not part of this API: their shapes change with the app and carry no compatibility promise.