UNFAIR
Download
APIv1 · Library
version2026.05.17

api reference · v1

Unfair Library API. Ship this week.

Structured supplement and intervention data backed by graded evidence. Stable filters, consistent pagination, clear quota headers — so you can move from discovery to ranked evidence without stitching logic.

Base path/api/library/v1
AuthAuthorization: Bearer <token>
Response typeapplication/json
Response headers
  • x-library-version
  • x-contract-version
  • x-snapshot-id
  • x-rate-limit-remaining
  • x-rate-limit-reset

Quickstart

#

Start here to confirm auth, hit one endpoint, and build a real workflow.

  1. Create or obtain an API token from your admin panel.
  2. Send it as a bearer token in the Authorization header.
  3. Use limit and offset for stable pagination.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/meta"
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes?category=disease&limit=3"

Core concepts

#

Four concepts drive every endpoint in the API.

Supplement

An ingredient with dosing ranges, safety flags, and an evidence tier summary.

Intervention

A treatment approach with linked health outcomes and an aggregate evidence score.

Health outcome

The specific measured result — a disease, biomarker, or behavior — you're trying to improve or track.

Evidence link

The raw edge between one intervention and one outcome, carrying grade, effect direction, and source metadata.

Explore the typed graph in the Schema Explorer — clickable types, field lists, and the endpoints that return each one.

Most integrations follow the same path: browse or search supplements to target a health outcome, rank linked interventions by evidence quality, then drop to individual evidence links only when you need custom scoring logic or research tooling. When you already know the entities you want, use the bulk endpoints and include expansions to avoid N+1 fetches.

Versioning & freshness

#

Every response includes x-library-version, x-contract-version, and x-snapshot-id. Treat them as separate signals — freshness, schema contract, and immutable snapshot identity.

  • Docs snapshot version: 2026-05-17T12:07:51.000Z
  • Contract version: 1.0.0
  • Snapshot id: snapshot.e513f499c72cb903305a
  • Last supplement dataset update: 2026-05-17T12:06:39Z
  • Last research dataset update: 2026-05-17T12:08:43.795Z
  • If the version changes, invalidate cached lists and refetch.

Use /snapshots and /diffs when you need auditable changes between snapshots. Use /releases plus /changelog when you want a decision-ready change feed.

Errors

#

Use the table below when integrations fail. Every error includes a cause, a fix, and whether automatic retry makes sense.

{
  "ok": false,
  "code": "capability_missing",
  "message": "API token is missing required capabilities",
  "details": {
    "requiredCapabilities": ["diffs.read"],
    "tokenCapabilities": ["library.read"]
  }
}

Structured failures include optional details. For capability_missing, the payload includes details.requiredCapabilities and details.tokenCapabilities. Query validation failures in strict mode return 400 invalid_query_param with details.fields describing each invalid parameter.

StatusCodeMeaningWhat to doRecoverability
401missing_tokenNo bearer token was providedSend Authorization with a Bearer token and retry.Recoverable by client
401invalid_tokenToken hash does not match any active tokenRegenerate the token in admin and update your env.Recoverable after token update
403token_inactiveToken exists but has been revokedReach out to support to re-enable access.Requires human action
403capability_missingToken is valid but missing required route capabilityUpdate token capabilities in admin for premium contract routes.Requires token update
404not_foundRequested resource id or slug does not existCheck slug formatting and confirm id from list endpoints.Recoverable by request correction
429monthly_limit_exceededToken exhausted its monthly request quotaPause requests until reset. Honor the Retry-After header.Time- or support-based recovery
400invalid_query_paramStrict mode rejected one or more query parametersFix fields listed in details.fields or remove strict=true.Recoverable by request correction

Need help with credentials or quota updates? Reach out through our contact page.

Supplements

#

Detail pages, search, and bulk hydration.

GET/supplementsList supplements

Paginated supplement catalog

Returns a list of supplements. Filters apply before sorting, so results are ranked by evidence tier strength and then alphabetically.

