api docs

Unfair Library API v1

This API is for app developers, researchers, and health builders who need structured supplement and intervention data they can trust. It helps you move from discovery to ranked evidence quickly with stable filtering, consistent pagination, and clear quota headers.

Base Path

/api/library/v1

Auth

Authorization: Bearer <token>

Response Type

application/json

Response Headers

x-library-version
x-contract-version
x-snapshot-id
x-rate-limit-remaining
x-rate-limit-reset

Intro

The Unfair Library API gives product teams, researchers, and developers structured access to supplement and intervention data backed by graded evidence.

Use it to power supplement detail pages, rank interventions by outcome, or build discovery experiences on top of the full intervention-outcome graph.

Four core concepts drive everything in the API:

A supplement is an ingredient with dosing ranges, safety flags, and an evidence tier summary.
An intervention groups a treatment approach with its linked health outcomes and aggregate evidence score.
A health outcome is the specific measured result, a disease, biomarker, or behavior, you are trying to improve or track.
An evidence link is the raw edge between one intervention and one outcome, carrying grade, effect direction, and source metadata.

Most integrations follow the same path: browse or search supplements to target a health outcome, rank linked interventions by evidence quality, then inspect individual evidence links if you need custom scoring logic. You do not have to follow it in order, but it is the fastest way to get oriented.

Quickstart

Start here if you want to confirm auth, test one endpoint, and then build a real workflow.

Create or obtain an API token from your admin panel.
Send it as a bearer token in the Authorization header.
Use limit and offset for stable pagination.

Smoke Test

bash

curl -sS -H "Authorization: Bearer $UAF_TOKEN" "https://unfairapp.com/api/library/v1/meta"

Research Graph Smoke Test

bash

curl -sS -H "Authorization: Bearer $UAF_TOKEN" "https://unfairapp.com/api/library/v1/health-outcomes?category=disease&limit=3"

Versioning and 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-03-18T01:53:00.432Z.
Contract version: 1.0.0.
Snapshot id: snapshot.a4154a2908a032ac407e.
Last supplement dataset update: 2026-03-18T01:39:01Z.
Last research dataset update: 2026-03-18T01:53:00.432Z.
If the version changes, invalidate cached lists and refetch.

Use /api/library/v1/snapshots and /api/library/v1/diffs when you need auditable changes between snapshots.

Troubleshooting and Errors

Use this table when integrations fail. Each error includes cause, immediate fix, and whether automatic retry makes sense.

Error Payload

json

{
  "ok": false,
  "code": "invalid_token",
  "message": "Invalid API token"
}

Status	Code	Meaning	What to do	Recoverability
401	missing_token	No bearer token was provided	Send Authorization with Bearer token and retry.	Recoverable by client
401	invalid_token	Token hash does not match any active token	Regenerate the token in admin and update your env.	Recoverable after token update
403	token_inactive	Token exists but has been revoked	Reach out through the contact page to re-enable access.	Requires human action
403	capability_missing	Token is valid but missing required route capability	Update token capabilities in admin for the premium contract routes.	Requires token update
404	not_found	Requested resource id or slug does not exist	Check slug formatting and confirm id from list endpoints.	Recoverable by request correction
429	monthly_limit_exceeded	Token exhausted its monthly request quota	Pause requests until reset time or request a higher quota.	Time based or support based recovery

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

Endpoints

Use this section as a map. Each endpoint description explains what it does and what to do with the result.

GET/api/library/v1/supplements

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

Example: q=creatine. Use this to narrow results by keyword.

Workflow Examples

These are job based examples you can copy and adapt.

1. Find well supported interventions for a specific outcome

Outcome to Intervention Workflow

bash

# 1) Find sleep-related outcomes
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes?q=sleep&limit=1"

# 2) Use the returned id to fetch linked interventions with stronger evidence
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/health-outcomes/OUTCOME_ID/interventions?minGrade=B&limit=20"

# 3) Inspect one intervention and validate evidence details
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/INTERVENTION_ID"

Expected Output Shape

json

{
  "selectedOutcomeID": "sleep-latency",
  "interventionCount": 12,
  "topIntervention": "L-theanine",
  "topGrade": "B"
}

2. Build a supplement detail experience

Supplement Detail Workflow

bash

# 1) Get supplement candidates for focus
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements?q=focus&tier=B&limit=10"

# 2) Open one supplement detail by slug
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements/alpha-gpc"

# 3) Render dose, safety, and evidence fields in your UI

Expected Output Shape

json

{
  "slug": "alpha-gpc",
  "dose": {
    "typical": "300-600 mg/day"
  },
  "safety": {
    "interactions": ["cholinergic medications"]
  },
  "evidence": {
    "tier": "B"
  }
}

