ShennongAlpha API

Use an NMM ID to retrieve the current public knowledge for a medicinal material from the ShennongAlpha knowledge base. Single-item requests allow limited anonymous access; batch requests require a signed-in session or an API key. Use your own key for programmatic access to attribute usage and audit records.

curl --fail-with-body \
  'https://shennongalpha.westlake.edu.cn/api/v1/knowledge/nmm-0001'

Do not add /zh or /en locale prefixes to API URLs. Complete knowledge preserves the original multilingual text; changing the website language does not translate the JSON content.

GET /api/v1/knowledge/{nmm_id}

An nmm_id consists of nmm- followed by four lowercase letters or digits, for example nmm-0001. The response includes published SNNMM identity, text sections, ingredients, related targets, related diseases and references. It excludes review drafts, account data and the full revision history.

Add download=1 to download the same JSON structure with a filename. The knowledge page's download button uses this endpoint. Ingredients and associations are embedded in the JSON, without a separate ingredient file.

curl --fail-with-body \
  'https://shennongalpha.westlake.edu.cn/api/v1/knowledge/nmm-0001?download=1' \
  --output nmm-0001.json

Success returns 200; an invalid ID format returns 400, and a valid ID with no matching knowledge returns 404. Read failures return errors instead of empty knowledge.

POST /api/v1/knowledge/batch

Send Content-Type: application/json. The body must contain only nmm_ids, with 1–20 distinct valid IDs. Empty lists, duplicates, 21 or more IDs, and extra fields return 400; requests are never silently truncated.

Here, SHENNONGALPHA_API_KEY is a caller-side environment variable containing the key you created under Settings → API keys. The variable name is public; its value is private.

curl --fail-with-body \
  'https://shennongalpha.westlake.edu.cn/api/v1/knowledge/batch' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${SHENNONGALPHA_API_KEY}" \
  --data '{"nmm_ids":["nmm-0001","nmm-01g8"]}'

The response contains schema_version, complete, requested and results, in request order. Successful items contain {nmm_id, status: 200, data}, with the complete single-item knowledge object in data. Failed items contain {nmm_id, status, error: {code, message}}.

HTTP 200 means the batch was processed. Always check top-level complete and each item's status. An item may return 404, 413 or 503 while others succeed. Retry only the failed items that can be retried.

Complete knowledge uses schema_version: "shennongalpha.knowledge.v1". This data contract version is independent of the website's software version.

Each section has toc_id, toc_heading, description and value. Nested sections are under value.sections; actual content is in value.content, distinguished by value.template:

This excerpt shows a real ingredient section's value.content for nmm-0001 (2026-10-27). Only the first item is shown here; total retains the full count at that time. The API returns all records, and knowledge may change.

{
  "nmm_id": "nmm-0001",
  "items": [
    {
      "pubchem_cid": 323,
      "pubchem_compound_name": "coumarin",
      "cas_registry_number": "91-64-5",
      "canonical_smiles": "C1=CC=C2C(=C1)C=CC(=O)O2",
      "ref": {
        "url": "http://herb.ac.cn/Detail/?v=HERB004520&label=Herb",
        "herb_id": "HERB004520",
        "sna_ref_id": "sna-ref-15"
      }
    }
  ],
  "total": 132,
  "relationship": "nmm_compound"
}

pubchem_cid is a numeric identifier. Ingredient ref preserves a source object, for example a URL, source database ID and sna_ref_id, or may be null.

Target records contain pubchem_cid, ncbi_gene_id, official_symbol, official_full_name and pubmed_pmid. Disease records contain pubchem_cid, mesh_id, mesh_heading and pubmed_pmid.

• Multiple sources for one ingredient remain separate records. total counts records, not necessarily unique compounds.
• Section value=null means no published section content; items=[] means a successful query with no associations. If a dictionary name is missing, the ID is retained and the name may be null.
• completeness.complete=true means all current public knowledge in scope was read, not that scientific knowledge is exhaustive. Each item uses a consistent data snapshot; different items in a batch have separate snapshots.
• content_version is for content comparison, not a digital signature. It is separate from metadata.last_updated_date; export time is also distinct from the knowledge update time.

Targets and diseases are compound-mediated associations, not direct evidence of whole-material effects or clinical efficacy. A PMID or bibliography entry does not mean the paper's contents have been verified.

GET /api/name/search

Supported name_type values are species_origins, medicinal_parts, processing_methods and special_descriptions. Use small pages and paginate according to total.

curl --fail-with-body --get \
  'https://shennongalpha.westlake.edu.cn/api/name/search' \
  --data-urlencode 'name_type=species_origins' \
  --data-urlencode 'q=Artemisia annua' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=5'

Returns {q, page, limit, total, results}. Species results include la, zh and other species fields. The other categories include en, zh and explanation; processing methods also include en_full and category. No matches return total=0 and results=[].

GET /api/name/all?name_type=medicinal_parts returns a complete small vocabulary without pagination. It supports only medicinal_parts, processing_methods and special_descriptions, not all species. The response follows the search structure, with q="", page=1 and limit=total.

GET /api/snnmm

Specify exactly one query field: nmm_id (NMM ID), nmmsn (English systematic name), nmmsn_zh (Chinese systematic name), nmmgn (English generic name) or nmmgn_zh (Chinese generic name). The legacy nmmid alias is accepted; new integrations should use nmm_id.

