Free PDF utilities

View as Markdown

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. See the guide at /docs/pdf-utilities.

Compose a PDF

POST/utilities/compose_pdfBearer auth

Build one PDF from several artifacts, each with an optional page selection and rotation. Anonymous callers send an artifact_token per source instead of a Bearer key.

Parameters

Name	In	Type	Required	Description
`sources`	body	array	yes	Up to twenty entries of {artifact_id, pages, rotate}. pages is a selection like 1-3,7 (omit for every page); rotate is 90, 180 or 270.
`artifact_token`	body	string	no	Per source entry, for pay-per-call callers: the artifact_token returned next to that source's artifact_id.
`Idempotency-Key`	header	string	no	Optional, for an account caller. Retrying with the same key answers 200 with the original run instead of running again. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

200The run's result: operation_id, status, artifact_id, artifacts, and for inspect_pdf a report.
400bad_request, invalid_page_spec, page_out_of_range, duplicate_page, missing_page, empty_output, or pdf_required: the body is malformed, a pages or order value is invalid, or a source is not a PDF with a known page count.
404not_found: no such artifact, or owned by another key or token.
410gone: the artifact's bytes have already been deleted.
413too_many_pages, too_many_inputs, or file_too_large: a source or the result exceeds the page limit, more than twenty sources, or the sources together exceed the size limit.
422pdf_encrypted or pdf_corrupt: the PDF is encrypted or could not be read.
429rate_limited: more than one hundred and twenty runs in an hour for this scope.

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

Response

{
  "operation_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "artifacts": [
    { "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a", "role": "output", "mime_type": "application/pdf" }
  ]
}

Merge whole PDFs

POST/utilities/merge_pdfBearer auth

Join whole PDFs in order, no page selection. Anonymous callers send an artifact_token per source instead of a Bearer key.

Parameters

Name	In	Type	Required	Description
`sources`	body	array	yes	Up to twenty entries of {artifact_id}, joined in order. For page selections use compose_pdf.
`artifact_token`	body	string	no	Per source entry, for pay-per-call callers: the artifact_token returned next to that source's artifact_id.
`Idempotency-Key`	header	string	no	Optional, for an account caller. Retrying with the same key answers 200 with the original run instead of running again. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

200The run's result: operation_id, status, artifact_id, artifacts, and for inspect_pdf a report.
400bad_request, invalid_page_spec, page_out_of_range, duplicate_page, missing_page, empty_output, or pdf_required: the body is malformed, a pages or order value is invalid, or a source is not a PDF with a known page count.
404not_found: no such artifact, or owned by another key or token.
410gone: the artifact's bytes have already been deleted.
413too_many_pages, too_many_inputs, or file_too_large: a source or the result exceeds the page limit, more than twenty sources, or the sources together exceed the size limit.
422pdf_encrypted or pdf_corrupt: the PDF is encrypted or could not be read.
429rate_limited: more than one hundred and twenty runs in an hour for this scope.

curl -X POST https://api.getemboss.ai/utilities/merge_pdf \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"sources": [{"artifact_id": "<first>"}, {"artifact_id": "<second>"}]}'

Response

{
  "operation_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "artifacts": [
    { "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a", "role": "output", "mime_type": "application/pdf" }
  ]
}

Extract pages

POST/utilities/extract_pagesBearer auth

Keep only the named pages of one artifact. Anonymous callers send an artifact_token instead of a Bearer key.

Parameters

Name	In	Type	Required	Description
`artifact_id`	body	string	yes	The source PDF artifact.
`pages`	body	string	yes	A page selection like 1-3,7; 1-based, repeats and any order allowed.
`artifact_token`	body	string	no	For pay-per-call callers: the artifact_token returned next to artifact_id.
`Idempotency-Key`	header	string	no	Optional, for an account caller. Retrying with the same key answers 200 with the original run instead of running again. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

