SCscipot
extraction-preview

Preview what a profile would extract from a text (nothing is stored)

Changed on

Run the extraction pipeline on content synchronously and return the facts a real ingestion would create — with their POT score, provenance, classification and (when scope-aware) scope fields — without persisting anything: no facts, no Document, no job, no vectors, no edges. The only durable trace is the usage event (operation=extraction_preview), which counts against the workspace's monthly token quota like an ingestion.

Profile: pass profile_id (a stored profile of this workspace, snapshotted exactly as /ingest does) or profile (an inline lever body, applied once and never stored — iterate on levers before saving them). The response's profile_applied says which levers shaped the extraction and where they came from.

What it does not do: constitution edge detection and score propagation (score_stage is initial, edges is null), and deduplication against the facts already in the POT (dedup_scope is batch+constitution), and the near-duplicate judge (a similar fact is discarded only when its text is identical; the others are listed in extraction_audit.near_duplicates_kept as undecided, no_judge), so a real ingestion may keep fewer facts than shown.

Limits: content at most 12288 characters (413), 45 s server-side ceiling (504), 4 concurrent previews per API process (429) and a per-integrator route limit on top of the global one (429). A chunk whose extraction fails is reported in errors[] with partial: true; when nothing at all could be extracted the call fails with 502 and the same error code a job would carry.

Error shapes: the gates this route shares with /ingest (404 POT, 422 PROFILE_NOT_FOUND, 429 TOKEN_QUOTA_EXCEEDED, the rate limiter's 429) answer {"detail": ...} like that route; the preview's own gates (413, 429 PREVIEW_CONCURRENCY_LIMIT, 500, 502, 503 LLM_NOT_CONFIGURED, 504) answer the {"error": {code, message, fix, retryable, ...}} envelope.

post/pots/{pot_id}/extract/preview

Request

Path parameters

pot_idstring uuid required

Headers

X-Contributor-IDstring nullable

Optional contributor (UUID) the usage events are attributed to, as on /ingest. A value that is not an active contributor of the workspace is ignored; billing never depends on it.

Request body

contentstring required

Text to preview (plain text or Markdown). At most 12288 characters (also reported as limits.max_content_chars); longer content is refused with 413 PREVIEW_CONTENT_TOO_LARGE. The cap is enforced by the route, not by schema validation, so the schema deliberately declares no maxLength: a generated client must not pre-empt the 413 with its own 422.

languagestring nullable

ISO 639-1 override for the extraction language. Same ladder as /ingest: request > profile > POT default > auto-detect.

profile_idstring uuid nullable

A stored extraction profile of this workspace to apply. Unknown here -> 422 PROFILE_NOT_FOUND. Mutually exclusive with profile.

include_unmaskedboolean

T9 — when the PII layer masked a fact, also return the fact as it was before masking (facts[].pii.unmasked_content), for a side-by-side view at the cost of one extraction. The text came from this same request and nothing is persisted, so nothing new is disclosed.

Example request

{
  "content": "# Master Services Agreement\n\nThe liability cap is 12 months of fees.",
  "profile": {
    "business_relevance": "Liability caps, SLAs and termination rights.",
    "granularity": "fine",
    "language": "en",
    "name": "Legal (draft)"
  }
}

Response

The facts the pipeline would create; nothing was stored

pot_idstring uuid required
persistedfalse

Always false: a preview writes nothing but its usage event

score_stage'initial' | 'propagated'

initial — the POT score each fact would be created with. Constitution edge detection and score propagation do not run in a preview in this release; propagated is reserved for the release that adds them.

dedup_scope'batch+constitution'

Deduplication crossed the previewed facts with each other and with the POT's constitution only — NOT with the facts already in the POT (the preview uses an empty disposable store). A real ingestion also dedups against the POT's existing facts and asks the near-duplicate judge (the preview discards only identical text), so it may keep fewer facts than shown.

language_appliedstring nullable

Extraction language after the ladder (request > profile > POT default > auto-detect) — the language on every fact.

content_charsinteger required
processing_time_msinteger required
detailstring nullable

Why nothing would be stored, when no fact survived and no chunk failed (same as the job's result.detail). Since v0.7.103.0.

detail_code'all_filtered' | 'no_facts_found' | 'all_withheld' | 'all_duplicates' nullable

Machine-readable form of detail. Since v0.7.103.0.

partialboolean required

True when chunking.chunks_failed > 0: the text was only partially extracted.

Example response

{
  "document_context": {
    "document_type": "technical",
    "key_entities": [
      "POT Index",
      "SciPot",
      "certainty scores",
      "facts",
      "provenance"
    ],
    "language": "en",
    "main_themes": [
      "scoring system",
      "knowledge validation",
      "certainty measurement"
    ],
    "title": "POT Index Specification"
  },
  "extraction_audit": {
    "discarded": 8,
    "discarded_facts": [],
    "kept": 12,
    "total_extracted": 20
  }
}

Changes

  • 87bd973b9c0fRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 0fb6ed61ba72Revision changes
    • warning

      added the new restates enum value to the /// response property for the response status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status