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" }

Ingestion is draft-by-default: the new document is created with status pending, has no parts, and is invisible to the library and to search until the finalize step publishes it. Use that window to review and edit the extracted content before it goes live.

Errors

Example

curl -X POST "https://vulgate.ai/api/jobs" \
  -H "Authorization: Bearer $VULGATE_TEAM_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.

To check the extracted content and correct it before publishing — and to edit or republish a document afterwards — see Reviewing and Editing Documents.