Starting the Ingest Process

Discover how to create documents from uploaded files and initiate the ingestion process using the Vulgate API.

Creating a document and initiating an ingest job

To create a new document from the uploaded file(s) and initiate a job, make a request to the following endpoint:

POST /api/jobs

Request schema

The request body must include either files or document_id:

* Either files or document_id must be provided, but not both.

The created document’s document_format is set automatically on the server from the first uploaded file’s content type; this field is not part of the request body.

Response

The response contains the created document_id and job_id:

{ "document_id": "doc-xyz789", "job_id": "job-abc123" }

Errors

Example

curl -X POST "https://vulgate.ai/api/jobs" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{ "id": "<file-id-from-upload>" }],
    "ingest_mode": "pro",
    "scope": "organization",
    "document_metadata": { "language": "la", "publisher": "Typis Vaticanis" }
  }'

Processing tiers

The ingest_mode field selects the processing tier. Two tiers are available:

Notes:

• If ingest_mode is omitted, standard is used.
• All files in a pro job must be PDFs or images (application/pdf or image/*); other content types are rejected with an error.
• Other ingest_mode values exist in the schema for legacy and internal use. Requests using a tier that is not enabled for your team fail with "This ingest mode is no longer available for new uploads.".

Models

You no longer choose a model directly — each processing tier maps to a fixed, curated processing engine, and the model request field is ignored. Audio and video files are always routed to speech-to-text transcription regardless of tier.

Pipelines

The pipeline field selects how extracted content is structured:

Omit the field unless you have a specific reason not to: new jobs default to "tei".

Document metadata

The optional document_metadata object sets metadata on the newly created document. All fields are optional:

document_metadata only applies when a new document is created (files flow). Reprocessing with document_id ignores it — use PATCH /api/documents/{document_id} to change metadata on an existing document.

Audio options

For audio and video files, audio_options controls the processing performed:

Both fields are required when audio_options is present.

Monitoring job progress

Poll the jobs endpoint to track a job until it finishes:

GET /api/jobs?job_id={job_id}

The response contains a data array of job rows (including status), plus count and pageCount. The statuses you will typically observe are pending → processing → processed (ready to finalize), or error if processing failed (the row’s status_text describes the failure).

Finalizing the document

Creating a job starts processing. Once the job reaches the processed status, finalize the document to generate its searchable parts (embeddings) and publish it:

POST /api/jobs/{job_id}/complete

Until this step runs, the document stays unpublished with no parts and is not returned by search. The request body is optional; include metadata fields (the same ones accepted by PATCH /api/documents/{document_id}) to set them at finalize time.

Response

{ "data": { "id": "doc-xyz789" }, "error": null }

The full ingest sequence is therefore: upload → POST /api/jobs → poll GET /api/jobs until processed → POST /api/jobs/{job_id}/complete.