Onboarding

Getting Started

The public DocuShell API is a queued job system: submit work, keep the returned job_id, poll status, then stream the finished file or artifact.

Overview3 min

View as Markdown

Parse PDF referenceFile upload, parser fields, batch parse, artifacts, and parse-specific failures.AuthenticationBearer headers, API key handling, and idempotent retries.Error codesTyped errors, status codes, and retry guidance.

Base URL

https://api.docushell.com/api

Append /v1/... paths to call public API routes.

Auth

Bearer API key

Send Authorization: Bearer YOUR_API_KEY on submit, status, and download routes.

Job flow

submit, poll, download

Most routes return 202 with a job_id; completed files are streamed through the gateway.

Section

Quickstart Checklist

Use this page to make one working API call. Endpoint-specific options live in each reference page.

Start with Markdown to PDF because it is a small JSON request and still exercises the full queued job lifecycle.

Create an API key in the dashboard Developer tab. The raw key is shown once.
Send bearer auth with Authorization: Bearer YOUR_API_KEY on every public API route.
Add Idempotency-Key on submit requests when callers may retry after a timeout.
Store job_id and request_id from the queued response. Use request_id when debugging with support.
Poll before download. The download link is valid after the job reaches done.

Keep API keys in server-side code, workers, CI, or trusted automation. Do not ship them in browser bundles.

Section

First Request

Submit a tiny Markdown document and save the returned job_id.

First request

bash

curl -X POST "https://api.docushell.com/api/v1/markdown-to-pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "markdown": "# DocuShell\n\nRendered through the public API.",
    "file_name": "quickstart.md",
    "page_size": "A4"
  }'

Section

Queued Job Lifecycle

A successful submit returns 202 immediately. The worker finishes the file asynchronously.

Queued response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 5,
  "service": "markdown-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Do not assume the file is ready when this response arrives. Poll the status link first.

Poll status

bash

curl "https://api.docushell.com/api/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT" \
  -H "Authorization: Bearer YOUR_API_KEY"

Done response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "done",
  "service": "markdown-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "result": {
    "filename": "quickstart.pdf",
    "sizeBytes": 184322,
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  },
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Download result

bash

curl "https://api.docushell.com/api/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output quickstart.pdf

Downloads are one-time streams where applicable. Fetch the artifact only after the job is terminal.

Section

Request Basics

These fields apply across the public API unless an endpoint page says otherwise.

Item	Required	Notes
`Authorization`	Yes	Bearer API key. Send on submit, status, and download requests.
`Idempotency-Key`	Recommended	Use a fresh value for each logical submit. Reuse it only for the exact same retry.
Content-Type	Depends	`application/json` for JSON routes; `multipart/form-data` for file uploads.
job_id	Response	Store it after submit and poll `GET /v1/jobs/:jobId`.
request_id	Response	Trace id returned in JSON and `x-request-id`; include it in support reports.

Section

Common Error Envelope

Errors are typed and include a request identifier.

Error response

json

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

The same `request_id` is also returned in the `x-request-id` response header for easier tracing.

Section

Common First-Run Errors

Status	Code	Fix
401	invalid_api_key	Check the bearer token, key status, and account API access.
409	idempotency_key_reused	Use a new key when the payload changes.
429	rate_limit_exceeded	Back off and retry after the documented window.
503	server_busy	Retry later with the same `Idempotency-Key` only for the same request.

Section

Next Steps

Move from the generic job flow to the endpoint you plan to ship.

Parse PDF

Use /v1/parse for structured JSON, Markdown, text, HTML, annotated PDF, and batch parse workflows.

Resume Parse

Use /v1/resume/parse for ATS-oriented candidate, contact, skills, experience, and confidence fields.

Playgrounds

Inspect sample output or run Parse and Resume Parse with your own API key.

Code Samples

First request

curl -X POST "https://api.docushell.com/api/v1/markdown-to-pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "markdown": "# DocuShell\n\nRendered through the public API.",
    "file_name": "quickstart.md",
    "page_size": "A4"
  }'

Queued response

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 5,
  "service": "markdown-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Poll status

curl "https://api.docushell.com/api/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT" \
  -H "Authorization: Bearer YOUR_API_KEY"