3. Traverse evidence links for custom ranking

Evidence Graph Workflow

bash

# 1) Find interventions for a condition
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions?condition=Insomnia&limit=5"

# 2) Pull linked outcomes for one intervention
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/INTERVENTION_ID/health-outcomes?minGrade=B"

# 3) Fetch raw evidence links if you need custom scoring
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence-links?interventionID=INTERVENTION_ID&limit=100"

Expected Output Shape

json

{
  "interventionID": "l-theanine",
  "linkedOutcomeCount": 8,
  "edgeCount": 43,
  "exampleEffect": "decrease"
}

4. Safety check before recommending a supplement

Use interaction-facts, assertions, and coverage together to verify a supplement is safe to surface in a consumer-facing app.

Safety Check Workflow

bash

# 1) Find drug interactions for a supplement
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interaction-facts?supplementID=st-johns-wort&severity=major"

# 2) Pull contraindication assertions for the same supplement
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/assertions?kind=contraindication&subjectType=supplement&subjectID=st-johns-wort"

# 3) Check coverage completeness before surfacing in UI
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/coverage?entityType=supplement&entityID=st-johns-wort"

Expected Output Shape

json

{
  "majorInteractions": 4,
  "contraindications": ["pregnancy", "SSRI co-administration"],
  "coverageLevel": "complete",
  "safeToSurface": false
}

5. Audit trail across data updates

Use snapshots and diffs to detect what changed between releases so your integration only invalidates stale cache entries.

Audit Trail Workflow

bash

# 1) List recent snapshots to find the previous version
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/snapshots?limit=5"

# 2) Diff two snapshots to see what changed
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/diffs?fromSnapshotID=snap-2026-02&toSnapshotID=snap-2026-03&entityType=supplement"

# 3) Invalidate your cache for changed entities only

Expected Output Shape

json

{
  "fromSnapshotID": "snap-2026-02",
  "toSnapshotID": "snap-2026-03",
  "changedEntities": 12,
  "entityType": "supplement",
  "actions": ["added", "modified"]
}

6. Cross-reference external identifiers

Use identifiers and lookup to map between Unfair entity IDs and external systems like PubChem, UNII, or RxNorm.

Cross-Reference Workflow

bash

# 1) Find all external identifiers for a supplement
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/identifiers?entityType=supplement&entityID=creatine"

# 2) Reverse lookup: find the Unfair entity from an external code
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/lookup?system=pubchem&code=586"

Expected Output Shape

json

{
  "entityID": "creatine",
  "identifiers": [
    { "system": "pubchem", "code": "586" },
    { "system": "unii", "code": "MU72812GK0" }
  ]
}

7. Deep evidence drill-down with studies

Use studies, evidence, and evidence/reverse to build research tools that trace claims back to primary sources.

Deep Evidence Workflow

bash

# 1) Search studies with effect estimates for a supplement
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/studies?q=creatine&hasEffectEstimates=true&limit=5"

# 2) Get structured evidence statements
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence?supplementID=creatine&limit=10"

# 3) Reverse query: which supplements have evidence for an outcome?
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/evidence/reverse?objectID=cognitive-performance"

Expected Output Shape

json

{
  "studyCount": 5,
  "evidenceStatements": 10,
  "reverseHits": ["creatine", "omega-3", "caffeine"],
  "topStudyType": "Systematic review",
  "exampleStudy": {
    "sampleSize": 281,
    "blinding": "double-blind",
    "randomized": true,
    "journal": "Journal of the ISSN",
    "publicationYear": 2017
  }
}

Language Examples

curl

Request

bash

curl -i -sS \
  -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/supplements?limit=2&offset=0"

Response

http

HTTP/2 200
x-library-version: 2026-03-18T01:53:00.432Z
x-contract-version: 1.0.0
x-snapshot-id: snapshot.a4154a2908a032ac407e
x-rate-limit-remaining: 497
x-rate-limit-reset: 2026-03-01T00:00:00.000Z

{
  "ok": true,
  "total": 384,
  "limit": 2,
  "offset": 0,
  "filters": {
    "q": null,
    "category": null,
    "categoryLabel": null,
    "tier": null
  },
  "data": [
    {
      "slug": "5-htp",
      "displayName": "5-HTP",
      "categoryID": "amino-acid"
    },
    {
      "slug": "7-keto-dhea",
      "displayName": "7-Keto DHEA",
      "categoryID": "hormone"
    }
  ]
}

Field Glossary

These fields are domain-specific and are easiest to use when you know what they represent.

