Sign in

v2

latestOpenAPI 3.1.02026-08-0382170235.8 KB
ingestion

Ingest inline text into a POT

Submit raw text content for ingestion into a POT. The request returns immediately with a job_id (HTTP 202); the actual work — chunking, fact extraction, scoring, edge detection vs. the Constitution, score propagation — happens asynchronously.

Poll GET /jobs/{job_id} for progress and the final result. Typical small documents (< 5 KB) complete in 5–15 seconds; larger ones scale with chunk count.

Use this endpoint for: programmatic ingestion of text already in memory — snippets, structured exports, conversation summaries, ADR bodies, etc.

This endpoint's text limit is 100 KB (102,400 chars). It's enforced at the request schema level: an oversize content field returns 422 with a Pydantic validation error. The 100 KB ceiling is specific to this inline-text route — it is NOT a per-document limit on SciPot as a whole.

For documents larger than 100 KB, or for file formats SciPot needs to convert (PDF, DOCX, PPTX, XLSX, HTML), use the upload pipeline instead:

  1. POST /documents/upload (multipart/form-data, default 50 MB cap, auto-conversion via MarkItDown).
  2. POST /pots/{pot_id}/extract-from-document to extract facts from the stored document into one or more POTs.

Provenance: every fact extracted will carry the source block you provide here. Be specific (path, author, tags) — provenance is the audit trail your agents will rely on later.

post/pots/{pot_id}/ingest

Path parameters

pot_idstring uuid required

Request body

contentstring required

Document content (max 100KB)

languagestring nullable

ISO 639-1 override for extraction language. When provided, skips auto-detection and forces facts + edge rationales into this language. Falls back to POT default and then auto-detect when omitted.

Example request

{
  "content": "# Document Title\n\nContent here...",
  "source": {
    "author": "sebas",
    "created_at": "2026-01-07T10:00:00Z",
    "path": "docs/architecture.md",
    "type": "markdown"
  }
}

Response

Document ingestion queued; poll /jobs/{job_id} for progress

job_idstring uuid required

Unique identifier for this ingestion job

pot_idstring uuid required

Target POT ID

status'pending'

Job status (always 'pending' for initial response)

messagestring

Human-readable status message

Example response

{
  "job_id": "01JH8KQMW3PG0HXNZV2QRST9YZ",
  "message": "Document ingestion queued",
  "pot_id": "01JH8KQMW3PG0HXNZV2QRST9YX",
  "status": "pending"
}