requires library.read
TipIf you apply a tier filter, the ranking still uses the same sort rule inside that tier.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements?q=creatine&category=amino-acid"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/supplements/{slug}Get supplement

One supplement by slug

Returns one supplement by slug. Unknown slugs return 404. Supplement slugs are lowercase and hyphenated.

requires library.read
  • slugstringrequired
    Supplement slug (path).e.g. 5-htp
  • includearray
    Expand with article markdown, contract metadata, or linked studies in one call.e.g. include=content,coverage,identifiers
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements/5-htp?include=content%2Ccoverage%2Cidentifiers"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/supplements/{slug}/contentGet supplement article

Long-form markdown article

Returns the full article markdown for a supplement. Use this when you need the content separately from the structured data.

requires library.read
  • slugstringrequired
    Supplement slug (path).e.g. creatine
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements/creatine/content"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/supplements/{slug}/product-packGet product pack

One-call detail page bundle

Product-ready supplement bundle. Returns a curated response for product pages with summary, dose, safety, evidence highlights, supporting traces, and related entities.

requires library.read
  • slugstringrequired
    Supplement slug (path).e.g. alpha-gpc
  • includearray
    Pull extra content into the pack without separate detail requests.e.g. include=content,studies
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements/alpha-gpc/product-pack?include=content%2Cstudies"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
POST/supplements/bulkBulk hydrate supplements

Resolve many slugs in one request

Bulk hydration endpoint family. Send a non-empty ids array plus optional lookupBy and include values to resolve many entities in one request and avoid N+1 fetches. The same request shape is available at /health-outcomes/bulk, /interventions/bulk, and /studies/bulk.

requires library.read
  • idsarrayrequired
    Non-empty array of IDs or slugs to resolve.
  • lookupBystring
    Which identifier kind the ids array contains.e.g. lookupBy: "slug"
  • includearray
    Expansions: coverage, identifiers, studies, content where supported.
curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/supplements/bulk" \
  -d '{"ids":["creatine","5-htp"],"lookupBy":"slug"}'
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in

Library metadata

#

Version, categories, tiers, validation contract.

GET/metaLibrary metadata

Library + research metadata + facets

Returns library metadata and filter facets (categories and tiers), plus research graph metadata/facets for health outcomes and interventions. Includes contracts.validation so clients can render machine-readable query parameter rules and strict-mode support per route.

requires library.read
TipCall this once during app start to prefill filters and cache metadata.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/meta"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.

Health outcomes

#

Outcome-first discovery, briefs, and ranked interventions.

GET/health-outcomesList health outcomes

Paginated outcome catalog

Returns paginated health outcomes with category/source filters and intervention linkage counts.

requires library.read
NotesourceType=interventionDerived means the outcome was inferred from intervention mappings; healthOutcomeFile comes from curated outcome records.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes?q=sleep&category=disease"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/health-outcomes/{id}Get health outcome

One outcome with intervention linkage

Returns one health outcome by id. Missing ids return 404 with code: not_found.

requires library.read
  • idstringrequired
    Health outcome id (path).e.g. sleep-latency
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes/sleep-latency"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/health-outcomes/{id}/briefOutcome brief

Decision-ready summary for an outcome page

Decision-ready outcome brief. Returns a compact summary, top interventions, and evidence distributions so you can render "what helps this?" without custom aggregation.

requires library.read
  • idstringrequired
    Health outcome id (path).e.g. sleep-latency
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes/sleep-latency/brief"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/health-outcomes/{id}/interventionsInterventions for outcome

Raw intervention list ordered by evidence

Returns interventions associated with a health outcome, ordered by combined evidence strength.

requires library.read
TipUse minGrade to narrow to better-supported interventions.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes/sleep-latency/interventions?condition=Insomnia&minGrade=B"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/health-outcomes/{id}/ranked-interventionsRanked interventions for outcome

Graded shortlist with score breakdowns

Ranked intervention shortlist with transparent score breakdowns, explanations, top evidence, and coverage confidence. Use this when your product needs a shortlist, not raw graph traversal.

