SCscipot
ingestion

Extract facts from a stored document

Changed on

Re-extract facts from an already-stored document into a POT.

This allows extracting the same document into multiple POTs without re-uploading the content.

post/pots/{pot_id}/extract-from-document

Request

Path parameters

pot_idstring uuid required

Request body

document_idstring uuid required

ID of the stored document to extract from

idempotency_keystring nullable

Optional key that makes the request safe to repeat: within the workspace, a second request with the same key for the same POT and document answers with the job the first one queued instead of queuing another extraction. Use one key per extraction you mean to run (for example a hash of document, POT and profile). The same key for a different POT or document is a 409 IDEMPOTENCY_KEY_REUSED.

languagestring nullable

ISO 639-1 override for extraction language. When omitted, the selected profile's language applies, then the POT default, then auto-detect (request > profile > POT default > auto-detect).

context_attachment_idsstring[] nullable

Optional explicit list of context_attachment_ids to inject into the extraction prompt. None (default) = use all attachments on the document. Empty list = no context block. Cross-document or cross-workspace ids cause a 422 with ATTACHMENT_REF_INVALID. Duplicate ids are silently deduplicated (preserving first-occurrence order) so they don't double-count against caps or duplicate provenance.

profile_idstring uuid nullable

Extraction profile to apply (T4). Snapshotted into the job at enqueue time; every extracted fact records provenance.profile_id / provenance.profile_version. Profile language sits between this request's language and the POT default. Unknown in this workspace -> 422 PROFILE_NOT_FOUND.

source_authoritystring nullable

What kind of source the document is: a key of the POT's source types (GET /pots/{pot}/constitution/source-types). Its weight is the starting POT Score of the extracted facts (every type of the default catalog weighs 0.60). Omitted = the document's own source_authority when it has one that is an active type of this POT, else 0.50 as before; it wins over the profile's initial_pot_score. Unknown or switched off -> 422 SOURCE_TYPE_UNKNOWN / SOURCE_TYPE_INACTIVE. Named here and the document has none yet: the document records it.

original_datestring nullable

The document's date in this POT (ISO 8601, v0.7.80.0), stored as the POT's own date for the document (pot_original_dates): the extraction cites it and its facts hold from it. The document's original_date and every other POT's date are left as they are. A date that changes the POT's own also recomputes the valid_from of the document's facts already in this POT. Omitted = the POT's own date when it has one; else, for the first POT to take the document in while no POT has a date of its own for it, the document's original_date (stored as this POT's own); else none: a POT never reads another's date (v0.7.82.0).

endorsed_bystring uuid nullable

«Confío en esta fuente»: a contributor of this workspace (registered and active) vouches for the document. Every fact extracted from it starts Verified (POT Score 0.85 at least, the floor of an endorsed contribution) and records who vouched in provenance.sources[0]. An extraction profile alone never reaches Verified (initial_pot_score ≤ 0.79); this is the person's validation. Unknown or inactive -> 422 ENDORSER_INVALID. The integrator decides who may send it.

Response

Re-extraction queued

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