API Reference

Complete REST API documentation for TruthKeeper. All endpoints accept and return JSON.

Base URL

http://localhost:8000/api/v1

Authentication

API requests require authentication via API key in the header:

curl -H "Authorization: Bearer tk_your_api_key" \
  http://localhost:8000/api/v1/claims

Generate an API key using the CLI:

truthkeeper api-key create --name "my-app"

Claims

Create Claim

POST /api/v1/claims

Create a new claim with optional evidence and dependencies.

Request Body

{
  "content": "string (required) - The factual assertion",
  "evidence": [
    {
      "source": "string - URI of the evidence source",
      "type": "CODE | DOCUMENTATION | API | USER_INPUT",
      "excerpt": "string - Relevant excerpt from source"
    }
  ],
  "dependencies": [
    {
      "target": "string - URI or claim ID this depends on",
      "type": "HARD | SOFT | DERIVED"
    }
  ],
  "metadata": {
    "tags": ["string"],
    "custom_field": "any"
  }
}

Response

{
  "id": "clm_abc123",
  "content": "The UserService class handles authentication",
  "state": "HYPOTHESIS",
  "confidence": null,
  "evidence": [...],
  "dependencies": [...],
  "created_at": "2026-01-21T10:00:00Z",
  "updated_at": "2026-01-21T10:00:00Z"
}

Get Claim

GET /api/v1/claims/{claim_id}

Retrieve a claim by ID.

Query Parameters

Search Claims

GET /api/v1/claims/search

Semantic search over claims.

Query Parameters

Response

{
  "claims": [
    {
      "id": "clm_abc123",
      "content": "...",
      "state": "SUPPORTED",
      "confidence": 0.92,
      "score": 0.87
    }
  ],
  "total": 42,
  "has_more": true
}

Update Claim

PATCH /api/v1/claims/{claim_id}

Update a claim's content or metadata. Creates a new version.

Delete Claim

DELETE /api/v1/claims/{claim_id}

Soft-delete a claim. The claim becomes invisible but history is preserved.

Get Stale Claims

GET /api/v1/claims/stale

Get all claims that need reverification due to source changes.

Sources

Register Source

POST /api/v1/sources

Register an external source for change tracking.

Request Body

{
  "uri": "file://src/services/user.py",
  "type": "FILE | URL | GIT",
  "metadata": {
    "branch": "main",
    "commit": "abc123"
  }
}

Notify Source Changed

POST /api/v1/sources/changed

Notify TruthKeeper that a source has changed. Triggers staleness cascade.

Request Body

{
  "uri": "file://src/services/user.py",
  "change_type": "MODIFIED | DELETED | RENAMED",
  "new_uri": "file://src/services/auth.py",
  "diff": "optional diff content"
}

Response

{
  "affected_claims": 5,
  "claims": [
    {
      "id": "clm_abc123",
      "old_state": "SUPPORTED",
      "new_state": "STALE"
    }
  ]
}

Verification

Verify Claim

POST /api/v1/claims/{claim_id}/verify

Trigger verification for a claim.

Request Body

{
  "strategies": ["MINICHECK", "AST", "CORROBORATION"],
  "force": false
}

Response

{
  "claim_id": "clm_abc123",
  "old_state": "HYPOTHESIS",
  "new_state": "SUPPORTED",
  "confidence": 0.89,
  "verification_results": [
    {
      "strategy": "MINICHECK",
      "score": 0.92,
      "details": {...}
    },
    {
      "strategy": "AST",
      "score": 0.85,
      "details": {...}
    }
  ]
}

Human Reviews

Get Review Queue

GET /api/v1/reviews

Get claims awaiting human review.

Query Parameters

Submit Review

POST /api/v1/reviews/{review_id}

Submit a human review decision.

Request Body

{
  "decision": "APPROVE | REJECT | MODIFY",
  "new_content": "Modified claim content (if decision=MODIFY)",
  "reason": "Review notes",
  "reviewer": "reviewer@example.com"
}

Export / Import

Export to JSONL

GET /api/v1/export/jsonl

Export all claims as JSONL for version control or backup.

Query Parameters

Import from JSONL

POST /api/v1/import/jsonl

Import claims from JSONL. Handles conflicts based on strategy.

Query Parameters

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "CLAIM_NOT_FOUND",
    "message": "Claim with ID clm_abc123 not found",
    "details": {...}
  }
}

Error Codes

Rate Limits

SDKs

• Python SDK
• CLI Reference