Ingest a Conversation Source

Before you begin

Roles required: Platform admin, operations user, support engineer.

You need the raw content of the source artifact you want to ingest. The content must be in one of the accepted formats: VTT, SRT, plain text, Markdown, HTML, PDF-derived text, or JSON. You must have a confirmed legal_basis value before you send the request — check with your legal or compliance team if you are unsure.

Assumed state: The Raw to Knowledge service is running and healthy. See Get Access and Prepare Your Workspace.

Steps

1. Choose the correct source_type for your file

Match your file format to the source_type string you will include in the request body:

File type	`source_type` value	Notes
WebVTT (`.vtt`)	`vtt`	Generated by Zoom, Microsoft Teams, Google Meet
SubRip (`.srt`)	`srt`	Common subtitle/caption format
Plain paragraphs	`plain_text`	Pasted text, support tickets, meeting notes
Markdown (`.md`)	`markdown`	Notes, SOPs, product docs
HTML (`.html`)	`html`	Exported KB pages, CMS content, support articles
PDF-derived text	`pdf`	Text extracted from a PDF; binary PDF bytes are not accepted
Structured JSON	`json`	Custom integrations; must provide segment-like entries

If you are unsure of your format, open the file in a text editor. VTT files begin with WEBVTT. SRT files begin with a sequence number (1) followed by a timecode line. JSON files begin with { or [.

2. Declare a legal basis for the content

Every artifact must include a legal_basis value. This declaration governs how the data may be processed and surfaced.

Value	When to use
`LEGITIMATE_INTEREST`	Internal business knowledge; analyst notes; internal support calls
`CONSENT`	Customer has explicitly consented to their conversation being used
`CONTRACT`	Processing is necessary to deliver a contracted service
`LEGAL_OBLIGATION`	Processing is required by law or regulation
`NOT_ASSESSED`	Legal basis has not been determined — blocks ingest

For most internal knowledge-capture use cases, LEGITIMATE_INTEREST is the appropriate default. If the source includes customer personal data (names, account details, identifiable content), consult your legal or compliance team before selecting a basis.

Important: If you submit legal_basis: "NOT_ASSESSED", the artifact will be blocked from processing. Segmentation will not run, and no candidates will be extracted. You must re-submit with a valid legal basis.

3. POST the artifact to /v1/artifacts

Send a POST request with a JSON body. The following example ingests a plain-text call transcript for the acme-corp customer scope.

curl -s -X POST http://localhost:8000/v1/artifacts \
  -H "Content-Type: application/json" \
  -d '{
    "source_system": "zoom",
    "source_type": "plain_text",
    "source_ref": "zoom-meeting-2026-06-01-acme",
    "raw_content": "Sales engineer: Our platform supports SSO via SAML 2.0 and OIDC. Customer: Does that include Azure AD? Sales engineer: Yes, Azure AD is a supported identity provider.",
    "legal_basis": "LEGITIMATE_INTEREST",
    "customer_scope": "acme-corp"
  }'

Required fields:

source_system — the originating system (e.g., zoom, teams, salesforce, support-portal)
source_type — one of vtt, srt, plain_text, markdown, html, pdf, json
source_ref — a unique identifier for this artifact in the source system; used for idempotency
raw_content — the full source text or structured content
legal_basis — one of the values listed in step 2

Optional fields:

customer_scope — scope identifier for customer-specific knowledge boundaries

Note: If you submit a source_ref that has already been ingested, the service returns 409 Conflict and does not create a duplicate artifact. This is intentional idempotency behavior. To re-ingest corrected content, use a new source_ref value.

4. Capture the artifact_id from the response

A successful ingest returns HTTP 201 with a response body like:

{
  "artifact_id": "art_01j2k3l4m5n6p7q8r9s0",
  "status": "processing",
  "source_ref": "zoom-meeting-2026-06-01-acme",
  "legal_basis": "LEGITIMATE_INTEREST",
  "customer_scope": "acme-corp",
  "created_at": "2026-06-07T14:32:00Z"
}

Save the artifact_id. You will use it to retrieve the extracted candidates in the next step.

5. Check the extracted candidates

After ingest, Raw to Knowledge runs segmentation asynchronously. Use the artifact_id to retrieve the candidates extracted from this artifact:

curl -s "http://localhost:8000/v1/candidates?artifact_id=art_01j2k3l4m5n6p7q8r9s0"

Allow a few seconds for segmentation to complete. The response is a paginated list of candidate objects. Each candidate includes a flow_type:

FLOW_A — a question-answer pair was detected; an answer is paired with the question
FLOW_B — a question was detected but no answer was found in the source; a generation work item is required to produce a draft answer

Result

The artifact is ingested, segmentation runs, and candidates are extracted. Privacy tagging is applied to each candidate based on content analysis. Each candidate has a flow_type indicating whether an answer is already available (FLOW_A) or needs to be generated (FLOW_B). The artifact record is retained for audit and provenance.

See also: Review Extracted Candidates; Classify a Candidate Answer