requires library.read
  • idstringrequired
    Health outcome id (path).e.g. sleep-latency
  • minGradestring
    Drop weaker evidence grades.e.g. minGrade=B
  • sortstring
    Reorder the shortlist.e.g. sort=coverage_first
  • limitinteger
    Page size. Max 200.e.g. limit=10
  • offsetinteger
    offset parameter
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes/sleep-latency/ranked-interventions?minGrade=B&sort=coverage_first"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
POST/health-outcomes/bulkBulk hydrate outcomes

Resolve many outcomes in one request

Shares the bulk hydration shape with /supplements/bulk. Send a non-empty ids array plus optional include values.

requires library.read
  • idsarrayrequired
    Non-empty array of outcome IDs.
  • lookupBystring
    Optional, but this route is ID-only. Keep lookupBy as id when you send it.e.g. lookupBy: "id"
  • includearray
    Expansions supported per route.
curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/health-outcomes/bulk" \
  -d '{"ids":["sleep-latency","abdominal-pain"],"lookupBy":"id"}'
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.

Interventions

#

Rank, brief, and compare interventions.

GET/interventionsList interventions

Paginated intervention catalog

Returns paginated interventions with condition and linked-outcome category filters.

requires library.read
TipUse condition first, then add outcomeCategory for tighter targeting.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions?q=theanine&condition=Anxiety"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/interventions/{id}Get intervention

One intervention with evidence

Returns one intervention by id. Missing ids return 404 with code: not_found.

requires library.read
  • idstringrequired
    Intervention id (path).e.g. acupuncture
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/acupuncture"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/interventions/{id}/briefIntervention brief

Why-it-works summary

Decision-ready intervention brief. Returns the strongest linked outcomes, related conditions, and evidence distributions for a single intervention.

requires library.read
  • idstringrequired
    Intervention id (path).e.g. acupuncture
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/acupuncture/brief"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/interventions/{id}/health-outcomesOutcomes for intervention

Outcomes ordered by evidence strength

Returns health outcomes associated with an intervention, ordered by combined evidence strength.

requires library.read
TipStart with minGrade=B for a high-confidence subset.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/acupuncture/health-outcomes?category=disease&condition=Insomnia"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
POST/interventions/bulkBulk hydrate interventions

Resolve many in one request

Shares the bulk hydration shape with /supplements/bulk.

requires library.read
  • idsarrayrequired
    Non-empty array of intervention IDs.
  • lookupBystring
    Optional, but this route is ID-only. Keep lookupBy as id when you send it.e.g. lookupBy: "id"
  • includearray
    Expansions supported per route.
curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/interventions/bulk" \
  -d '{"ids":["acupuncture","aerobic-exercise"],"lookupBy":"id"}'
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/interventions/rankedRanked interventions

Global ranked shortlist

Global ranked intervention listing with filterable condition, outcome category, and minimum grade. Use this when you want a shortlist before choosing exact outcomes to compare.

requires library.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/ranked?condition=Insomnia&outcomeCategory=Feel"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in

Compare

#

Pairwise decision endpoints.

POST/compare/interventionsCompare interventions

Head-to-head with shared outcomes + winner

Pairwise comparison endpoint. Send left, right, and optional compareOn values to get shared outcomes, advantages, safety deltas, and a winner summary without writing your own comparison logic. The same shape is available at /compare/supplements.

requires library.read
  • leftstringrequired
    Left candidate id or slug.
  • rightstringrequired
    Right candidate id or slug.
  • compareOnarray
    Optional outcome IDs to focus the comparison.e.g. compareOn: ["sleep-latency"]
  • includearray
    Optional comparison expansions.
curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/compare/interventions" \
  -d '{"left":"acupuncture","right":"aerobic-exercise","compareOn":["sleep-latency"]}'
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
POST/compare/supplementsCompare supplements

Head-to-head supplement comparison

Pairwise supplement comparison. Same shape as /compare/interventions.

