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, screen supplement safety, or build discovery experiences on top of the full intervention-outcome graph.

Start with the high-level routes when you are shipping product features quickly: product packs, ranked interventions, comparison endpoints, safety screening, bulk hydration, and release intelligence all reduce the amount of stitching logic you need to own.

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 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.

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-04-09T02:39:46.074Z.
Contract version: 1.0.0.
Snapshot id: snapshot.0e78bc69814bbd345e92.
Last supplement dataset update: 2026-04-08T23:20:44Z.
Last research dataset update: 2026-04-09T02:39:46.074Z.
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, and use /api/library/v1/releases plus /api/library/v1/changelog when you want a more decision-ready change feed.

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": "capability_missing",
  "message": "API token is missing required capabilities",
  "details": {
    "requiredCapabilities": ["diffs.read"],
    "tokenCapabilities": ["library.read"]
  }
}

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

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. Honor the `Retry-After` header.	Time based or support based recovery
400	invalid_query_param	Strict mode rejected one or more query parameters	Fix fields listed in `details.fields` or remove `strict=true` during migration.	Recoverable by request correction

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.

List endpoints support two validation modes. Default mode is lenient and may return warnings[] when parameters are invalid or clamped. Add strict=true to fail fast with 400 invalid_query_param.

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. Get a ranked intervention shortlist for an outcome

Outcome Ranking 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) Ask for a ranked shortlist instead of stitching edges yourself
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 for the top candidate you want to explain
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/interventions/INTERVENTION_ID/brief?minGrade=B&limit=5"

Expected Output Shape

json

{
  "outcomeID": "sleep-latency",
  "topCandidate": "l-theanine",
  "topScore": 84,
  "why": [
    "strongest linked grade is B",
    "6 linked studies across 600 participants"
  ]
}

2. Build a supplement product page fast

Use the product pack when your UI needs a curated bundle, then use bulk hydration for adjacent cards or comparison rails.

Supplement Product Pack Workflow

bash

# 1) Fetch a product-ready supplement 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 cards without N+1 detail requests
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"]}'

# 3) Render dose, safety, evidence highlights, and related entities from one response

Expected Output Shape

json

{
  "productPack": {
    "slug": "alpha-gpc",
    "coverageStatus": "complete",
    "topOutcome": "focus"
  },
  "bulkFound": 2,
  "acceptedIncludes": ["coverage", "identifiers"]
}

3. Compare ranked intervention candidates

Use ranked listings to narrow the field, then use the comparison endpoints to explain tradeoffs without writing scoring or overlap logic yourself.

Comparison Workflow

bash

# 1) Rank interventions for a condition
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 two candidates on the same outcome
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"]}'

# 3) Use the winner, shared outcomes, and score summary in your chooser UI

Expected Output Shape

json

{
  "rankedCount": 5,
  "comparisonWinner": "l-theanine",
  "sharedOutcomes": ["sleep-quality", "sleep-latency"],
  "reason": "L-theanine has stronger aggregate linked evidence"
}

4. Safety check before recommending a supplement

Use the safety screen endpoint when you need a machine-readable decision for a real user context instead of manually stitching interaction, assertion, and coverage calls together.

Use strictness=high_safety when you want coverage gaps to surface as insufficient_coverage instead of silently defaulting to a weaker answer.

Safety Check Workflow

bash

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"}
  }'

Expected Output Shape

json

{
  "overallDecision": "block",
  "results": [
    {
      "supplementID": "st-johns-wort",
      "decision": "block",
      "confidence": "medium",
      "blockers": [
        {
          "type": "interaction",
          "severity": "major",
          "reason": "serotonergic interaction risk",
          "target": { "id": "sertraline", "label": "Sertraline" },
          "sources": ["assertion.interaction.st-johns-wort.5fbb50ba372ebafc"]
        }
      ],
      "warnings": [],
      "coverage": {
        "status": "has_gaps",
        "gaps": ["Interaction target is free text and not yet mapped to external codes"]
      },
      "trace": {
        "assertionIDs": [
          "assertion.interaction.st-johns-wort.5fbb50ba372ebafc",
          "assertion.contraindication.st-johns-wort.6c9eb735d4aa0db4"
        ],
        "interactionFactIDs": [
          "assertion.interaction.st-johns-wort.5fbb50ba372ebafc"
        ],
        "coverageEntityID": "st-johns-wort"
      }
    }
  ]
}

5. Audit trail across data updates

Use releases and changelog for the fast answer, then fall back to raw diffs when you need exact entity-level action.

Audit Trail Workflow

bash

# 1) See the most recent classified releases
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/releases?limit=5"

# 2) Pull the human-readable changelog feed
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/changelog?limit=10"

# 3) Fetch exact diff rows when you need entity-level action
curl -sS -H "Authorization: Bearer $UAF_TOKEN" \
  "https://unfairapp.com/api/library/v1/diffs?fromSnapshotID=snap-2026-02&toSnapshotID=snap-2026-03&entityType=supplement"

Expected Output Shape

json

{
  "releaseSummary": "2 safety-impacting changes detected",
  "changelogKind": "safety",
  "recommendedAction": "review_safety_screening",
  "entityType": "supplement"
}

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-04-09T02:39:46.074Z
x-contract-version: 1.0.0
x-snapshot-id: snapshot.0e78bc69814bbd345e92
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.
For 429, use Retry-After to choose the next attempt window.
Conditional requests are available on /meta, /snapshots, and /diffs using ETag and If-None-Match. Current behavior still applies quota checks before a possible 304.
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-04-08T23:20:44Z",
      "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-04-09T02:39:46.074Z",
        "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.0e78bc69814bbd345e92",
      "supportedAssertionKinds": [
        "claim",
        "interaction",
        "contraindication",
        "avoid_if",
        "regulatory",
        "intervention_outcome"
      ],
      "artifactDigests": {
        "assertions": "sha256:...",
        "coverage": "sha256:..."
      },
      "validation": {
        "strictModeQueryParam": "strict",
        "routes": [
          {
            "path": "/api/library/v1/supplements",
            "requiredCapabilities": ["library.read"],
            "strictMode": {
              "supported": true,
              "queryParam": "strict",
              "enabledValue": "true",
              "defaultValue": false
            },
            "params": [
              { "name": "q", "type": "string" },
              { "name": "tier", "type": "grade", "enumValues": ["A", "B", "C", "D", "F"] },
              { "name": "limit", "type": "integer", "min": 0, "max": 200 }
            ]
          }
        ]
      }
    }
  }
}

Unfair Library API v1

Intro

Quickstart

Versioning and Freshness

Troubleshooting and Errors

Endpoints

Workflow Examples

1. Get a ranked intervention shortlist for an outcome

2. Build a supplement product page fast

3. Compare ranked intervention candidates

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