curl --fail-with-body --get \
  'https://shennongalpha.westlake.edu.cn/api/snnmm' \
  --data-urlencode 'nmm_id=nmm-0001'

Returns {total, results}, with identity fields including nmm_id, snnmm, nmm_hierarchy and synonyms. No matches return 200, total=0 and results=[]. Missing or multiple query fields return 400.

Use this endpoint for identity matching. For text sections, ingredients and associations, use complete knowledge.

Single-item complete knowledge, Name and SNNMM endpoints are public. Batch knowledge supports:

1. Same-origin requests from signed-in website users, carrying the site's session cookie.
2. Server applications using Authorization: Bearer <API key>.

Sign in and open Settings → API keys. Each account supports one non-revoked key. Create, regenerate or revoke it, with a validity of 30, 90 or 365 days. The complete value is shown only when generated; the database stores an irreversible hash. Regeneration replaces the old key immediately for new requests; requests already in progress may finish.

Choose read scopes: knowledge:read for complete knowledge and downloads, names:read for Name search, vocabularies and hints, and snnmm:read for identity lookup. Keys cannot edit knowledge, manage users or manage keys. Missing scope returns 403; invalid, expired or revoked keys return 401 without anonymous fallback.

Server applications can use a personal API key. For services that need independent management, administrators can configure a service identity, service key and separate quota. Keep keys on the calling server, never in browser scripts, public repositories, URLs or logs.

Cross-origin browser access is not enabled. Other websites should call from their servers. The ShennongAlpha website uses its session; do not embed a personal key in webpages.

Request auditing

The query endpoints return X-Request-Id for correlating requests and troubleshooting. Settings shows your requests from the last 90 days. Administrators can view all users and services, adjust quotas and disable API access.

Records include caller identity, key ID, endpoint, time, charged units, status, failed batch-item count and duration. They exclude raw keys, search text and knowledge response bodies. Anonymous requests cannot be attributed to an account. A service key identifies the calling service, not its individual users. Callers can store the returned X-Request-Id in their own task records to correlate them with platform request records. Key creation, regeneration, revocation and quota changes have separate activity records.

Complete knowledge, downloads, Name search / vocabularies / hints and SNNMM queries share authentication, scope checks, quotas and auditing. Public website browsing remains available. Other internal endpoints do not gain key access.

Accepted requests also charge for not-found items and read failures. Personal-key and website-session requests share the account quota. Regeneration, revocation and subsequent creation do not reset usage.

All applicable limits apply together, using fixed UTC windows. Clients sharing a network exit may share an IP quota. Keys are also limited by their owning identity. Use Settings and the response headers for effective limits:

• X-RateLimit-Limit: the strictest applicable minute limit.
• X-RateLimit-Remaining: the smallest remaining minute allowance, not the daily balance.
• X-RateLimit-Cost: the number of quota units charged for this request.
• Retry-After: seconds to wait after 429. Add jitter to retries to avoid simultaneous resubmissions.

An IP or identity may have at most 2 requests in flight; the service-wide default is 8. Batch bodies are limited to 4 KiB, single JSON responses to 8 MiB, batch responses to 24 MiB, and each association section to 10,000 rows. Oversized results return explicit errors, not truncated “complete” exports. A large batch can take about 70 seconds; callers can use a 90-second timeout and smaller batches as needed.

Complete knowledge application errors normally use this structure. Use code for programmatic handling and message for explanation; do not depend on the message language.

{
  "error": {
    "code": "authentication_required",
    "message": "批量查询需要登录或知识 API 服务密钥。"
  }
}

Malformed JSON and oversized batch bodies return explicit audited application errors. Gateway or network errors may still return non-JSON content. Check HTTP status and Content-Type before parsing. Legacy Name and SNNMM errors use {code, message, user_message}, where code is a numeric HTTP status, unlike complete knowledge's string error codes.

ShennongSearch is the Python SDK for ShennongAlpha and uses the same data service. This page is the official HTTP API reference. For SDK installation, typed models and DataFrames, see the ShennongSearch Python SDK documentation and source repository.

The SDK wraps Name and SNNMM queries. This example also works with older SDK versions using anonymous limits. Support for the api_key option depends on the installed version. Use the HTTP example below to explicitly attribute calls to your key.

from shennongsearch import ShennongSearchClient

with ShennongSearchClient() as client:
    identity = client.snnmm.get(nmm_id="nmm-0001")
    print(identity.total)

    names = client.name.species_origins.search(
        q="Artemisia annua", page=1, limit=5
    )
    print(names.total)

The current SDK does not wrap the complete knowledge endpoints yet. Call them over HTTP; this authenticated example uses only the Python standard library. First configure the SHENNONGALPHA_API_KEY environment variable:

import json
import os
from urllib.request import Request, urlopen

url = "https://shennongalpha.westlake.edu.cn/api/v1/knowledge/nmm-0001"
request = Request(url, headers={
    "Authorization": "Bearer " + os.environ["SHENNONGALPHA_API_KEY"]
})
with urlopen(request, timeout=90) as response:
    knowledge = json.load(response)

print(knowledge["_id"], knowledge["content_version"])
print(knowledge["completeness"])