SCscipot
ingestion

Ingest inline text into a POT

Changed on

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.

Extraction profile: pass profile_id (see /profiles) to apply a named bundle of levers. The profile is snapshotted into the job at enqueue time, and every fact records provenance.profile_id / provenance.profile_version. Language precedence: request > profile > POT default > auto-detect.

post/pots/{pot_id}/ingest

Request

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. When omitted, the selected profile's language applies, then the POT default, then auto-detect (request > profile > POT default > auto-detect).

profile_idstring uuid nullable

Extraction profile to apply (T4). Its levers are snapshotted into the job at enqueue time and every extracted fact records provenance.profile_id / provenance.profile_version. Profile language sits between this request's language and the POT default in the precedence ladder. A profile that does not exist in this workspace returns 422 with PROFILE_NOT_FOUND.

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

replayedboolean

True when the request repeated an idempotency_key and this is the job the first request queued: nothing new was queued, and the job may already have finished (read it at GET /jobs/{job_id})

Example response

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

Changes