chunking_strategies_evaluation/docs/api-reference.md

API Reference

Complete documentation of all REST API endpoints.

---

Base URL

http://localhost:8000

---

Endpoints

Documents

GET /documents

List all uploaded documents.

Response:

{
  "items": [
    {
      "id": "doc-abc123",
      "filename": "insurance.docx",
      "paragraph_count": 245,
      "chunk_counts": {
        "recursive": 218,
        "fixed_size": 117
      },
      "created_at": "2026-07-25T10:00:00"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

---

POST /documents

Upload a document (.docx or .doc).

Request:

• Content-Type: multipart/form-data
• Body: file (binary)

Response (201):

{
  "id": "doc-abc123",
  "filename": "insurance.docx",
  "paragraph_count": 245,
  "chunk_counts": {},
  "created_at": "2026-07-25T10:00:00"
}

---

DELETE /documents/{doc_id}

Delete a document and its vectors.

Response:

{
  "deleted": true,
  "document_id": "doc-abc123"
}

---

POST /documents/{doc_id}/process

Run chunking strategies on a document.

Query parameters:

• background (bool, default false) — when true, enqueue processing and return 202 with a job_id; poll GET /jobs/{job_id}.

Request:

{
  "strategies": [
    "recursive",
    "fixed_size",
    "semantic",
    "contextual_retrieval",
    "semantic_parent_child"
  ]
}

Response:

{
  "document_id": "doc-abc123",
  "strategies_completed": [
    {
      "strategy": "recursive",
      "status": "completed",
      "chunks_produced": 218
    }
  ],
  "strategies_failed": []
}

---

Strategies

GET /strategies

List all available chunking strategies.

Response:

{
  "strategies": [
    {
      "name": "recursive",
      "description": "Cascade splitting: headers > double newline > ..."
    },
    {
      "name": "fixed_size",
      "description": "Fixed-size token splitting with overlap"
    }
  ]
}

---

Queries

POST /queries

Ask a question against a document using a specific strategy.

Request:

{
  "document_id": "doc-abc123",
  "strategy": "recursive",
  "question": "What are the main topics?",
  "top_k": 5
}

Response (201):

{
  "query_id": "q-xyz789",
  "document_id": "doc-abc123",
  "strategy": "recursive",
  "question": "What are the main topics?",
  "answer": "The document covers insurance regulations...",
  "retrieved_chunks": [
    {
      "chunk_id": "recursive_doc_000045",
      "score": 0.892,
      "text": " chunk content...",
      "parent_id": null
    }
  ],
  "latency_breakdown": {
    "embed_seconds": 0.15,
    "search_seconds": 0.02,
    "answer_seconds": 1.23,
    "total_seconds": 1.40
  },
  "token_usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 150,
    "total_tokens": 1400
  },
  "created_at": "2026-07-25T12:00:00"
}

---

GET /queries/{query_id}

Retrieve a past query.

Response: Same as POST /queries response.

---

Benchmarks

POST /benchmarks

Run a benchmark comparing multiple strategies.

Query parameters:

• background (bool, default false) — when true, enqueue the run and return 202 with a job_id; poll GET /jobs/{job_id} for status and result.

Request:

{
  "document_id": "doc-abc123",
  "strategies": ["recursive", "fixed_size", "semantic"],
  "questions_file": "files/questions.json",
  "top_k": 5,
  "dry_run": false
}

Response (201):

{
  "experiment_id": "exp-abc123",
  "document_id": "doc-abc123",
  "strategies_used": ["recursive", "fixed_size", "semantic"],
  "questions_count": 21,
  "aggregate_metrics": {
    "recursive": {
      "avg_context_relevance": 8.5,
      "avg_answer_similarity": 7.8,
      "avg_faithfulness": 9.2,
      "hallucination_rate": 0.05,
      "total_questions": 21,
      "failed_questions": 0
    }
  },
  "best_strategy": "recursive",
  "total_latency_seconds": 120.5,
  "estimated_cost_usd": 0.22,
  "created_at": "2026-07-25T12:00:00"
}

---

GET /benchmarks/{experiment_id}

Retrieve experiment results.

Response: Same as POST /benchmarks response.

---

GET /benchmarks/{experiment_id}/report

Generate HTML report.

Query Parameters:

• view: managerial (default) or technical

Response: HTML page

---

GET /experiments

List all experiments.

Response:

{
  "items": [
    {
      "id": "exp-abc123",
      "document_id": "doc-abc123",
      "strategies_used": ["recursive", "fixed_size"],
      "created_at": "2026-07-25T12:00:00"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

---

Jobs

Background execution for long-running benchmarks and document processing (FastAPI BackgroundTasks + SQLite job records).

GET /jobs

List jobs (newest first).

Query parameters: job_type, status, offset, limit

GET /jobs/{job_id}

Poll job status. When status is completed, result contains the same payload as the synchronous endpoint would return; when failed, error is set.

Response (202 enqueue body from POST with background=true):

{
  "job_id": "abc123",
  "job_type": "benchmark",
  "status": "pending",
  "poll_url": "/jobs/abc123"
}

---

Error Responses

All errors return:

{
  "detail": "Error message",
  "type": "ErrorClassName"
}

Status Code	Error Type	Description
400	ChunkingError	Invalid request
400	QueryError	Query failed
400	BenchmarkError	Benchmark failed
404	QueryError	Resource not found
422	ValidationError	Invalid request body

---

Rate Limits

None configured. For production, consider adding rate limiting.

---

Authentication

None configured. For production, add API key or OAuth2 authentication.