Free PDF utilities

Free document mechanics inside the Emboss artifact workflow: merge, compose, extract, delete, reorder, rotate, inspect and lock PDF artifacts without downloading or re-uploading them, and use the result directly in a fill or a fax.

What you can do

Each row is a POST /utilities/{skill} call. See Artifacts and lineage for artifact_id, artifact_token, and the page-selection grammar pages uses.

Utility	What it does	Request keys
`compose_pdf`	Builds one PDF from several artifacts, with an optional page selection and rotation per source.	`sources`: a list of `{artifact_id, pages, rotate}`
`merge_pdf`	Joins whole PDFs in order; no page selection.	`sources`: a list of `{artifact_id}`
`extract_pages`	Keeps only the named pages of one artifact.	`artifact_id`, `pages`
`delete_pages`	Removes the named pages of one artifact; every other page stays in order.	`artifact_id`, `pages`
`reorder_pages`	Puts one artifact's pages in a new order; every page is named exactly once.	`artifact_id`, `order`
`rotate_pages`	Rotates named pages of one artifact by 90, 180 or 270 degrees.	`artifact_id`, `rotations`: a list of `{pages, degrees}`
`inspect_pdf`	Reports structural facts about one artifact: no new file is produced.	`artifact_id`
`flatten_pdf`	Lock a filled form: draws every field's value and every comment into the page so nothing can be edited.	`artifact_id`

Every call may add artifact_token per source for anonymous callers. See Anonymous callers below.

Page selections

Page selections use the same grammar as the rest of the artifact workflow: see Artifacts and lineage for the syntax. Omitting pages on a compose_pdf or merge_pdf source means every page of that source.

Compose then fax

A packet assembled from several artifacts can be rotated and faxed without ever leaving the artifact workflow. Compose two sources into one PDF:

curl -X POST https://api.getemboss.ai/utilities/compose_pdf \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sources": [
        {"artifact_id": "<cover letter>"},
        {"artifact_id": "<filled form>", "pages": "1-2"}]}'

Rotate the composed result:

curl -X POST https://api.getemboss.ai/utilities/rotate_pages \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artifact_id": "<artifact_id from compose_pdf>", "rotations": [{"pages": "1", "degrees": 90}]}'

Fax the rotated result by its artifact_id, no re-upload needed:

curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "artifact_id": "<artifact_id from rotate_pages>"}'

GET /artifacts/{id} on the transmitted copy shows the whole chain: the fax's produced_by points at the rotation, whose inputs point at the compose, whose inputs point at the two original sources.

Lock a filled form

flatten_pdf takes one PDF artifact and makes a new PDF in which every field's value, every checked box and every comment is drawn into the page. No editable fields are left. Links keep working, and the page count, page size and rotation do not change. The original stays as it is, so you still have the fillable copy.

Signature boxes. A typed name is drawn in the box. An empty box is left blank, ready to sign by hand. No placeholder tag is ever drawn. A real digital signature is refused (pdf_signed), because locking would change the file and break it.
Calculated boxes. The result's report lists calculated_left_blank: the labels of boxes the form totals itself that were empty when it was locked.
Nothing to lock. A file with no fields and no comments succeeds, with zeros in the report.
Read or verify first. A locked form cannot be read back or checked: read_form refuses it with "no form boxes found". Read it or verify it before you lock it. See Read a filled form back.
fill_form never locks. It returns a fillable PDF. To lock it, call flatten_pdf with the filled PDF's artifact_id.

The report carries fields_locked, annotations_locked, pages and calculated_left_blank. It is free, with the same limits and the same hourly run limit as the other page tools.

Anonymous callers

Pay-per-call callers pass the artifact_token they received with each source alongside its artifact_id. A run's result carries an artifact_token next to its artifact_id too, so the chain above works the same way without an account: no quote, no charge. See Pay per call.

Limits and retention

at most twenty sources per call.
Up to one hundred pages per source.
Up to five hundred pages in the result.
Up to one hundred megabytes of sources together.
One hundred and twenty runs an hour per account or per pay-per-call scope.

Outputs of a free utility are deleted sixty to seventy minutes after they are created, for every caller.

Errors

Code	Status	Meaning
`bad_request`	400	The body is malformed or missing a required key.
`invalid_page_spec`	400	A `pages` value could not be parsed.
`page_out_of_range`	400	`order` names a page the document does not have.
`duplicate_page`	400	`order` names the same page twice.
`missing_page`	400	`order` leaves a page out.
`empty_output`	400	Deleting the named pages would leave no document.
`pdf_required`	400	A source is not a PDF with a known page count.
`not_found`	404	No such artifact, or owned by another key.
`gone`	410	The artifact's bytes have already been deleted.
`too_many_pages`	413	A source, or the result, exceeds the page limit.
`too_many_inputs`	413	More than twenty sources.
`file_too_large`	413	The sources together exceed the size limit.
`pdf_encrypted`	422	The PDF is encrypted and cannot be processed.
`pdf_corrupt`	422	The PDF could not be read.
`pdf_unsafe`	422	The PDF's form fields are built in a way that could compromise the service. The message is "Emboss does not process PDF files that could compromise the service."
`pdf_signed`	422	`flatten_pdf` only: This PDF is digitally signed. Locking it would change the file and break the signature.
`xfa_dynamic`	422	`flatten_pdf` only: This form is built with Adobe's dynamic XFA format, which only Adobe Reader can draw, so it can't be locked.
`rate_limited`	429	More than one hundred and twenty runs in an hour for this scope.