requires library.read
  • leftstringrequired
    Left supplement slug.
  • rightstringrequired
    Right supplement slug.
  • compareOnarray
    Optional outcome IDs to focus on.
  • includearray
    Optional comparison expansions.
curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/compare/supplements" \
  -d '{"left":"magnesium","right":"l-theanine","compareOn":["sleep-latency"]}'
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.

Evidence

#

Traverse the supplement-outcome graph.

GET/evidenceEvidence statements

Structured statements with provenance

Returns structured evidence statements linking supplements to outcomes with predicate, population, and source metadata.

requires library.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence?supplementID=creatine&predicateID=improves"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/evidence-linksEvidence links

Raw edges with grade and effect

Returns individual evidence links between interventions and outcomes. Most integrations don't need this unless you are building custom ranking or graph logic.

requires library.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence-links?q=magnesium&interventionID=l-theanine"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/evidence/reverseReverse evidence lookup

Which supplements target this outcome?

Reverse evidence query: given an outcome, find which supplements have evidence for it. Returns grouped statements with supplement IDs.

requires library.read
  • objectIDstring
    The outcome to reverse-lookup.e.g. objectID=cognitive-performance
  • predicateIDstring
    Filter by relationship direction.e.g. predicateID=improves
  • populationstring
    Narrow to a population group.e.g. population=athletes
TipUse this to power "what helps with X?" discovery experiences.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence/reverse?objectID=cognitive-performance&predicateID=improves"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in

Studies

#

Citations with effect estimates and structured metadata.

GET/studiesList studies

Search studies, filter by effect data

Returns paginated studies with search, PubMed ID lookup, and effect estimate filtering. Each study includes structured metadata: design details (blinding, randomization, duration), population (sample size, age range, sex), publication info (journal, year, authors), conclusions, adverse events, and funding sources.

requires library.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/studies?q=creatine+cognition&pmid=12345678"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/studies/{studyID}Get study

Full structured record

Returns one study by id with full metadata and linked supplement associations. Includes structured design, population, intervention, and publication objects along with author details, conclusions, adverse events, and funding.

requires library.read
  • studyIDstringrequired
    Study id (path).e.g. pmid-29257353
NoteResponse objects: design (type, blinding, control, durationDays, randomized), population (description, sampleSize, ageRange, sex), interventions (description, dose), publication (journal, year), authors (name, affiliation, email), plus conclusions, adverseEvents, funding.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/studies/pmid-29257353"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/studies/{studyID}/contentGet study content

Full paper markdown and summary metadata

Returns the full paper content markdown for a study when available, plus summary markdown and extraction metadata. Use contentStatus and contentSource to distinguish extracted full text from compatibility fallbacks.

requires library.read
  • studyIDstringrequired
    Study id (path).e.g. pmid-29257353
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/studies/pmid-29257353/content"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
POST/studies/bulkBulk hydrate studies

Resolve many studies in one request

Shares the bulk hydration shape with /supplements/bulk.

requires library.read
  • idsarrayrequired
    Non-empty array of study IDs.
  • lookupBystring
    Optional, but this route is ID-only. Keep lookupBy as id when you send it.e.g. lookupBy: "id"
  • includearray
    Expansions supported per route.
curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/studies/bulk" \
  -d '{"ids":["pmid-29257353","pmid-15986863"],"lookupBy":"id"}'
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.

Safety & interactions

#

Drug-supplement screening and interaction data.

GET/interaction-factsInteraction facts

Structured interaction assertions with severity

Structured interaction facts view over the assertion ledger with supplement, target typing, severity, and coverage fields.

requires interaction-facts.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interaction-facts?supplementID=st-johns-wort&targetType=drug"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/interactionsList interactions

Supplement-drug and supplement-supplement interactions

Returns supplement-drug and supplement-supplement interactions with target typing and external code references.

requires library.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interactions?targetType=drug&system=rxnorm"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
POST/safety/screenSafety screen

Clear · warn · block decision

Productized safety screen. Submit candidate supplements plus medication, condition, stack, and profile context to receive a machine-readable clear, warn, block, or insufficient_coverage decision with blockers, warnings, and trace IDs.

