API Reference

Authentication

All API requests require authentication via an API key. Create API keys from your dashboard.

Include your key in the Authorization header:

Authorization: Bearer cg_your_api_key_here

API keys use the cg_ prefix. The key is hashed (SHA-256) on the server — CiteGuardian never stores your raw key after creation.

POST /api/verify

Submit an AI-generated answer and its claimed sources for verification.

Request Body

* Each source must have at least one of url or text.

Example — Sync Request

curl -X POST https://citeguardian.com/api/verify \
  -H "Authorization: Bearer cg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "The Earth orbits the Sun in 365.25 days [S1].",
    "sources": [
      {"id": "S1", "url": "https://example.com/astronomy"}
    ]
  }'

Response (200)

{
  "run_id": "abc12345def",
  "overall": {
    "supported_rate": 1.0,
    "total_claims": 1,
    "decorative_citations": 0,
    "contradictions_found": 0
  },
  "claims": [
    {
      "claim": "The Earth orbits the Sun in 365.25 days",
      "citations": ["S1"],
      "verdict": "supported",
      "confidence": 0.95,
      "contradiction": false,
      "scrub_test": {
        "p0": 0.5,
        "p1": 0.95,
        "delta": 0.45,
        "decorative": false
      },
      "evidence_chunk_ids": ["S1:C0"],
      "notes": "Source confirms orbital period."
    }
  ],
  "meta": {}
}

Gate Mode

Add "gate": true to get a simple pass/fail verdict instead of a full report. Designed for RAG pipelines that need to block hallucinated responses.

Example

curl -X POST https://citeguardian.com/api/verify \
  -H "Authorization: Bearer cg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "The speed of light is 300,000 km/s [S1].",
    "sources": [{"id": "S1", "url": "https://example.com/physics"}],
    "gate": true,
    "threshold": 0.8
  }'

Response (200)

{
  "pass": true,
  "supported_rate": 1.0,
  "threshold": 0.8,
  "total_claims": 1,
  "contradictions_found": 0,
  "decorative_citations": 0,
  "run_id": "abc12345def"
}

Pass Criteria

• supported_rate >= threshold (default threshold: 0.7)
• contradictions_found == 0

Both conditions must be met. A single contradiction causes a fail regardless of the supported rate.

Async Mode

Add a callback_url to receive results via webhook instead of waiting for the response.

Example

curl -X POST https://citeguardian.com/api/verify \
  -H "Authorization: Bearer cg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "AI text to verify [S1].",
    "sources": [{"id": "S1", "url": "https://example.com"}],
    "callback_url": "https://your-server.com/webhook"
  }'

Response (202 Accepted)

{
  "run_id": "abc12345def",
  "status": "processing"
}

When verification completes, results are POSTed to your callback_url. See Webhooks for the payload format.

POST /api/batch

Submit multiple verification requests at once. Processing happens in the background.

Format A — Bare Array

curl -X POST https://citeguardian.com/api/batch \
  -H "Authorization: Bearer cg_your_key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "answer": "Claim one [S1].",
      "sources": [{"id": "S1", "url": "https://example.com/1"}]
    },
    {
      "answer": "Claim two [S1].",
      "sources": [{"id": "S1", "url": "https://example.com/2"}]
    }
  ]'

Format B — Object with Callback

curl -X POST https://citeguardian.com/api/batch \
  -H "Authorization: Bearer cg_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"answer": "...", "sources": [{"id": "S1", "url": "..."}]},
      {"answer": "...", "sources": [{"id": "S1", "url": "..."}]}
    ],
    "callback_url": "https://your-server.com/batch-done"
  }'

Response (202 Accepted)

{
  "batch_id": "batch123abc",
  "total_items": 2,
  "poll_url": "/api/batch/batch123abc"
}

Maximum batch size: 50 items. Each item costs 1 credit.

GET /api/batch/<id>

Poll the status and results of a batch job.

Example

curl https://citeguardian.com/api/batch/batch123abc \
  -H "Authorization: Bearer cg_your_key"

Response (200)

{
  "batch": {
    "id": "batch123abc",
    "total_items": 2,
    "completed_items": 1,
    "failed_items": 0,
    "status": "processing",
    "created_at": "2025-01-15T10:30:00",
    "completed_at": null
  },
  "runs": [
    {
      "id": "run12345abc",
      "answer_preview": "Claim one [S1]...",
      "supported_rate": 1.0,
      "total_claims": 1,
      "status": "completed"
    }
  ]
}

The status field is one of: processing, completed, failed.

GET /api/credits

Check your current credit balance.

curl https://citeguardian.com/api/credits \
  -H "Authorization: Bearer cg_your_key"

Response (200)

{"credits": 42}

Webhooks

When you provide a callback_url, CiteGuardian POSTs results to your server when verification completes.

Success Payload

{
  "event": "verify.completed",
  "run_id": "abc12345def",
  "report": { ... }
}

Failure Payload

{
  "event": "verify.failed",
  "run_id": "abc12345def",
  "error": "Error description"
}

Gate Mode Webhook

When gate: true is set with a callback_url, the webhook includes a gate field:

{
  "event": "verify.completed",
  "run_id": "abc12345def",
  "report": { ... },
  "gate": {
    "pass": true,
    "supported_rate": 0.85,
    "threshold": 0.7,
    "contradictions_found": 0
  }
}

Retry Behavior

• 3 attempts with exponential backoff: 2s, 4s, 8s
• 10-second timeout per attempt
• Your endpoint should return a 2xx status to acknowledge receipt

Error Codes

All error responses return JSON:

{"error": "Description of what went wrong"}