Capsule API

A free, read-only API for researchers and institutions to pull Capsule's verified, classified knowledge programmatically. Public capsules only. Reads work with no key at 60 requests per minute per IP, and it is open for cross-origin (CORS) use. A free per-partner API key raises the limit to 600 requests per minute and attributes your usage.

Base URL

https://joincapsule.org/api/v1

Authentication and API keys

Reads are open. Passing a key simply raises your rate limit from 60 to 600 requests per minute and lets us attribute (and support) heavier use. Send it either as a Bearer token or in the X-API-Key header.

curl "https://joincapsule.org/api/v1/capsules?limit=2" \
  -H "Authorization: Bearer cap_xxxxxxxxxxxx"

# or
curl "https://joincapsule.org/api/v1/capsules?limit=2" \
  -H "X-API-Key: cap_xxxxxxxxxxxx"

Confidence rating

Every capsule carries an epistemic classification, returned both as a label and as a numeric confidence on a 1 to 5 truth scale: Debunked 1, Contested 2, Hypothesis 3, Theory 4, Fact and Proven 5. Books are not claims and have no rating.

List capsules

GET /api/v1/capsules

Query parameters (all optional):
  classification   FACT | PROVEN | THEORY | HYPOTHESIS | CONTESTED | DEBUNKED
  category         filter by category
  domainTag        filter by a domain tag (e.g. country)
  q                search titles
  limit            page size, max 100 (default 25)
  offset           pagination offset

Example:
  curl "https://joincapsule.org/api/v1/capsules?classification=FACT&limit=2"

Get one capsule

By slug (preferred) or id. Returns the full content, sources, and the confidence status history.

GET /api/v1/capsules/{slug-or-id}

Example:
  curl "https://joincapsule.org/api/v1/capsules/peru"

Response shape

{
  "data": {
    "type": "capsule",
    "id": "…",
    "attributes": {
      "title": "Peru",
      "slug": "peru",
      "url": "https://joincapsule.org/capsules/peru",
      "classification": "FACT",
      "confidence": { "value": 5, "bestValue": 5, "worstValue": 1, "label": "Fact" },
      "category": "geography",
      "domainTags": ["country", "south-america"],
      "author": "…",
      "publishedAt": "…",
      "updatedAt": "…",
      "content": "…",
      "sources": [{ "title": "…", "url": "…" }],
      "statusHistory": [
        { "from": "HYPOTHESIS", "to": "THEORY", "at": "…", "reason": "…", "by": "…" }
      ]
    },
    "links": { "self": "https://joincapsule.org/api/v1/capsules/peru" }
  }
}

Terms

The API serves public content for research and non-commercial reuse; please attribute Capsule and link back to the capsule URL. See the Policy and Terms. To discuss a partnership or higher rate limits, reach us via Feedback.