Vendor API v1

Authentication

Every request MUST include an Authorization: Bearer <key> header. Live keys start with cs_live_; test keys with cs_test_. Both count against the same monthly cap for the key. Never embed a key in client-side code.

POST /api/v1/verify/citation

Verify a single citation. Optional quote field enables Layer 2 quote matching against the source opinion.

Request

POST /api/v1/verify/citation
Authorization: Bearer cs_live_...
Content-Type: application/json

{
  "citation": "Brown v. Board of Education, 347 U.S. 483 (1954)",
  "quote": "Separate educational facilities are inherently unequal."
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_...

{
  "request_id": "req_1a2b3c4d5e6f7890",
  "citation": "Brown v. Board of Education, 347 U.S. 483 (1954)",
  "result": {
    "normalized": "347 U.S. 483",
    "kind": "case",
    "outside_coverage": false,
    "existence": {
      "verdict": "VERIFIED",
      "explanation": "Case exists at the cited reporter volume and page.",
      "case_name": "Brown v. Board of Education",
      "source_url": "https://www.courtlistener.com/...",
      "checked_via": "courtlistener"
    },
    "quote": {
      "verdict": "QUOTE CONFIRMED",
      "explanation": "Quoted text matches the opinion.",
      "match_type": "exact"
    }
  },
  "billing": {
    "citations_billed": 1,
    "billed_cents": 5,
    "month_to_date_citations": 123,
    "month_to_date_cents": 615
  }
}

Billing: $0.05/citation for the first 10,000 per calendar month per key; $0.03 above. Every request is billed a minimum of one citation.

POST /api/v1/verify/document

Extract every citation from a block of text and verify each. Optional quotes array (strings) enables Layer 2 quote matching for claimed quotations paired with their nearest citation.

Request

POST /api/v1/verify/document
Authorization: Bearer cs_live_...
Content-Type: application/json

{
  "text": "The court held that separate is inherently unequal. Brown v. Board of Education, 347 U.S. 483 (1954). See also Miranda v. Arizona, 384 U.S. 436 (1966).",
  "quotes": ["Separate educational facilities are inherently unequal."]
}

Response shape: { request_id, citations_found, summary: {verified, not_found, unconfirmed, outside_coverage}, citations: [...], billing }. Each element of citations has the same shape as the result object above.

Max input size: 64,000 characters. Larger payloads should be chunked client-side.

GET /api/v1/usage

Snapshot of the current calendar-month usage for the calling key.

Request

GET /api/v1/usage
Authorization: Bearer cs_live_...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key_prefix": "cs_live_aB3xQ7Zk",
  "vendor_name": "Acme Legal AI",
  "status": "active",
  "month_to_date": { "citations": 4123, "billed_cents": 20615 },
  "monthly_cap_cents": 50000,
  "overage_billing_enabled": false,
  "remaining_cents": 29385
}

Error codes

• 400 invalid_json / missing_field / citation_too_long — bad request shape.
• 401 unauthorized — missing, malformed, or unknown API key.
• 402 monthly_cap_reached — key hit its monthly cap and overage billing is off.
• 403 key_paused — key is paused; contact support to resume.
• 405 method_not_allowed — wrong HTTP verb.
• 500 db_insert_failed / 503 server_unconfigured — server side.

Verdict vocabulary

The existence.verdict string is one of: VERIFIED, NOT FOUND, UNCONFIRMED, UNCONFIRMED — OUTSIDE COVERAGE, RETRACTED. The quote.verdict string is one of: QUOTE CONFIRMED, QUOTE NOT FOUND, SOURCE UNAVAILABLE. Layer 3 (proposition support) is not exposed on the vendor API — verification is deterministic only.