Developers

Content API

The API serves Verscienta's published reference content only — never user or patient data. It reads the same herb, formula, condition and point records the site shows, as JSON, and nothing about any account, practitioner record or health profile.

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_…

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:

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

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):

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"