All content is © Verscienta Health, educational reference and not medical advice. Use of
the API is subject to the terms below; every payload carries that line
in its license field.
Access and keys
Anyone can read conditions, formulas, herbs and points without a key, rate limited per IP address. Verified professionals can create read-only API keys on their Practice tab (up to 5 active keys per account). A key adds concepts and patterns, and is rate limited per account instead of per IP.
Send a key as a Bearer token:
Authorization: Bearer vsk_…
-
Only a value starting
vsk_is read as an API key. Any otherAuthorizationvalue is ignored and the request is served as anonymous. -
A
vsk_key that is unknown or revoked, or whose owner is no longer a verified professional, gets401 invalid_api_key— never a quiet fallback to anonymous access. Failed keys count against the per-IP limit, and once an address has used that limit up, requests from it carrying a key are refused too until the minute resets. -
Requesting concepts and patterns without a key gets
401 key_required. - A key keeps working when its owner changes their password or two-step verification, since it reads published content only. If a key may have leaked, revoke it from the API keys page and create a new one.
- Keys stop working at once if the owner's professional verification lapses, and are revoked when the owner asks to delete their account.
Endpoints
GET https://verscienta.com/api/v1/{type}
GET https://verscienta.com/api/v1/{type}/{slug}
type
is one of conditions, formulas, herbs and points, or with a key also concepts and patterns. List parameters:
q— search text.page— page number, from 1.-
sort— for herbs and formulas:a-z(the default),z-a,newest,oldest. -
system— points only:tcm,extraortung; every point system by default.
Unknown parameters are ignored.
Responses
A list:
{
"data": [{"type": "herb", "slug": "…", "title": "…", "url": "…", …}],
"meta": {"page": 1, "per_page": …, "total": …, "total_pages": …},
"license": "© Verscienta Health — use subject to the API terms at https://verscienta.com/developers/api; educational reference, not medical advice"
}
One record is {"data": {…}}. An error:
{"error": {"code": "rate_limited", "message": "…", "details": {"retry_after": 12}}}
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key |
The key is unknown, revoked, or its owner is no longer verified. |
| 401 | key_required |
The content type needs a professional API key. |
| 404 | not_found |
No published record for that slug, or an unknown type. |
| 429 | rate_limited |
Over the limit. Wait the number of seconds in the Retry-After
header (also details.retry_after).
|
| 503 | unavailable |
The content backend is unreachable; try again shortly. |
Rate limits
- Without a key: 60 requests a minute per IP address.
- With a key: 120 requests a minute per account, however many keys the account holds. All keyed traffic also shares an overall ceiling, so a 429 can occasionally come sooner.
Caching
Successful reads carry a weak ETag. Send it back in If-None-Match
and an unchanged record or page answers 304 Not Modified
with no body. Anonymous reads are Cache-Control: public, max-age=300, stale-while-revalidate=600; keyed reads are
private, max-age=300
with Vary: Authorization. Errors are no-store.
Versioning
Changes within /api/v1
are additive: new optional fields and new types may appear, so clients must ignore fields
they don't know. A breaking change would ship as /api/v2, with
/api/v1
kept for about twelve months after it is deprecated.
Key terms
Each key is created under these terms (version 2026-11-05):
- Use the key only within your own practice's tools and software.
- Don't republish or redistribute the content in bulk, resell it or access to it, or use it to build a competing reference.
Examples
curl "https://verscienta.com/api/v1/herbs?q=ginseng&page=1"
curl "https://verscienta.com/api/v1/herbs/ren-shen"
curl -H "Authorization: Bearer $VERSCIENTA_API_KEY" \
"https://verscienta.com/api/v1/patterns?page=2"
curl -H 'If-None-Match: W/"…"' "https://verscienta.com/api/v1/points/lu9"