Overview

The Vulgate Ingest API lets you upload files and process them into searchable documents within your libraries. Ingesting is a two-step process: first you upload a file, then you create a document and start an ingest job that processes it.

Base URL

All Ingest API endpoints are relative to your Vulgate instance:

https://vulgate.ai/api

Endpoints

EndpointMethodDescription
/api/uploadsGETObtain a signed URL for single-file upload
/api/uploadsPOSTInitiate a multipart upload
/api/jobsPOSTCreate a document and start an ingest job
/api/jobsGETList jobs and poll processing status
/api/jobs/{job_id}/completePOSTFinalize a processed job and publish the document

Processing tiers

Every ingest job runs in one of two processing tiers, selected with the ingest_mode field on POST /api/jobs:

  • Standard ("standard", the default) — fast OCR-based extraction, 1 credit per page, accepts every supported file type (PDF, images, audio, video, Office documents, HTML).
  • Pro ("pro") — vision-model extraction for degraded scans and complex layouts, 5 credits per page, PDF and images only.

The processing model is fixed by the tier — there is no separate model parameter to configure. See Processing tiers for details.

Authentication

All endpoints require authentication via a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

API keys are scoped to a team and carry the permissions of the team owner. See Getting Started for how to obtain and configure your API key.

Quick example

Upload a PDF and start ingesting it:

Step 1 — Get a signed upload URL:

curl -G "https://vulgate.ai/api/uploads" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "name=document.pdf" \
  --data-urlencode "type=application/pdf"

Step 2 — Upload the file to the signed URL:

curl -X PUT "<signed-url-from-step-1>" \
  -H "Content-Type: application/pdf" \
  -H "X-Amz-Meta-Name: document.pdf" \
  --data-binary @document.pdf

Step 3 — Create a document and start ingestion:

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-step-1>" }],
    "ingest_mode": "standard"
  }'

ingest_mode is optional and defaults to "standard"; pass "pro" for vision-model extraction on difficult scans.

Next steps