API reference · v1.0.0

PDF Tagger API reference

Tag PDFs for PDF/UA accessibility from your own code. Authenticate with an API key, upload a PDF, submit a tagging job, then poll the job or receive a signed webhook when it finishes. Jobs draw from the same credit balance as the web app (1 credit per page).

Download the OpenAPI spec

Base URL

https://api.pdf-tagger.com

Authentication

Send your key as Authorization: Bearer sk_live_….

Header

Authorization: Bearer sk_live_...

Account

Your account and credit balance.

Get account

The authenticated account, its plan, and its current credit balance.

Responses

200Account info
- account_idstring
- planstring | null
- subscription_statusstring | null
- credits_availableinteger
- request_idstring
401Missing, invalid, or revoked API key
- errorobject
  - typestring
  - messagestring
  - request_idstring
429Rate limit exceeded (see the Retry-After header)
- Retry-Afterheader · integer
  Seconds until the window resets.
- errorobject
  - typestring
  - messagestring
  - request_idstring

GEThttps://api.pdf-tagger.com/v1/me

Request

curl -X GET https://api.pdf-tagger.com/v1/me \
  -H "Authorization: Bearer sk_live_..."

Response 200

{
  "account_id": "string",
  "plan": "string",
  "subscription_status": "string",
  "credits_available": 0,
  "request_id": "string"
}

Response 401, 429

{
  "error": {
    "type": "string",
    "message": "string",
    "request_id": "string"
  }
}

Jobs

Upload a PDF, submit a tagging job, and download the result.

Create upload

Returns a presigned POST. Upload the PDF straight to storage as multipart/form-data, including every field in fields plus the file, then pass key to POST /v1/jobs.

Request body (JSON)

filenamestring
The original filename (optional).

Responses

201Presigned upload
- upload_urlstring
- fieldsobject
- keystring
- request_idstring
401Missing, invalid, or revoked API key
- errorobject
  - typestring
  - messagestring
  - request_idstring
429Rate limit exceeded (see the Retry-After header)
- Retry-Afterheader · integer
  Seconds until the window resets.
- errorobject
  - typestring
  - messagestring
  - request_idstring

POSThttps://api.pdf-tagger.com/v1/uploads

Request

curl -X POST https://api.pdf-tagger.com/v1/uploads \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "string"
  }'

Response 201

{
  "upload_url": "string",
  "fields": {
    "property1": "string",
    "property2": "string"
  },
  "key": "string",
  "request_id": "string"
}

Response 401, 429

{
  "error": {
    "type": "string",
    "message": "string",
    "request_id": "string"
  }
}

Submit job

Submit a tagging job for an uploaded PDF. Charges one credit per page.

Parameters

Idempotency-Keyheader · string
A repeat with the same key returns the first job and never double-charges.

Request body (JSON, required)

keystringrequired
The key from POST /v1/uploads.
filenamestring
optionsobject
- ocrboolean, default false
  Force OCR on image-only pages.
- embed_fontsboolean, default false
  Embed a non-embedded font when safe.

Responses

202Job accepted
- idstring
- statusstring: processing, completed, failed
- filenamestring | null
- credits_usedinteger
- optionsobject | null
- created_atstring (date-time)
- request_idstring
400Invalid request
- errorobject
  - typestring
  - messagestring
  - request_idstring
401Missing, invalid, or revoked API key
- errorobject
  - typestring
  - messagestring
  - request_idstring
402Not enough credits
- errorobject
  - typestring
  - messagestring
  - request_idstring
409Idempotency conflict or a job still being created
- errorobject
  - typestring
  - messagestring
  - request_idstring
429Rate limit exceeded (see the Retry-After header)
- Retry-Afterheader · integer
  Seconds until the window resets.
- errorobject
  - typestring
  - messagestring
  - request_idstring

POSThttps://api.pdf-tagger.com/v1/jobs

Request

curl -X POST https://api.pdf-tagger.com/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "string",
    "filename": "string",
    "options": {
      "ocr": false,
      "embed_fonts": false
    }
  }'

Response 202

{
  "id": "string",
  "status": "processing",
  "filename": "string",
  "credits_used": 0,
  "options": {},
  "created_at": "2026-01-01T12:00:00Z",
  "request_id": "string"
}

Response 400, 401, 402, 409, 429

{
  "error": {
    "type": "string",
    "message": "string",
    "request_id": "string"
  }
}