200The run's result: operation_id, status, artifact_id, artifacts, and for inspect_pdf a report.
400bad_request, invalid_page_spec, page_out_of_range, duplicate_page, missing_page, empty_output, or pdf_required: the body is malformed, a pages or order value is invalid, or a source is not a PDF with a known page count.
404not_found: no such artifact, or owned by another key or token.
410gone: the artifact's bytes have already been deleted.
413too_many_pages, too_many_inputs, or file_too_large: a source or the result exceeds the page limit, more than twenty sources, or the sources together exceed the size limit.
422pdf_encrypted or pdf_corrupt: the PDF is encrypted or could not be read.
429rate_limited: more than one hundred and twenty runs in an hour for this scope.

curl -X POST https://api.getemboss.ai/utilities/extract_pages \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"artifact_id": "<source>", "pages": "2,5-9"}'

Response

{
  "operation_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "artifacts": [
    { "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a", "role": "output", "mime_type": "application/pdf" }
  ]
}

Delete pages

POST/utilities/delete_pagesBearer auth

Remove the named pages of one artifact; every other page stays in order. Anonymous callers send an artifact_token instead of a Bearer key.

Parameters

Name	In	Type	Required	Description
`artifact_id`	body	string	yes	The source PDF artifact.
`pages`	body	string	yes	A page selection like 1-2,17; 1-based, repeats and any order allowed.
`artifact_token`	body	string	no	For pay-per-call callers: the artifact_token returned next to artifact_id.
`Idempotency-Key`	header	string	no	Optional, for an account caller. Retrying with the same key answers 200 with the original run instead of running again. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

200The run's result: operation_id, status, artifact_id, artifacts, and for inspect_pdf a report.
400bad_request, invalid_page_spec, page_out_of_range, duplicate_page, missing_page, empty_output, or pdf_required: the body is malformed, a pages or order value is invalid, or a source is not a PDF with a known page count.
404not_found: no such artifact, or owned by another key or token.
410gone: the artifact's bytes have already been deleted.
413too_many_pages, too_many_inputs, or file_too_large: a source or the result exceeds the page limit, more than twenty sources, or the sources together exceed the size limit.
422pdf_encrypted or pdf_corrupt: the PDF is encrypted or could not be read.
429rate_limited: more than one hundred and twenty runs in an hour for this scope.

curl -X POST https://api.getemboss.ai/utilities/delete_pages \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"artifact_id": "<source>", "pages": "1-2,17"}'

Response

{
  "operation_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "artifacts": [
    { "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a", "role": "output", "mime_type": "application/pdf" }
  ]
}

Reorder pages

POST/utilities/reorder_pagesBearer auth

Put one artifact's pages in a new order; every page is named exactly once. Anonymous callers send an artifact_token instead of a Bearer key.

Parameters

Name	In	Type	Required	Description
`artifact_id`	body	string	yes	The source PDF artifact.
`order`	body	array of integers	yes	Every page number, 1-based, named exactly once, in the new order.
`artifact_token`	body	string	no	For pay-per-call callers: the artifact_token returned next to artifact_id.
`Idempotency-Key`	header	string	no	Optional, for an account caller. Retrying with the same key answers 200 with the original run instead of running again. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

200The run's result: operation_id, status, artifact_id, artifacts, and for inspect_pdf a report.
400bad_request, invalid_page_spec, page_out_of_range, duplicate_page, missing_page, empty_output, or pdf_required: the body is malformed, a pages or order value is invalid, or a source is not a PDF with a known page count.
404not_found: no such artifact, or owned by another key or token.
410gone: the artifact's bytes have already been deleted.
413too_many_pages, too_many_inputs, or file_too_large: a source or the result exceeds the page limit, more than twenty sources, or the sources together exceed the size limit.
422pdf_encrypted or pdf_corrupt: the PDF is encrypted or could not be read.
429rate_limited: more than one hundred and twenty runs in an hour for this scope.