requires interaction-facts.readrequires assertions.readrequires coverage.read
  • candidatesarrayrequired
    Candidate supplements to screen.
  • medicationsarray
    Patient medication list.
  • conditionsarray
    Conditions or states to consider.
  • profile.strictnessstring
    Use high_safety to surface coverage gaps as insufficient_coverage.
curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/safety/screen" \
  -d '{"candidates":[{"supplementID":"st-johns-wort"}],"medications":[{"label":"sertraline"}],"profile":{"strictness":"high_safety"}}'
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in

Lookup & identifiers

#

Cross-system ID resolution.

GET/identifiersIdentifier graph

Crosswalk across all entity types

Identifier graph and crosswalk lookup across supplements, studies, outcomes, and interventions.

requires identifiers.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/identifiers?entityType=supplement&entityID=creatine"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/lookupLookup

Forward or reverse ID resolution

Cross-reference lookup. Maps external identifiers (PubChem, UNII, RxNorm) to Unfair entity IDs and back. Use this to bridge your existing data with the Unfair graph.

requires identifiers.read
  • systemstring
    The external identifier system.e.g. system=pubchem
  • codestring
    The external code to resolve.e.g. code=586
  • sourcestring
    Alternative crosswalk system.e.g. source=unii
  • externalIDstring
    Alternative crosswalk code.e.g. externalID=MU72812GK0
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/lookup?system=pubchem&code=586"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in

Assertions & coverage

#

Contract-grade facts you can cite.

GET/assertionsList assertions

Claims, interactions, contraindications, regulatory

Canonical assertion ledger endpoint. Query claims, interactions, contraindications, regulatory facts, and intervention-outcome edges from one schema.

requires assertions.read
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/assertions?kind=claim&subjectType=supplement&subjectID=creatine"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/assertions/{id}Get assertion

One assertion with provenance

Returns one assertion by deterministic id for audit trails and deep links.

requires assertions.read
  • idstringrequired
    Assertion id (path).e.g. assertion.avoid_if.5-htp.44b8953e5ddc78ca
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/assertions/assertion.avoid_if.5-htp.44b8953e5ddc78ca"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
GET/coverageCoverage reports

Per-entity coverage transparency

Per-entity coverage transparency for evidence linkage, coding completeness, and unresolved gaps.

requires coverage.read
  • entityTypestring
    Scope coverage to one entity kind.e.g. entityType=supplement
  • entityIDstring
    Check coverage for one entity.e.g. entityID=ashwagandha
  • gapstring
    Filter to entities with a specific gap type.e.g. gap=missing_evidence
  • limitinteger
    Page size.e.g. limit=100
  • offsetinteger
    Pagination offset.e.g. offset=0
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/coverage?entityType=supplement&entityID=ashwagandha"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.

Snapshots & change intel

#

Audit trail for every change.

GET/changelogChangelog feed

Human-readable change stream

Human-readable companion feed to /releases. Stream the latest impactful changes classified by kind (safety, evidence, content, coverage).

requires snapshots.readrequires diffs.read
  • limitinteger
    Page size.e.g. limit=10
  • offsetinteger
    Pagination offset.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/changelog?limit=10"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/diffsDiffs

Classified diffs between snapshots

Classified diff feed. Compare two snapshots to see added, modified, and removed entities plus impact type, severity, and recommended downstream action.

requires diffs.read
  • fromSnapshotIDstringrequired
    Preferred baseline snapshot to diff from.e.g. fromSnapshotID=snap-2026-02
  • toSnapshotIDstring
    Optional, defaults to current snapshot.e.g. toSnapshotID=snap-2026-03
  • entityTypestring
    Scope the diff to one entity kind.e.g. entityType=supplement
  • limitinteger
    Page size.e.g. limit=100
  • offsetinteger
    Pagination offset.
NoteSupports conditional requests with If-None-Match.
NoteIf neither fromSnapshotID nor sinceSnapshotID is provided, the API returns 400 missing_from_snapshot.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/diffs?fromSnapshotID=snap-2026-02&toSnapshotID=snap-2026-03"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/releasesReleases

