Skip to content

API.md

Latest commit

 

History

History
220 lines (170 loc) · 3.32 KB

API.md

File metadata and controls

220 lines (170 loc) · 3.32 KB

Executable Claims API Documentation

Base URL

http://localhost:8000/api/v1

Authentication

Currently no authentication is required. In production, implement API key or OAuth2.

Endpoints

Health Check

GET /health

Check API health status.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00Z"
}

Analyze Manuscript

POST /analyze

Submit manuscript text for claim analysis.

Request Body:

{
  "text": "Our model achieves 95% accuracy...",
  "bibliography": {
    "bibtex": "...",
    "entries": [...]
  },
  "project_context": {
    "repo_path": "/path/to/repo",
    "figures": ["fig1.png"],
    "data_files": ["data.csv"],
    "notebooks": ["analysis.ipynb"]
  },
  "extract_counterevidence": true,
  "generate_capsules": false,
  "max_claims": 50
}

Response:

{
  "analysis_id": "uuid-here",
  "status": "processing",
  "claims_count": 0,
  "message": "Analysis started..."
}

Get Analysis Result

GET /analysis/{analysis_id}

Retrieve analysis results by ID.

Response:

{
  "analysis_id": "uuid",
  "status": "completed",
  "claims": [
    {
      "id": "claim-uuid",
      "text": "Our model achieves 95% accuracy",
      "start_char": 0,
      "end_char": 32,
      "claim_type": "quantitative",
      "confidence": 0.95,
      "numeric_values": [
        {
          "value": 95.0,
          "unit": "%"
        }
      ],
      "weasel_words": [],
      "cited_works": [],
      "status": "verified"
    }
  ],
  "evidence_map": {
    "claim-uuid": [
      {
        "id": "evidence-uuid",
        "claim_id": "claim-uuid",
        "source": {
          "type": "cited_paper",
          "title": "Paper Title",
          "authors": ["Author 1"],
          "year": 2024
        },
        "spans": [
          {
            "text": "Evidence text..."
          }
        ],
        "entailment_score": 0.85,
        "retrieval_score": 0.92
      }
    ]
  },
  "capsules": [],
  "stats": {
    "total_claims": 5,
    "verified_claims": 3,
    "pending_claims": 2
  },
  "processing_time_ms": 5432.1
}

Get Claim Details

GET /claims/{claim_id}

Get detailed information for a specific claim.

Response:

{
  "id": "claim-uuid",
  "text": "...",
  "evidence": [...]
}

Re-run Capsule

POST /claims/{claim_id}/rerun

Execute the evidence capsule for a claim.

Response:

{
  "capsule_id": "uuid",
  "status": "passed",
  "result": "pass",
  "logs": "pytest output...",
  "test_results": [
    {
      "test_name": "test_efficacy",
      "status": "passed",
      "duration_ms": 234.5
    }
  ],
  "duration_ms": 1234.5
}

Download Capsule

GET /capsule/{claim_id}/download?format=python

Download capsule file.

Query Parameters:

  • format: python or jupyter

Response: File download

Error Responses

All endpoints return standard error responses:

{
  "detail": "Error message here"
}

Status Codes:

  • 200 - Success
  • 400 - Bad Request
  • 404 - Not Found
  • 500 - Internal Server Error

Rate Limiting

No rate limiting currently. Implement in production.

Webhooks (Future)

For real-time updates, use Server-Sent Events:

POST /stream/analyze

Stream analysis progress in real-time.