A

API Reference

Quick Start

1. Create an API key in Settings.

2. Include it in the Authorization header:

curl https://api.alexandrialibraries.com/api/v1/libraries \
  -H "Authorization: Bearer ak_your_key_here"

All responses use JSON. Errors return { error: { code, message } }.

Authentication

API keys use the ak_ prefix. Keys have scopes that control access:

read

List and search libraries

verify

Run claim verification

write

Add claims to libraries

Public endpoints (listing public libraries) work without authentication but have stricter rate limits.

Rate Limits

Every response includes rate limit headers:

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 97

X-RateLimit-Reset: 42

Unauthenticated

60 requests/minute

Authenticated

100 requests/minute (configurable)

Endpoints

GET/api/v1/libraries

List public and system libraries. Authenticated users also see their own.

curl "https://api.alexandrialibraries.com/api/v1/libraries?limit=10" \
  -H "Authorization: Bearer ak_..."

# Response
[
  {
    "slug": "scifact",
    "name": "SciFact",
    "description": "Biomedical claims...",
    "claim_count": 45911,
    "visibility": "public",
    ...
  }
]
GET/api/v1/libraries/{slug}

Get details of a single library by slug.

curl "https://api.alexandrialibraries.com/api/v1/libraries/scifact" \
  -H "Authorization: Bearer ak_..."
GET/api/v1/libraries/{slug}/claims

Paginated list of claims in a library.

curl "https://api.alexandrialibraries.com/api/v1/libraries/fever/claims?offset=0&limit=20" \
  -H "Authorization: Bearer ak_..."

# Response
{
  "library_slug": "fever",
  "claims": [{"id": "...", "claim_text": "...", ...}],
  "offset": 0,
  "limit": 20,
  "total": 108680
}
GET/api/v1/libraries/{slug}/searchread

Semantic search within a library. Embeds your query and returns nearest claims by cosine similarity.

curl "https://api.alexandrialibraries.com/api/v1/libraries/scifact/search?q=mRNA+vaccine+efficacy&top_k=5" \
  -H "Authorization: Bearer ak_..."

# Response
{
  "library_slug": "scifact",
  "query": "mRNA vaccine efficacy",
  "results": [
    {"claim_text": "...", "similarity": 0.8734, "claim_id": "..."},
    ...
  ]
}
POST/api/v1/verifyverify

Verify text against selected libraries. Extracts claims, decomposes into subclaims, checks each against libraries, returns consensus. Deducts credits.

curl -X POST "https://api.alexandrialibraries.com/api/v1/verify" \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The Earth is approximately 4.5 billion years old.",
    "library_slugs": ["scifact", "fever"]
  }'

# Response
{
  "claim_groups": [
    {
      "parent_claim": "The Earth is approximately 4.5 billion years old.",
      "subclaims": [
        {
          "claim_text": "The Earth is approximately 4.5 billion years old.",
          "consensus": "consensus_support",
          "density": {"total_supporting": 3, "total_contradicting": 0, ...},
          "library_results": [...]
        }
      ],
      "overall_consensus": "consensus_support"
    }
  ],
  "total_claims": 1,
  "total_subclaims": 1,
  "credits_used": 1
}
POST/api/v1/libraries/{slug}/claimswrite

Add claims to a library you own. Creates a new version.

curl -X POST "https://api.alexandrialibraries.com/api/v1/libraries/my-library/claims" \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "claims": [
      "Water boils at 100 degrees Celsius at sea level.",
      "Light travels at approximately 299,792 km/s."
    ],
    "change_summary": "Added physics facts"
  }'

# Response
{
  "library_slug": "my-library",
  "claims_added": 2,
  "new_version": 3
}

Consensus Values

The consensus field in verification results uses these values:

consensus_supportMultiple libraries agree the claim is supported
consensus_contradictionEvidence contradicts the claim
contestedSome libraries support, others contradict
inconclusiveRelated evidence found but no clear consensus
not_coveredNo relevant evidence found in selected libraries

Credits

Verification (POST /api/v1/verify) deducts credits from the API key owner's account. If verification fails, credits are automatically refunded. Every account receives 50 free credits a day.

Key Management

Manage API keys in Settings or via these endpoints (Firebase auth only, not API key auth):

POST/api/keys

Create a new API key. The raw key is returned only once.

curl -X POST "https://api.alexandrialibraries.com/api/keys" \
  -H "Authorization: Bearer <firebase_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "production", "scopes": ["read", "verify"]}'
GET/api/keys

List all your API keys (raw keys not included).

DELETE/api/keys/{id}

Revoke an API key immediately.