Async Jobs

Most heavy production workloads should use execution_mode: async. The pattern is the same across parse, schema builder, extract, split, and chat:

1. Send the original request with execution_mode: "async"
2. Store the returned job_id
3. Poll GET /v1/jobs/{job_id}
4. Fetch GET /v1/jobs/{job_id}/result once the job is complete

cURL

JOB_ID=$(
  curl -sS -X POST "https://api.docspeed.ai/api/v1/parse" \
    -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "input": {"file_id": "file_123"},
      "execution_mode": "async",
      "profile": "grounded",
      "grounding": "regions"
    }' | jq -r '.job_id'
)

curl -sS \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  "https://api.docspeed.ai/v1/jobs/${JOB_ID}"

Python

import requests

submit = requests.post(
    "https://api.docspeed.ai/api/v1/parse",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "input": {"file_id": "file_123"},
        "execution_mode": "async",
        "profile": "grounded",
        "grounding": "regions",
    },
    timeout=300,
)
submit.raise_for_status()
job_id = submit.json()["job_id"]

status = requests.get(
    f"https://api.docspeed.ai/v1/jobs/{job_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=60,
)
print(status.json())

TypeScript

const submit = await fetch("https://api.docspeed.ai/api/v1/parse", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { file_id: "file_123" },
    execution_mode: "async",
    profile: "grounded",
    grounding: "regions",
  }),
});

const { job_id } = await submit.json();
const status = await fetch(`https://api.docspeed.ai/v1/jobs/${job_id}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

console.log(await status.json());

Example job result

{
  "job_id": "job_123",
  "operation": "parse",
  "status": "completed",
  "execution_mode": "async"
}