API documentation

Base URL https://api.pagesmith.eu/api · every request is processed in memory and shredded. Nothing is stored.

Authentication

All requests to the pagesmith API require an API key passed via the Authorization header:

Authorization: Bearer psk_live_...

Generate your API key in the dashboard. Keys require an active subscription.

POST /v1/fill

Fill AcroForm fields in a PDF from JSON data. Fields are optional; missing fields are skipped. Optionally flatten the form to bake the values into the page and remove the interactive fields.

Parameters

Example

curl -s https://api.pagesmith.example/api/v1/fill \
  -H "Authorization: Bearer psk_live_..." \
  -F file=@contract.pdf \
  -F 'data={"name":"Jesper","subscribed":true}' \
  -F flatten=true -o filled.pdf

Response

HTTP 200 with the filled PDF file as binary content. Content-Type: application/pdf

POST /v1/pdfa/validate

Validate a PDF against PDF/A compliance standards using the veraPDF engine. Returns detailed rule-level results for archival readiness assessment.

Parameters

Example

curl -s https://api.pagesmith.example/api/v1/pdfa/validate \
  -H "Authorization: Bearer psk_live_..." \
  -F file=@archive.pdf -F profile=2b

Response

HTTP 200 with JSON:

{
  "compliant": true,
  "profile": "2b",
  "passedRules": 58,
  "failedRules": 0,
  "ruleSummaries": [
    {
      "ruleId": "6.1.2-1",
      "specification": "ISO 19005-1:2005",
      "description": "Font program embedded",
      "status": "failed",
      "failedChecks": 3
    }
  ]
}

POST /v1/pdfa/convert

Convert any PDF to archival PDF/A using Ghostscript. The output must pass pagesmith's own PDF/A-validate engine for the requested profile before it's ever returned.

Parameters

Example

curl -s https://api.pagesmith.example/api/v1/pdfa/convert \
  -H "Authorization: Bearer psk_live_..." \
  -F file=@scan.pdf -F profile=2b -o converted.pdf

Response

HTTP 200 with the converted PDF as binary content. Content-Type: application/pdf, X-Pagesmith-Units: 3 (3 units per call).

POST /v1/seal

Apply a PAdES digital signature with your own PKCS#12 certificate. No signing authority, no pagesmith-issued identity. An invisible signature field is added to the PDF automatically, so it works on any PDF, not just one with an existing signature field.

Parameters

Example

curl -s https://api.pagesmith.example/api/v1/seal \
  -H "Authorization: Bearer psk_live_..." \
  -F file=@contract.pdf \
  -F certificate_id=4 \
  -F passphrase="correct horse battery staple" \
  -F reason="Approved by finance" -o sealed.pdf

Response

HTTP 200 with the sealed PDF as binary content. Content-Type: application/pdf, X-Pagesmith-Units: 3 (3 units per call).

POST /v1/merge

Merge 2–10 PDFs into a single document, in the order submitted.

Parameters

Example

curl -s https://api.pagesmith.example/api/v1/merge \
  -H "Authorization: Bearer psk_live_..." \
  -F files[]=@cover.pdf -F files[]=@contract.pdf -F files[]=@appendix.pdf \
  -o merged.pdf

Response

HTTP 200 with the merged PDF as binary content. Content-Type: application/pdf, X-Pagesmith-Units: 1 (1 unit per call, regardless of file count).

POST /v1/stamp

Stamp text onto every page of a PDF: page numbers, watermarks, draft marks.

Parameters

Example

curl -s https://api.pagesmith.example/api/v1/stamp \
  -H "Authorization: Bearer psk_live_..." \
  -F file=@draft.pdf -F text="DRAFT internal review" -F position=top -F opacity=0.4 \
  -o stamped.pdf

Response

HTTP 200 with the stamped PDF as binary content. Content-Type: application/pdf, X-Pagesmith-Units: 1 (1 unit per call).

Async processing

Add async=1 to any of /v1/fill, /v1/pdfa/convert, /v1/seal, /v1/merge, or /v1/stamp to run the same operation as a background job instead of waiting for the response inline. Useful for large files or slower operations like convert and seal.

Parameters

Example

curl -s https://api.pagesmith.example/api/v1/seal \
  -H "Authorization: Bearer psk_live_..." \
  -F file=@contract.pdf -F certificate_id=4 -F passphrase="..." \
  -F async=1 -F webhook_url=https://example.com/hooks/pagesmith

{"id": "01j...", "status": "queued", "status_url": "https://api.pagesmith.example/api/v1/jobs/01j..."}

GET /v1/jobs/{id}

Poll (or wait for the webhook, then call) the job's status_url:

• HTTP 200 {"id": "...", "status": "queued"} or "status": "processing" while the job is still running.
• application/problem+json, at the operation's original error status, if the job failed: the same body the synchronous call would have returned.
• HTTP 200 with the result file as binary content (Content-Type: application/pdf) once the job is done.
• HTTP 404 job.not_found for an unknown job id, or one belonging to another account.

Error responses

All errors are returned as application/problem+json with a stable code field for programmatic handling.

Error codes

Example error response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://pagesmith.example/problems/form.field_unknown",
  "title": "Field not found",
  "status": 422,
  "detail": "Field 'employer' does not exist in this PDF",
  "code": "form.field_unknown"
}