Ingest API quickstart

The Ingest API turns a raw file (PDF, image, audio, text) into a searchable document in your Vulgate Library. It's a two-step process: upload the file, then start an ingest job.

The full reference lives at /docs/ingest/overview. This guide walks through the minimum needed to upload your first file from code.

Step 1 — Request a signed upload URL

Vulgate uses signed storage URLs so file uploads bypass the API server entirely. First, request a URL from /api/uploads:

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

Response:

{
  "url": "https://...signed-storage-url...",
  "method": "PUT",
  "headers": {
    "content-type": "application/pdf",
    "x-amz-meta-name": "research-paper.pdf"
  }
}

Keep the file ID returned in the headers (x-amz-meta-name along with the path part of the URL) — you'll need it in step 3. The signed URL is valid for a short window.

Step 2 — Upload the file to the signed URL

Send the file body as a PUT to the signed URL with the headers from step 1. Don't include the Vulgate auth header here — the signature handles auth:

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

The storage service responds with HTTP 200 and no body when successful.

Step 3 — Start an ingest job

Tell Vulgate to start processing the uploaded file by POSTing to /api/jobs with the file ID from step 1:

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

The job runs in the background. Once it completes, the document is searchable — call the Search API or Chat API to interact with it.

Multipart uploads for large files

The single-file flow above works well for typical files. For very large files, use the multipart endpoints (POST /api/uploads). See Uploading files for the full reference.