Probara for developers

The signed evidence layer for what goes in your body.

One API call returns a 33-field, outcome-scoped evidence card for any (ingredient, outcome) pair: the full GRADE reasoning trace, every supporting PMID, and an HMAC tamper-evident attestation token. Substrate only. No verdicts, no recommendations, no model-generated rewrites.

Open the interactive reference → Get a key

90-second quickstart

  1. Get an API key (below), scoped to the ingredient/outcome pairs you need.
  2. Call /v1/evidence with that key in the Authorization: Bearer header.
  3. Read the signed card: 33 fields, including the full GRADE trace and the attestation_token you can re-derive yourself.
Your first call: berberine × blood sugar (dose: 500 mg)
curl -s \
  -H "Authorization: Bearer probara_sk_live_xxxxxxxxxxxxxxxx" \
  "https://probara.dev/api/v1/evidence?ingredient=berberine&outcome=blood%20sugar&dose_mg=500" \
  | jq .
Same shape every time. Every response carries exactly 33 fields, whether the pair is found or not. Unknown pairs return null/0/[] with a null attestation_token, never a 404, so your parser can always expect the same schema.

What no one else ships: the signed GRADE reasoning trace

Other ingredient databases hand you a letter grade and stop. Probara hands you the entire GRADE-aligned reasoning trace behind that grade: every downgrade decision, the totality-of-evidence verdict, the independent-study count that guards against single-lab inflation, and the exact PMIDs, and then signs the whole card so you can prove it reached you untampered.

final_grade_tier_after_downgrades

The GRADE certainty tier after every risk-of-bias, inconsistency, indirectness, imprecision, publication-bias downgrade is applied. The honest, post-adjustment tier (not the headline grade).

totality_verdict

The weight-of-evidence verdict across the full body of studies for the pair: the kind of synthesis a careful reviewer writes, expressed as substrate, not advice.

independent_study_count

How many independent studies stand behind the grade: the guard against a grade inflated by one prolific lab.

supporting_study_ids

The exact PMIDs of those independent studies. Trace any grade back to the primary literature yourself. Returns honest null when absent, never fabricated.

HMAC tamper-evident. Every populated card carries an attestation_token: an HMAC-SHA256 digest over the canonical JSON body. Re-derive it with your shared signing key and you can detect any tampering in transit. It is GRADE-aligned evidence with an integrity seal, stated plainly.

Endpoints: copy-paste curl

Four endpoints. The two scoped ones (/v1/evidence and /changes) require your key in the Authorization: Bearer header. /health and /v1/fields are public. Full request/response shapes and a live try-it console are in the interactive reference.

GET /v1/evidence

Returns the 33-field substrate card for an (ingredient, outcome) pair. Auth required (scoped). In-scope returns 200. Out-of-scope pair returns 403. Missing or unknown key returns 401.

Shell
curl -s \
  -H "Authorization: Bearer probara_sk_live_xxxxxxxxxxxxxxxx" \
  "https://probara.dev/api/v1/evidence?ingredient=berberine&outcome=blood%20sugar&dose_mg=500" \
  | jq .

GET /v1/fields

Lists the V1.2 substrate field names in definition order. No auth required. → 200.

Shell
curl -s "https://probara.dev/api/v1/fields" | jq .

GET /changes

All (ingredient, outcome) changes since a point-in-time baseline. Auth required (key presence). Missing key returns 401. Malformed since returns 400.

Shell
curl -s \
  -H "Authorization: Bearer probara_sk_live_xxxxxxxxxxxxxxxx" \
  "https://probara.dev/api/changes?since=2026-06-01T00:00:00Z" \
  | jq '.changes[] | {ingredient, outcome, change_type, old_grade_tier, new_grade_tier}'

GET /health

Service identity and status. No auth required. → 200.

Shell
curl -s "https://probara.dev/api/health" | jq .

Unauthenticated call

Omit the key on a scoped endpoint and you get HTTP 401 with a machine-readable code: unauthorized.

Shell
# No token -> 401 Unauthorized
curl -s -o /dev/null -w "%{http_code}\n" \
  "https://probara.dev/api/v1/evidence?ingredient=berberine&outcome=blood%20sugar&dose_mg=500"

Authentication & scope

Scoped endpoints require an API key via the Authorization header:

  • Authorization: Bearer probara_sk_live_xxxxxxxxxxxxxxxx
ConditionHTTP statuscode
No key / unknown key401unauthorized
Key not scoped for the requested pair403scope_not_authorized
Key valid and in-scope200N/A
Per-key rate limit exceeded429rate_limit_exceeded

Keys are scoped to specific (ingredient, outcome) pairs at provisioning time, or granted a wildcard * outcome for an ingredient.

Attestation: re-derive the token yourself

The attestation_token is an HMAC-SHA256 hex digest (64 chars) over the canonical JSON body of the 32 preceding fields, serialised with sort_keys=True and compact separators. The signing key is PROBARA_ATTESTATION_KEY (server-global, not per-key). With your shared key you can re-derive and compare for HMAC tamper-evident integrity.

Python
import hashlib, hmac, json

def verify_attestation(card: dict, signing_key: str) -> bool:
    token = card["attestation_token"]
    canonical_body = {k: v for k, v in card.items() if k != "attestation_token"}
    canonical = json.dumps(canonical_body, sort_keys=True,
                           separators=(",", ":")).encode("utf-8")
    expected = hmac.new(signing_key.encode(), canonical,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(token, expected)
The token is null for empty-evidence shapes (unknown pairs): there is no substrate body to attest.

The 33-field evidence card

Every card carries these 33 fields, in this order. The interactive reference documents the type, examples, and x-field-class (substrate / derived / provenance) for each.

  • ingredient
  • outcome
  • final_grade
  • grade_label
  • evidence_summary
  • dose_form
  • dose_match
  • dose_match_label
  • population
  • study_count
  • pmids
  • confidence
  • validation_status
  • studied_dose_text
  • as_of_date
  • grade_downgrade_rob
  • grade_downgrade_rob_basis
  • grade_downgrade_inconsistency
  • grade_downgrade_inconsistency_basis
  • grade_downgrade_indirectness
  • grade_downgrade_indirectness_basis
  • grade_downgrade_imprecision
  • grade_downgrade_imprecision_basis
  • grade_downgrade_pub_bias
  • grade_downgrade_pub_bias_basis
  • grade_downgrade_summary
  • final_grade_tier_after_downgrades
  • totality_verdict
  • independent_study_count
  • supporting_study_ids
  • funding_source
  • dose_verdict
  • attestation_token
Substrate, not verdict. No verdict, reframe, or vault field can appear. The serialiser is an allow-list, so recommendation language is impossible by construction. "Grade A evidence" reports what the literature says. The recommendation layer ("therefore take it") is your product's editorial decision and compliance responsibility.

Get a key

API keys are issued during onboarding, scoped to the ingredient/outcome pairs you need. To request one, reach out at hello@probara.dev with the pairs you want to ground. We provision a scoped probara_sk_live_ key and you are calling the API the same day.

Open the interactive reference → See pricing