Get job

A job's current status — processing, completed, or failed.

Parameters

idpath · stringrequired

Responses

200Job
- idstring
- statusstring: processing, completed, failed
- filenamestring | null
- credits_usedinteger
- optionsobject | null
- created_atstring (date-time)
- request_idstring
401Missing, invalid, or revoked API key
- errorobject
  - typestring
  - messagestring
  - request_idstring
404No such resource for this account
- errorobject
  - typestring
  - messagestring
  - request_idstring
429Rate limit exceeded (see the Retry-After header)
- Retry-Afterheader · integer
  Seconds until the window resets.
- errorobject
  - typestring
  - messagestring
  - request_idstring

GEThttps://api.pdf-tagger.com/v1/jobs/{id}

Request

curl -X GET https://api.pdf-tagger.com/v1/jobs/{id} \
  -H "Authorization: Bearer sk_live_..."

Response 200

{
  "id": "string",
  "status": "processing",
  "filename": "string",
  "credits_used": 0,
  "options": {},
  "created_at": "2026-01-01T12:00:00Z",
  "request_id": "string"
}

Response 401, 404, 429

{
  "error": {
    "type": "string",
    "message": "string",
    "request_id": "string"
  }
}

Get result

A short-lived download URL for the tagged PDF, once the job is completed.

Parameters

idpath · stringrequired

Responses

200A presigned download URL
- result_urlstring
- expires_ininteger
  Seconds the URL is valid.
- request_idstring
401Missing, invalid, or revoked API key
- errorobject
  - typestring
  - messagestring
  - request_idstring
404No such resource for this account
- errorobject
  - typestring
  - messagestring
  - request_idstring
409The job is not completed yet
- errorobject
  - typestring
  - messagestring
  - request_idstring
429Rate limit exceeded (see the Retry-After header)
- Retry-Afterheader · integer
  Seconds until the window resets.
- errorobject
  - typestring
  - messagestring
  - request_idstring

GEThttps://api.pdf-tagger.com/v1/jobs/{id}/result

Request

curl -X GET https://api.pdf-tagger.com/v1/jobs/{id}/result \
  -H "Authorization: Bearer sk_live_..."

Response 200

{
  "result_url": "string",
  "expires_in": 0,
  "request_id": "string"
}

Response 401, 404, 409, 429

{
  "error": {
    "type": "string",
    "message": "string",
    "request_id": "string"
  }
}

Webhooks

Signed job events delivered to your server. Register and manage endpoints in the dashboard (the Developers page); this section documents the event you receive and how to verify it.

Job event

POSTed to every enabled endpoint. Verify the X-PDFTagger-Signature header before trusting the body: it is t=<unixSeconds>,v1=<hmac>, where the HMAC is SHA-256 over <t>.<rawBody> keyed by the endpoint secret. Reject a timestamp older than a few minutes (replay). Delivery is at least once — dedupe on data.job.id. The event carries no result URL; fetch it with GET /v1/jobs/{id}/result.

Parameters

X-PDFTagger-Signatureheader · stringrequired

Request body (JSON)

idstring
typestring: job.completed, job.failed
createdinteger
dataobject
- jobobject
  - idstring
  - statusstring: processing, completed, failed
  - filenamestring | null
  - credits_usedinteger
  - optionsobject | null
  - created_atstring (date-time)
  - request_idstring

Responses

2XXAny 2xx acknowledges receipt. Non-2xx is retried with backoff.

POSTYour webhook endpoint

Payload you receive

{
  "id": "string",
  "type": "job.completed",
  "created": 0,
  "data": {
    "job": {
      "id": "string",
      "status": "processing",
      "filename": "string",
      "credits_used": 0,
      "options": {},
      "created_at": "2026-01-01T12:00:00Z",
      "request_id": "string"
    }
  }
}

Schemas

Job

idstring
statusstring: processing, completed, failed
filenamestring | null
credits_usedinteger
optionsobject | null
created_atstring (date-time)
request_idstring

Example

{
  "id": "string",
  "status": "processing",
  "filename": "string",
  "credits_used": 0,
  "options": {},
  "created_at": "2026-01-01T12:00:00Z",
  "request_id": "string"
}

Error

errorobject
- typestring
- messagestring
- request_idstring

Example

{
  "error": {
    "type": "string",
    "message": "string",
    "request_id": "string"
  }
}