REST API v1

Authentication and retries

Send Authorization: Bearer lsa_…. Paid POST endpoints also require an 8–128 character Idempotency-Key. Retry a timeout with the same key and identical body; a different body with the same key returns HTTP 409.

Every response includes billing.credits_charged. Errors, provider failures, and zero-result searches charge 0 credits.

Examples

curl https://litsource.net/api/v1/evidence/search \
  -H "Authorization: Bearer $LITSOURCE_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-$(date +%s)" \
  -d '{"query":"Aspirin reduces cardiovascular events","max_hits":5}'

const response = await fetch("https://litsource.net/api/v1/evidence/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LITSOURCE_AGENT_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ query: "Aspirin reduces cardiovascular events", max_hits: 5 }),
});
console.log(await response.json());

import os, uuid, requests

response = requests.post(
    "https://litsource.net/api/v1/references/verify",
    headers={
        "Authorization": f"Bearer {os.environ['LITSOURCE_AGENT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"references": ["Smith J. Example study. Nature. 2024."]},
)
print(response.json())

Errors

Common codes: INVALID_TOKEN (401), INSUFFICIENT_CREDITS (402), SCOPE_DENIED (403), IDEMPOTENCY_KEY_CONFLICT (409), and CREDIT_CHECK_FAILED (503). All error envelopes include billing.credits_charged: 0.

Use cases

• Verify citations inside your coding agent. Paste a draft reference list and ask Cursor or Codex to run litsource_verify_references — it flags fabricated or mismatched citations before they reach your paper.
• Fact-check a claim while writing. Ask Claude to call litsource_search_evidence on a sentence like "aspirin reduces cardiovascular events" and get real PubMed / Crossref evidence supporting or challenging it.
• Build a citation-checking workflow. Use the REST API to verify references in bulk, read results back with GET /api/v1/runs/{id}, and monitor spend with GET /api/v1/usage.

Credits & pricing

Every Agent API and MCP call is metered in LitSource credits. You are only charged when a call produces a usable result — failures and zero-result searches cost nothing.

Free accounts can verify up to 10 references per call; verifying more requires Pro or Trial. Retrying the same request with the same idempotency key returns the cached result without charging again.

Response format

Every successful call returns a uniform envelope with data, billing, and meta:

{
  "data": {
    "results": [
      { "title": "…", "doi": "10.…", "pmid": "…", "relevance": 0.94 }
    ]
  },
  "billing": {
    "credits_charged": 1,
    "balance_after": 99,
    "reused": false
  },
  "meta": {
    "request_id": "my-search-001",
    "quality_version": null
  }
}

Failures never charge credits — billing.credits_charged is always 0:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient LitSource credits",
    "details": { "remaining_credits": 2, "required_credits": 3 }
  },
  "billing": { "credits_charged": 0 }
}

Limits & quotas

• Max 100 references per verification.
• Free plan: 10 references per verification call.
• Idempotency key: 8–128 characters, [A-Za-z0-9._:-].
• No daily credit limit and no rate limit — your credit balance is the only cap. Calls fail with INSUFFICIENT_CREDITS once depleted.