Free PDF utilities

Free document mechanics inside the Emboss artifact workflow: merge, compose, extract, delete, reorder, rotate and inspect 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`

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.

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.
`rate_limited`	429	More than one hundred and twenty runs in an hour for this scope.