tier is the normalized evidence strength bucket. Higher quality evidence sorts first.
endpointRelevance scores how directly a study endpoint supports the claim.
biasRisk estimates methodological risk of bias for that evidence entry.

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. For example, start with minGrade=B in decision-focused views, then allow lower tiers in exploration views.

Evidence Quality Metadata

Evidence quality metadata helps explain why an item was ranked a certain way. Fields like endpointRelevance and biasRisk describe how directly a study supports a claim and how likely the result is to be biased.

Use these fields for transparency in your UI. Show users when a recommendation is backed by stronger endpoint alignment and lower bias risk, and flag weaker entries as lower confidence.

For deeper definitions, see the Evidence Tier and Evidence Quality Metadata glossary entries.

Rate Limit Strategy

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

Use 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 can skip unnecessary refetches.
Monthly quota is configured per token, so limits vary by plan.
At zero remaining requests, API calls fail with 429 monthly_limit_exceeded until reset.
In production, back off immediately at low remaining values and alert your team before zero is reached.
If traffic grows, request a higher limit through the contact page before launch windows.

Documentation Checklist

Use this checklist when adding or updating endpoints so docs stay consistent.

Confirm the endpoint fits the mental model section.
Add at least one workflow that uses the endpoint.
Document each parameter with an example and why it matters.
Describe failure modes and recovery steps.
Document quota behavior and retry strategy.

Sample JSON Responses

GET /supplements

json

{
  "ok": true,
  "total": 384,
  "limit": 50,
  "offset": 0,
  "filters": {
    "q": null,
    "category": null,
    "categoryLabel": null,
    "tier": null
  },
  "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"
      }
    }
  ]
}

GET /supplements/{slug}

json

{
  "ok": true,
  "data": {
    "slug": "5-htp",
    "displayName": "5-HTP",
    "mechanismSummary": "Precursor to serotonin...",
    "dose": {
      "min": "Not established",
      "typical": "100-300 mg/day",
      "maxCaution": "Low-risk cautious titration"
    },
    "safety": {
      "contraindications": ["pregnancy", "lactation"],
      "interactions": ["SSRI", "SNRI", "MAOI"]
    },
    "evidence": {
      "tier": "C",
      "effectWindow": "2-4 weeks",
      "table": [
        {
          "sourceID": "SRC-001",
          "studyType": "Systematic review",
          "studyURL": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
          "endpointRelevance": 4,
          "biasRisk": 4,
          "blinding": "double-blind",
          "sampleSize": 120,
          "durationDays": 56,
          "randomized": true,
          "conclusions": "Significant improvement in...",
          "adverseEvents": "Well tolerated, mild GI...",
          "dose": "300 mg/day",
          "journal": "Nutrients",
          "publicationYear": 2020
        }
      ]
    }
  }
}

GET /meta

json

{
  "ok": true,
  "data": {
    "metadata": {
      "generatedAt": "2026-03-18T01:39:01Z",
      "sourceManifestGeneratedAt": "2026-03-14T11:01:19Z",
      "sourceSupplementCount": 384,
      "importedSupplementCount": 384,
      "exportedSupplementCount": 384,
      "byCategory": {
        "chemical-compound": 16,
        "amino-acid": 31
      }
    },
    "facets": {
      "categories": ["chemical-compound", "amino-acid"],
      "tiers": ["A", "B", "C", "D"]
    },
    "research": {
      "metadata": {
        "generatedAt": "2026-03-18T01:53:00.432Z",
        "counts": {
          "healthOutcomeCount": 781,
          "interventionCount": 182,
          "edgeCount": 3919
        },
        "quality": {
          "level": "High"
        }
      },
      "facets": {
        "healthOutcomeCategories": ["Behavior and Context", "Biology"],
        "interventionConditions": ["Acute Respiratory Infection", "Aerobic Exercise Performance"]
      }
    },
    "contracts": {
      "contractVersion": "1.0.0",
      "snapshotID": "snapshot.a4154a2908a032ac407e",
      "supportedAssertionKinds": [
        "claim",
        "interaction",
        "contraindication",
        "avoid_if",
        "regulatory",
        "intervention_outcome"
      ]
    }
  }
}

Unfair Library API v1

Intro

Quickstart

Versioning and Freshness

Troubleshooting and Errors

Endpoints

Workflow Examples

1. Find well supported interventions for a specific outcome

2. Build a supplement detail experience

3. Traverse evidence links for custom ranking

4. Safety check before recommending a supplement

5. Audit trail across data updates

6. Cross-reference external identifiers

7. Deep evidence drill-down with studies

Language Examples

curl

Field Glossary

Evidence Definitions

Evidence Tier

Evidence Quality Metadata

Rate Limit Strategy

Documentation Checklist

Sample JSON Responses

Guides

Setup

Help