# 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](/docs/artifacts) 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](#anonymous-callers) below.

## Page selections

Page selections use the same grammar as the rest of the artifact workflow:
see [Artifacts and lineage](/docs/artifacts) 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:

```bash
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:

```bash
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:

```bash
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](/docs/read-filled-form).
- **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](/docs/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. |

## See also

- [Send a fax from an agent](https://getemboss.ai/use-cases/send-a-fax-from-an-agent)
- [Fillable PDF](https://getemboss.ai/glossary/fillable-pdf)
- [Send a fax](https://getemboss.ai/docs/send-fax)
- [Artifacts and lineage](https://getemboss.ai/docs/artifacts)
- [Send a fax](https://getemboss.ai/docs/send-fax)
- [Free PDF utilities](https://getemboss.ai/docs/reference/utilities)
- [Artifacts](https://getemboss.ai/docs/reference/artifacts)