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/jobsRequest schema
The request body must include either files or document_id:
| Field | Type | Default | Description |
|---|---|---|---|
files | array | Conditional* | Array of file objects with id (string). Required if document_id is not provided. |
document_id | string (UUID) | Conditional* | UUID of an existing document. Required if files is not provided. |
team | string | — | Team identifier |
model | string | — | Model to use for processing |
pipeline | object | — | Ingest pipeline configuration |
ingest_mode | string | — | Mode for ingestion |
scope | object | — | Document scope configuration |
audio_options | object | — | Audio processing options |
audio_options.transcription | boolean | — | Enable audio transcription |
audio_options.music_analysis | boolean | — | Enable music analysis |
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.
* Either files or document_id must be provided, but not both.
The response contains the created document_id and job_id:
{ "document_id": "doc-xyz789", "job_id": "job-abc123" }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}/completeUntil 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 → wait for processed → POST /api/jobs/{job_id}/complete.