Classified release summaries

Change-intelligence feeds built on top of snapshots and diffs. Use /releases for classified release summaries and /changelog for a more human-readable stream.

requires snapshots.readrequires diffs.read
  • limitinteger
    Page size.e.g. limit=5
  • offsetinteger
    Pagination offset.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/releases?limit=5"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.
Used in
GET/snapshotsList snapshots

Point-in-time manifests with digests

Snapshot manifests with contract version, artifact digests, and immutable snapshot identifiers.

requires snapshots.read
  • limitinteger
    Page size.e.g. limit=20
  • offsetinteger
    Pagination offset.e.g. offset=0
NoteSupports conditional requests with If-None-Match. Successful cache validation returns 304 with an ETag header.
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/snapshots?limit=20&offset=0"
Try it livePaste a token in the header to use your data — otherwise calls run unauthenticated and return 401.

Workflows · 7

#

Job-based examples you can copy and adapt. Each workflow is a numbered sequence of requests — the response from one step feeds the next.

Wellness app · guided picker

Ranked shortlist for an outcome

Your user asks for sleep. You return the top candidates ranked by evidence grade — no stitching, no custom scoring.

  1. Find the outcomeSearch for matching outcomes by keyword.GET/health-outcomes
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes?q=sleep&limit=1"
    NextThe first hit's `id` feeds the next step.
  2. Ask for a ranked shortlistSkip raw graph traversal — request the shortlist endpoint with a minimum grade.GET/health-outcomes/{id}/ranked-interventions
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes/OUTCOME_ID/ranked-interventions?minGrade=B&limit=10"
  3. Pull a brief to explain the top pickGet a why-it-works summary for the candidate you want to feature.GET/interventions/{id}/brief
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/INTERVENTION_ID/brief?minGrade=B&limit=5"
Supplement commerce · PDP

Build a supplement detail page fast

One call returns dose, safety, evidence highlights, and related entities — then bulk hydrate adjacent cards to avoid N+1.

  1. Fetch the product packCurated bundle with dose, safety, evidence highlights, and related entities.GET/supplements/{slug}/product-pack
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements/alpha-gpc/product-pack?include=content,studies"
  2. Bulk hydrate adjacent cardsSend slugs for the related rail in one request — no N+1 fetches.POST/supplements/bulk
    curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/supplements/bulk" \
  -d '{"ids":["alpha-gpc","citicoline"],"lookupBy":"slug","include":["coverage","identifiers"]}'
    NextRender dose, safety, evidence highlights, and related entities from one response.
Wellness app · decision rail

Compare ranked candidates

Narrow to a shortlist, then compare head-to-head with shared outcomes and a winner summary.

  1. Rank interventions for a conditionGET/interventions/ranked
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/ranked?condition=Insomnia&minGrade=B&limit=5"
  2. Compare the top twoPass both candidates plus the outcome you care about.POST/compare/interventions
    curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/compare/interventions" \
  -d '{"left":"magnesium","right":"l-theanine","compareOn":["sleep-latency"]}'
    NextUse the winner, shared outcomes, and score summary in your chooser UI.
Telehealth · Pharmacy

Safety check before recommending

Submit the candidate, the patient's meds, and the profile context. Receive a machine-readable clear / warn / block verdict.

  1. Run the screenUse `strictness=high_safety` to surface coverage gaps as `insufficient_coverage` instead of silently downgrading.POST/safety/screen
    curl -sS -X POST -H "Authorization: Bearer $UAF_TOKEN" \
  -H "Content-Type: application/json" \
  "https://unfairapp.com/api/library/v1/safety/screen" \
  -d '{
    "candidates": [{"supplementID": "st-johns-wort"}],
    "medications": [{"label": "sertraline"}],
    "conditions": [{"label": "pregnancy"}],
    "profile": {"strictness": "high_safety"}
  }'
Clinical platform · Cache invalidation

