Quickstart

This walks the full roundtrip with curl. You need an API key and a PDF. Export the key first:

export ACCESSFUL_API_KEY="ak_your_key_here"
export BASE="https://api.accessful.de/api/v1/upload-service"

1. Upload the PDF. Send it as multipart form field files:

   curl --fail-with-body --silent --show-error \
     -X POST "$BASE/pdf/upload" \
     -H "X-API-Key: $ACCESSFUL_API_KEY" \
     -F "files=@document.pdf"

   The response lists one caseId per accepted file:

   {
     "successfulUploads": ["7c2f1e4a-9b0d-4a1e-8f3c-2d6b5a9e1c40"],
     "duplicateFiles": [],
     "message": "Upload completed successfully. Uploaded 1 files. 0 duplicates found.",
     "callbackUrl": null
   }

2. Poll the job status with that caseId until it is completed:

   curl --fail-with-body --silent --show-error \
     "$BASE/job-status/7c2f1e4a-9b0d-4a1e-8f3c-2d6b5a9e1c40" \
     -H "X-API-Key: $ACCESSFUL_API_KEY"

   { "jobStatus": "completed", "stage": "finished", "score": 87 }

   score is the accessibility quality of the result (0–100). See all jobStatus values.

3. Download the converted PDF/UA:

   curl --fail-with-body --silent --show-error --location \
     "$BASE/download/7c2f1e4a-9b0d-4a1e-8f3c-2d6b5a9e1c40" \
     -H "X-API-Key: $ACCESSFUL_API_KEY" \
     -o document-pdfua.pdf

4. Delete the case when you no longer need it (optional, but recommended — this is a permanent purge):

   curl --fail-with-body --silent --show-error \
     -X DELETE "$BASE/delete/7c2f1e4a-9b0d-4a1e-8f3c-2d6b5a9e1c40" \
     -H "X-API-Key: $ACCESSFUL_API_KEY"

Skip the polling

Instead of step 2, register a webhook at upload time and we’ll POST a signed event to your URL the moment the job finishes.

Full example

cURL + jq

#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Pass a PDF path as the first argument.
: "${ACCESSFUL_API_KEY:?Set ACCESSFUL_API_KEY first}"
BASE="https://api.accessful.de/api/v1/upload-service"
FILE="${1:-document.pdf}"
AUTH=(-H "X-API-Key: $ACCESSFUL_API_KEY")

upload=$(curl --fail-with-body --silent --show-error \
  -X POST "$BASE/pdf/upload" \
  "${AUTH[@]}" \
  -F "files=@$FILE")
case_id=$(jq -er '.successfulUploads[0]' <<<"$upload")
echo "Uploaded: $case_id"

terminal='^(completed|failed|analyzer_failed|canceled|quota_exceeded)$'
while true; do
  status_json=$(curl --fail-with-body --silent --show-error \
    "$BASE/job-status/$case_id" "${AUTH[@]}")
  status=$(jq -r '.jobStatus' <<<"$status_json")
  echo "Status: $status"
  [[ $status =~ $terminal ]] && break
  sleep 2
done

if [[ $status != completed ]]; then
  echo "Conversion ended with status: $status" >&2
  exit 1
fi

curl --fail-with-body --silent --show-error --location \
  "$BASE/download/$case_id" \
  "${AUTH[@]}" \
  --output document-pdfua.pdf

score=$(jq -r '.score // "n/a"' <<<"$status_json")
echo "Saved document-pdfua.pdf (score: $score)"

Node.js

import { openAsBlob } from 'node:fs';
import { writeFile } from 'node:fs/promises';

const apiKey = process.env.ACCESSFUL_API_KEY;
if (!apiKey) throw new Error('Set ACCESSFUL_API_KEY first');

const BASE = 'https://api.accessful.de/api/v1/upload-service';
const headers = { 'X-API-Key': apiKey };
const terminal = new Set([
  'completed',
  'failed',
  'analyzer_failed',
  'canceled',
  'quota_exceeded',
]);

async function request(path, init = {}) {
  const response = await fetch(BASE + path, {
    ...init,
    signal: AbortSignal.timeout(60_000),
  });
  if (!response.ok) {
    throw new Error(`${response.status}: ${await response.text()}`);
  }
  return response;
}

// 1. Upload
const file = await openAsBlob('document.pdf', {
  type: 'application/pdf',
});
const body = new FormData();
body.append('files', file, 'document.pdf');

const upload = await request('/pdf/upload', {
  method: 'POST',
  headers,
  body,
}).then((response) => response.json());
const [caseId] = upload.successfulUploads ?? [];
if (!caseId) throw new Error('Upload returned no caseId');

// 2. Poll until the job reaches a terminal state
let status;
while (true) {
  status = await request(`/job-status/${caseId}`, { headers })
    .then((response) => response.json());
  console.log(`Status: ${status.jobStatus}`);
  if (terminal.has(status.jobStatus)) break;
  await new Promise((resolve) => setTimeout(resolve, 2_000));
}

if (status.jobStatus !== 'completed') {
  throw new Error(`Conversion ended with status: ${status.jobStatus}`);
}

// 3. Download
const result = await request(`/download/${caseId}`, { headers });
await writeFile(
  'document-pdfua.pdf',
  Buffer.from(await result.arrayBuffer()),
);
console.log(`Saved document-pdfua.pdf (score: ${status.score})`);

Python

# pip install requests
import os
import time
from pathlib import Path

import requests

api_key = os.environ.get("ACCESSFUL_API_KEY")
if not api_key:
    raise RuntimeError("Set ACCESSFUL_API_KEY first")

base = "https://api.accessful.de/api/v1/upload-service"
terminal = {
    "completed",
    "failed",
    "analyzer_failed",
    "canceled",
    "quota_exceeded",
}

with requests.Session() as session:
    session.headers.update({"X-API-Key": api_key})

    # 1. Upload
    with Path("document.pdf").open("rb") as pdf:
        response = session.post(
            f"{base}/pdf/upload",
            files={"files": ("document.pdf", pdf, "application/pdf")},
            timeout=60,
        )
    response.raise_for_status()
    case_id = response.json()["successfulUploads"][0]

    # 2. Poll until the job reaches a terminal state
    while True:
        response = session.get(
            f"{base}/job-status/{case_id}",
            timeout=30,
        )
        response.raise_for_status()
        status = response.json()
        print(f"Status: {status['jobStatus']}")
        if status["jobStatus"] in terminal:
            break
        time.sleep(2)

    if status["jobStatus"] != "completed":
        raise RuntimeError(
            f"Conversion ended with status: {status['jobStatus']}"
        )

    # 3. Download without loading the entire PDF into memory
    with session.get(
        f"{base}/download/{case_id}",
        stream=True,
        timeout=60,
    ) as response:
        response.raise_for_status()
        with Path("document-pdfua.pdf").open("wb") as output:
            for chunk in response.iter_content(chunk_size=64 * 1024):
                output.write(chunk)

print(f"Saved document-pdfua.pdf (score: {status['score']})")

Prefer to click instead of type? Run the same flow in the browser on the Try it out page.