curl -X POST https://api.getemboss.ai/utilities/reorder_pages \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"artifact_id": "<source>", "order": [3, 1, 2]}'

Response

{
  "operation_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "artifacts": [
    { "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a", "role": "output", "mime_type": "application/pdf" }
  ]
}

Rotate pages

POST/utilities/rotate_pagesBearer auth

Rotate named pages of one artifact by 90, 180 or 270 degrees, added clockwise to each page's current rotation. Anonymous callers send an artifact_token instead of a Bearer key.

Parameters

Name	In	Type	Required	Description
`artifact_id`	body	string	yes	The source PDF artifact.
`rotations`	body	array	yes	A non-empty list of {pages, degrees}; degrees is 90, 180 or 270.
`artifact_token`	body	string	no	For pay-per-call callers: the artifact_token returned next to artifact_id.
`Idempotency-Key`	header	string	no	Optional, for an account caller. Retrying with the same key answers 200 with the original run instead of running again. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

200The run's result: operation_id, status, artifact_id, artifacts, and for inspect_pdf a report.
400bad_request, invalid_page_spec, page_out_of_range, duplicate_page, missing_page, empty_output, or pdf_required: the body is malformed, a pages or order value is invalid, or a source is not a PDF with a known page count.
404not_found: no such artifact, or owned by another key or token.
410gone: the artifact's bytes have already been deleted.
413too_many_pages, too_many_inputs, or file_too_large: a source or the result exceeds the page limit, more than twenty sources, or the sources together exceed the size limit.
422pdf_encrypted or pdf_corrupt: the PDF is encrypted or could not be read.
429rate_limited: more than one hundred and twenty runs in an hour for this scope.

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

Response

{
  "operation_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "artifacts": [
    { "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a", "role": "output", "mime_type": "application/pdf" }
  ]
}

Inspect a PDF

POST/utilities/inspect_pdfBearer auth

Structural facts about one artifact: page count, page sizes and rotations, whether it is encrypted, has form fields, annotations, outlines, embedded files or JavaScript. No text, no field values, no new artifact is produced. Anonymous callers send an artifact_token instead of a Bearer key.

Parameters

Name	In	Type	Required	Description
`artifact_id`	body	string	yes	The PDF artifact to inspect.
`artifact_token`	body	string	no	For pay-per-call callers: the artifact_token returned next to artifact_id.
`Idempotency-Key`	header	string	no	Optional, for an account caller. Retrying with the same key answers 200 with the original run instead of running again. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

200The run's result: operation_id, status, artifact_id, artifacts, and for inspect_pdf a report.
400bad_request, invalid_page_spec, page_out_of_range, duplicate_page, missing_page, empty_output, or pdf_required: the body is malformed, a pages or order value is invalid, or a source is not a PDF with a known page count.
404not_found: no such artifact, or owned by another key or token.
410gone: the artifact's bytes have already been deleted.
413too_many_pages, too_many_inputs, or file_too_large: a source or the result exceeds the page limit, more than twenty sources, or the sources together exceed the size limit.
422pdf_encrypted or pdf_corrupt: the PDF is encrypted or could not be read.
429rate_limited: more than one hundred and twenty runs in an hour for this scope.

curl -X POST https://api.getemboss.ai/utilities/inspect_pdf \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"artifact_id": "<source>"}'

Response

{
  "operation_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "artifact_id": null,
  "artifacts": [],
  "report": {
    "pages": 3,
    "encrypted": false,
    "has_acroform": true,
    "has_annotations": false,
    "has_outlines": false,
    "has_embedded_files": false,
    "has_javascript": false,
    "pdf_version": "PDF-1.7",
    "page_info": [
      { "page": 1, "width_points": 612.0, "height_points": 792.0, "rotation": 0 }
    ],
    "mime_type": "application/pdf",
    "size_bytes": 184320,
    "sha256": "f2ad6f..."
  }
}