Audit trail across data updates

Watch classified releases, read the changelog, then fall back to raw diffs when you need entity-level action.

  1. See the most recent releasesGET/releases
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/releases?limit=5"
  2. Pull the changelog feedGET/changelog
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/changelog?limit=10"
  3. Fetch entity-level diffsWhen you need to invalidate specific entities in your cache.GET/diffs
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/diffs?fromSnapshotID=snap-2026-02&toSnapshotID=snap-2026-03&entityType=supplement"
Research tools · Integrations

Cross-reference external identifiers

Map between Unfair entity IDs and external systems like PubChem, UNII, or RxNorm.

  1. List external identifiers for a supplementGET/identifiers
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/identifiers?entityType=supplement&entityID=creatine"
  2. Reverse lookup from an external codeGET/lookup
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/lookup?system=pubchem&code=586"
Research tools

Deep evidence drill-down with studies

Trace claims back to primary sources. Search studies, query evidence statements, then reverse-lookup to find related supplements.

  1. Search studies with effect estimatesGET/studies
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/studies?q=creatine&hasEffectEstimates=true&limit=5"
  2. Get structured evidence statementsGET/evidence
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence?supplementID=creatine&limit=10"
  3. Reverse query: which supplements help this outcome?GET/evidence/reverse
    curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence/reverse?objectID=cognitive-performance"

Field glossary

#

Domain-specific fields you'll meet across responses.

  • tierThe normalized evidence strength bucket. Higher quality evidence sorts first in ranked responses.
  • endpointRelevanceScores how directly a study endpoint supports the claim. Higher is more aligned.
  • biasRiskEstimates methodological risk of bias for an evidence entry. Lower is better.
  • predicateThe relationship between subject and object in an evidence statement — e.g. `improves`, `worsens`, `no_effect`.
  • coverageMachine-readable completeness status: `full`, `partial`, `text_only`, or `has_gaps`. Use `high_safety` strictness to convert gaps into `insufficient_coverage` decisions.
  • snapshotAn immutable point-in-time manifest with artifact digests. Snapshots are the basis for diffs, releases, and audit trails.
  • contract versionThe response schema contract. Returned on every response as `x-contract-version`. Treat it as separate from freshness.

Evidence definitions

#

Evidence tier

Evidence tier is a normalized confidence label used for sorting and filtering. Higher tiers represent stronger supporting evidence and are surfaced first in ranked responses. Use tiers to control strictness in your product — start with `minGrade=B` in decision-focused views, then allow lower tiers in exploration views.

Evidence quality metadata

Quality metadata explains why an item was ranked a certain way. `endpointRelevance` describes how directly a study supports a claim; `biasRisk` estimates the likelihood of bias. Surface both to users when you want transparency — show stronger endpoint alignment and lower bias as higher confidence, and flag weaker entries.

Rate limits

#

Build clients that respect quotas by reading response headers on every request.

  • Read x-rate-limit-remaining to decide when to throttle prefetching.
  • Use x-rate-limit-reset to schedule retries after quota resets.
  • Use x-library-version as a cache key so clients skip unnecessary refetches.
  • Monthly quota is per token — limits vary by plan.
  • At zero remaining, calls fail with 429 monthly_limit_exceeded until reset.
  • For 429s, use Retry-After to pick the next attempt window.
  • Conditional requests on /meta, /snapshots, /diffs via ETag + If-None-Match. Quota still applies before a possible 304.
  • In production, back off early at low remaining values and alert your team before zero.
  • If traffic grows, request a higher limit through the contact page before launch windows.

Sample JSON responses

#
{
  "ok": true,
  "total": 386,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "slug": "5-htp",
      "displayName": "5-HTP",
      "scientificName": "5-Hydroxy-L-tryptophan",
      "categoryID": "amino-acid",
      "summary": "5-HTP is a serotonin precursor...",
      "dose": { "typical": "100-300 mg/day" },
      "evidence": { "tier": "C", "effectWindow": "2-4 weeks" }
    }
  ]
}