Introduction
Welcome to the Artwork API, a powerful tool that allows you to seamlessly integrate artworker.io into your workflow. With this API, you can create, update and attach artwork to artworker jobs.
You can view code examples in the dark area to the right.
Authentication
To authorize, use the
api_keyquery param:POST https://open-api.artworker.io/v1/route ?api_key=[API_KEY]
Make sure to replace
[API_KEY]with your API key.
Artworker uses API keys to allow access to the API. You can register a new Artworker API key at our developer portal.
Artworker expects the API key to be included in all API requests to the server as a query parameter that looks like the following:
?api_key=[API_KEY]
Jobs
Job Object
Sample Job Object
{
"id": "63e6357ad9a28b28ab9",
"ref": "ODR1382",
"name": "Flyers",
"state": "created",
"customerRef": "930e9bf3-pkdj-4447-83e0-d9fb2d727f0c",
"customerActionURL": "",
"supplerActionURL": "https://app.artworker.io/artwork/63e6357ad9a28b28ab9",
"items": [
{
"thumbnailSrc": "https://storage.googleapis.com/thumb_artwork_page_1.jpg",
"previewSrc": "https://storage.googleapis.com/preview_artwork_page_1.jpg",
"src": "https://storage.googleapis.com/artwork.pdf",
"filename": "two_pages.pdf"
}
]
}
| Field | Description |
|---|---|
| job.id | The id of the job. |
| job.name | The jobs name. |
| job.ref | The jobs reference. |
| job.state | The state of the current job. |
| job.customerRef | The reference for a customer in Artworker. This can be used to GET details of the jobs customer such as name and email |
| job.customerActionURL | URL for the customer to visit to perform any required action. Returns an empty string if no action required. |
| job.supplerActionURL | URL for the supplier to visit to perform any required action. Returns an empty string if no action required. |
| job.items | List of job items (individual files within tthe job). |
Job Item Object
Sample Job Item Object
{
"thumbnailSrc": "https://storage.googleapis.com/thumb_artwork_page_1.jpg",
"previewSrc": "https://storage.googleapis.com/preview_artwork_page_1.jpg",
"src": "https://storage.googleapis.com/artwork.pdf",
"filename": "two_pages.pdf"
}
| Field | Description |
|---|---|
| thumbnailSrc | URL for the file thumnail |
| previewSrc | URL for the file preview |
| src | URL of the file |
| filename | Original name of the file |
Job States
awaiting_artwork
Job ready to recieve artwork
rejected
Artwork rejected by admin, waiting for customer to review
pending_approval
Artwork uploaded by customer or admin and awaiting review
ready_for_production
Artwork approved and ready for production
pending_proof_approval
Proof(s) sent to customer for approval
proof_rejected
Customer has rejected proof(s)
proof_accepted
Customer has accepted proof(s)
complete
Job marked as complete by admin
Postman Collection
Create a Job
POST https://open-api.artworker.io /v1/job ?api_key=[API_KEY]
Headers
Content-Type: application/json
Sample Body
{
"jobName": "new job",
"jobRef": "NJ-1234",
"customerName": "joe bloggs",
"customerEmail": "[email protected]",
"mediaUrls": ["https://storage.googleapis.com/kudo-web-assets/upload-examples/two_pages.pdf"],
"leadtimeOptions": {
"leadtimeLengthDays": 5,
"requiresProof": true
},
"preflightCheckOptions": {
"imageResMin": 150,
"imageResRecommended": 300,
"requireEmbeddedFonts": true,
"pageCount": 1,
"visibleToCustomer": true,
"height": 297.0,
"width": 210.0,
"bleed": 3.0,
"safetyZone": 5.0,
"measurementUnit": "mm"
},
"externalLink": {
"url": "http://google.com",
"buttonText": "Go To Google"
}
}
Sample Response
{
"job": {
"id": "63e6357ad9a28b28ab9",
"ref": "ODR1382",
"name": "Flyers",
"state": "created",
"customerActionURL": "",
"supplerActionURL": "https://app.artworker.io/artwork/63e6357ad9a28b28ab9",
}
}
This endpoint creates a new job within artworker.
HTTP Request
POST https://open-api.artworker.io/v1/job?api_key=[API_KEY]
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| customerEmail | true | The customers email address. |
| customerName | true | The customers name. |
| jobName | true | A name for the job. This should (although does not have to be) be unique to prevent multiple jobs with the same name within artworker. |
| jobRef | false | A reference for the name, not used by our system but useful if you want to associate the job with an order number for example. |
| mediaUrls | false | URLs to artwork files to be imported into artworker and attached to this job. Must be publically accessible. |
| leadtimeOptions | false | Leadtime Options for this job. |
| preflightCheckOptions | false | Preflight Check Options for this job. |
| externalLink | false | External Link adds a link on this jobs page in Artworker. |
Leadtime Options
| Parameter | Required | Description |
|---|---|---|
| leadtimeLengthDays | true | Leadtime length in days, where leadtime is made up of both production and delivery time. |
| requiresProof | false | Indicates if a proof is required for this job. Used to ensure correct leadtime messaging is presented to customer. |
Preflight Check Options
| Parameter | Required | Description |
|---|---|---|
| imageResMin | false | Minimum image resolution in DPI. |
| imageResRecommended | false | Recommended image resolution in DPI. |
| requireEmbeddedFonts | false | Indicates if embedded fonts are required. |
| pageCount | false | Required number of pages in the artwork. |
| measurementUnit | false | Required measurement unit for the artwork. Must be one of: mm or inch. |
| height | false | Required height of the artwork in mm. |
| width | false | Required width of the artwork in mm. |
| bleed | false | Required bleed in mm. |
| safetyZone | false | Required safety zone in mm. |
| visibleToCustomer | false | Indicates if the preflight check results are visible to the customer. |
External Link
| Parameter | Required | Description |
|---|---|---|
| url | true | Link to display on this jobs page in Artworker. |
| buttonText | false | Button text for this link. |
Response
| Parameter | Description |
|---|---|
| job.id | The id of the job. |
| job.name | The jobs name. |
| job.ref | The jobs reference. |
| job.state | The state of the current job. |
| job.customerActionURL | URL for the customer to visit to perform any required action. Returns an empty string if no action required. |
| job.supplerActionURL | URL for the supplier to visit to perform any required action. Returns an empty string if no action required. |
Import files to a Job
PATCH https://open-api.artworker.io /v1/job/:id/import-files ?api_key=[API_KEY]
Headers
Content-Type: application/json
Sample Body
{
"mediaUrls": ["https://storage.googleapis.com/kudo-web-assets/upload-examples/two_pages.pdf", "https://storage.googleapis.com/kudo-web-assets/upload-examples/two_pages.pdf"]
}
Sample Response
{
"ok": true
}
This endpoint imports files to a Job in artworker.
HTTP Request
PATCH https://open-api.artworker.io/v1/job/:id/import-files?api_key=[API_KEY]
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| mediaUrls | false | URLs to artwork files to be imported into artworker and attached to this job. Must be publically accessible. |
Response
| Parameter | Description |
|---|---|
| ok | true if operation succeeded. |
GET a Job
GET https://open-api.artworker.io /v1/job/:id ?api_key=[API_KEY]
Sample Response
{
"job": {
"jobName": "new job",
"jobRef": "NJ-1234",
"customerName": "joe bloggs",
"customerEmail": "[email protected]",
"mediaUrls": ["https://storage.googleapis.com/kudo-web-assets/upload-examples/two_pages.pdf"],
"leadtimeOptions": {
"leadtimeLengthDays": 5,
"requiresProof": true
},
"preflightCheckOptions": {
"imageResMin": 150,
"imageResRecommended": 300,
"requireEmbeddedFonts": true,
"pageCount": 1,
"visibleToCustomer": true,
"height": 297.0,
"width": 210.0,
"bleed": 3.0,
"safetyZone": 5.0,
"measurementUnit": "mm"
},
"externalLink": {
"url": "http://google.com",
"buttonText": "Go To Google"
},
"items": [...]
}
}
This endpoint imports files to a Job in artworker.
HTTP Request
GET https://open-api.artworker.io/v1/job/:id?api_key=[API_KEY]
Response
Response
| Parameter | Description |
|---|---|
| job | job |
Webhook_Endpoint
Webhook Endpoints
POST /v1/webhook_endpoint
GET /v1/webhook_endpoint/:id
POST /v1/webhook_endpoint/:id
GET /v1/webhook_endpoint
DELETE /v1/webhook_endpoint/:id
You can configure webhook endpoints via the API to be notified about events that happen in your Stripe account or connected accounts.
Most users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints.
Webhook Object
Sample Webhook Object
{
"webhook": {
"id": 1234,
"url": "https://dev.example.com/api/webhook",
"secret": "whsec_85n9845yt754n87y35",
"enabledEvents": ["job.complete"]
}
}
| Field | Description |
|---|---|
| id | Unique identifier for the object. |
| url | The URL of the webhook endpoint. |
| secret | The endpoint’s secret, used to generate webhook signatures. |
| enabledEvents | List of enabled events for this endpoint |
Create a Webhook
POST https://open-api.artworker.io /v1/webhook_endpoint ?api_key=[API_KEY]
Headers
Content-Type: application/json
Sample Body
{
"url": "https://dev.example.com/api/webhook",
"enabledEvents": ["job.complete"]
}
Sample Response
{
"webhook": WebhookObject
}
A webhook endpoint must have a url and a list of enabled_events. You can also create webhook endpoints in the webhooks section of the Settings page.
HTTP Request
POST https://open-api.artworker.io/v1/webhook_endpoint?api_key=[API_KEY]
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| url | true | The URL of the webhook endpoint. |
| enabledEvents | true | The list of events to enable for this endpoint. |
Response Body
| Field | Description |
|---|---|
| webhook | WebhookObject |
Get a Webhook
GET https://open-api.artworker.io /v1/webhook_endpoint/1234 ?api_key=[API_KEY]
Headers
Content-Type: application/json
Sample Response
{
"webhook": WebhookObject
}
This endpoint gets a single webhook by id.
HTTP Request
GET https://open-api.artworker.io/v1/webhook_endpoint/:id?api_key=[API_KEY]
Response Body
| Field | Description |
|---|---|
| webhook | WebhookObject |
Update a Webhook
POST https://open-api.artworker.io /v1/webhook_endpoint/1234 ?api_key=[API_KEY]
Headers
Content-Type: application/json
Sample Body
{
"webhook": WebhookObject
}
Sample Response
{
"webhook": WebhookObject
}
This endpoint updates a webhook within artworker.
HTTP Request
POST https://open-api.artworker.io/v1/webhook_endpoint/:id?api_key=[API_KEY]
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| webhook | WebhookObject |
Response Body
| Field | Description |
|---|---|
| webhook | WebhookObject |
List Webhooks
GET https://open-api.artworker.io /v1/webhook_endpoint/1234 ?api_key=[API_KEY]
Headers
Content-Type: application/json
Sample Response
{
"webhooks": WebhookObject[]
}
This endpoint lists all the artworker accounts webhooks. There is a limit of 5 webhooks per account, so the max length of the returned array is 5.
HTTP Request
GET https://open-api.artworker.io/v1/webhook_endpoint?api_key=[API_KEY]
Response Body
| Field | Description |
|---|---|
| webhooks | WebhookObject[] |
Delete a Webhook
DELETE https://open-api.artworker.io /v1/webhook_endpoint/1234 ?api_key=[API_KEY]
Headers
Content-Type: application/json
Sample Response
{
"ok": true
}
This endpoint deletes a webhook by id.
HTTP Request
DELETE https://open-api.artworker.io/v1/webhook_endpoint/:id?api_key=[API_KEY]
Response Body
| Field | Description |
|---|---|
| ok | returns true if successfully deleted |
Errors
The Artworker API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 404 | Not Found -- The specified object could not be found. |
| 405 | Method Not Allowed -- You tried to access an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 410 | Gone -- The object requested has been removed from our servers. |
| 418 | I'm a teapot. |
| 429 | Too Many Requests -- You've reached the limit! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Webhooks
Use incoming webhooks to get real-time updates
Listen for events on your Artworker account so your integration can automatically trigger reactions. Artworker uses webhooks to notify your application when an event happens in your account.
How Artworker uses webhooks
A webhook enables Artworker to push real-time notifications to your app. Artworker uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.
Webhook Events
When an event occurs, we create a new Webhook Event Object object. If you registered a webhook endpoint to receive that event, we send it to your endpoint as part of a POST request.
Webhook Event Object
Sample Body
{
"eventId": "29fdefd3-f499-49a5-8dae-db53b4321d41",
"event": "job.complete",
"createdAt": "2023-02-10T09:15:09.7345339Z",
"data": {
"id": "43991f5c-f75a-459d-9fd2-decaca579354",
"name": "flyers",
"ref": "order001",
"state": "complete",
"customerActionURL": "",
"supplerActionURL": ""
}
}
| Parameter | Description |
|---|---|
| eventID | ID of the event. |
| event | Webhook Events. |
| createdAt | timestamp |
| data | Job |
Webhook Events
job.awaiting_artwork
Occurs when an admin sends an artwork request to a customer.
job.rejected
Occurs when an admin reject one of more files in a job.
job.pending_approval
Occurs when artwork has been uploaded either by the customer, or by the supplier and is ready for review.
job.ready_for_production
Occurs either when an admin has approved all artwork for a job, or when a customer has accepted provided fixup files or accepted highlighted issues.
job.pending_proof_approval
Occurs when an admin sends proof(s) to the customer
job.proof_rejected
Occurs when a customer rejects one or more proofs in a job
job.proof_accepted
Occurs when a customer approved all proofs in a job
job.complete
Occurs when an admin marks a job as complete
Steps to receive webhooks
- Identify the events you want to monitor, and the event payloads to parse.
- Create a webhook endpoint as an HTTP endpoint on your local server.
- Handle requests from Artworker by parsing each event object and returning
200or201response status codes - Test your webhook endpoint is working properly with ngrok
- Deploy your webhook endpoint so it's publicly accessible HTTPS URL
- Register your publicly accessible HTTPS URL in your Artworker account settings.
1: Identify the events to monitor
Use the list of events above (Webhook Events) to identify which events you want to recieve notification of and take a note of the event object payload.
2: Setting up locally
To get up and running locally, you will need
- A local application serving an endpoint like
http://localhost:8080/artworker_webhooks - To make this endpoint accessible to the internet
Route setup
const http = require('http');
const server = http.createServer((req, res) => {
if (req.method === 'POST' && req.url === '/artworker_webhooks') {
let body = '';
req.on('data', chunk => { body += chunk.toString(); });
req.on('end', () => {
console.log(body);
res.end('Event received');
});
} else {
res.statusCode = 404;
res.end('Not Found');
}
});
server.listen(8080, () => {
console.log('Server listening on http://localhost:8080');
});
Set up an HTTP endpoint on your local machine that can accept unauthenticated webhook requests with a POST method.
For a quick start, the code on the right is a small node app that starts a server on 8080 and accepts unauthenticated POST requests to http://localhost:8080/artworker_webhooks
Ngrok setup
Artworker cannot send events directly to your local system as the endpoint is not accessible to the internet. To change that ngrok can be used to route requests through a hosted endpoint to your local one. Once ngrok is installed from https://ngrok.com/, run the following command and make a note of the endpoint it outputs.
ngrok http 8080
Artworker setup
In the Artworker settings page, navigate to webhooks and create a new one with your ngrok url (dont forget to all the /artworker_webhooks to the end!) eg https://337f-86-175-154-122.ngrok.io/artworker_webhooks with the desired events.
Create a couple of test jobs and you should start to see events hitting the endpoint!
3: Handle events from Artworker
Check event objects
Each event is structured as an Webhook Event Object object with a event, eventId, and related Artworker resource nested under data. Your endpoint must check the event type and parse the payload of each event.
Return a 2xx response
Your endpoint should return a positive status code (2xx) quickly before executing any complicated procedures that might result in a timeout.
Built-in retries
Artworker's webhooks come equipped with automatic retry mechanisms for response status codes 3xx, 4xx, or 5xx. Artworker stop trying to deliver the request after 2 days.
4: Secure your webhooks (recommended)
Artworker has the option to authenticate the webhook events it sends to your endpoints by including a signature in the Artworker-Signature header of each event. This ensures that the events were sent by Artworker and not by an unauthorized third party.
To verify the signatures, you must first retrieve the secret for your endpoint from the Webhooks settings.
It's important to note that Artworker generates a unique secret key for each endpoint. If you have multiple endpoints, you will need to retrieve the secret for each one you want to verify signatures on.
Verifying signatures
Artworker-Signature:
t=1492774577,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
The Artworker-Signature header included in each signed event contains a timestamp and one signature. The timestamp is prefixed by t= and the signature by v1=
const artworkersig = req.headers['artworker-signature'];
let [timestamp, sig] = artworkersig.split(",")
timestamp = timestamp.replace("t=", "")
sig = sig.replace("v1=", "")
const stripeSecret = crypto.createHmac('sha256', STRIPE_SIGNING_SECRET)
.update(`${timestamp}.${body}`)
.digest('hex');
const verified = stripeSecret === sig
Artworker generates signatures using a hash-based message authentication code (HMAC) with SHA-256
Step 1: Extract the timestamp and signatures from the heade
Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.
The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). You can discard all other elements.
Step 2: Prepare the signed_payload string
The signed_payload string is created by concatenating:
The timestamp (as a string) The character . The actual JSON payload (that is, the request body) Step 3: Determine the expected signature Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.
Step 4: Compare the signatures
Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.
Preventing replay attacks
A replay attack occurs when a malicious party captures a legitimate payload and its accompanying signature and sends them again. To prevent such attacks, Artworker includes a timestamp in the Artworker-Signature header. This timestamp is part of the signed payload and is verified by the signature, making it impossible for the attacker to alter the timestamp without altering the signature. If the signature is still valid but the timestamp is outdated, your application can choose to reject the payload.
Artworker creates a new timestamp and signature each time it sends an event to your endpoint. In cases where Artworker retries sending an event (e.g., if your endpoint responded with a non-2xx status code on the previous attempt), a fresh signature and timestamp will be generated for the new delivery attempt.
Task API
Workflows & Tasks
Example task chain
Task 1: Import pdf
↓
Task 2: Add bleed
↓
Task 3: Generate thumbnails
↓
Task 4: Split pdf into pages
Processing files is done via workflows in the terminology of the Artworker REST API. Each workflow consists of one or more tasks chained together.
For example: The first task of a workflow could be importing the file(s) from a specified source. The second task could be getting quick insights on the file(s). The third tasks could be generating thumbnails.
It is possible to chain tasks and pass the output of one task to the next. This is useful if you want to add bleed and create a thumbnail or preview with the added bleed, for example.
Import Tasks
An import task is a task that imports one or multiple files into Artworker for use in other tasks. Examples of import tasks include downloading files from a URL. Imported files are only stored temporarily.
Typically, each workflow starts with an import task.
Postman Collection
Errors and Rate Limiting
The Artworker API responds with standard HTTP status codes, such as 400 (invalid data), 500 (internal server error), 503 (temporarily unavailable), or 429 (too many requests).
Rate Limiting
Some endpoints enforce dynamic rate limiting. These endpoints return the X-RateLimit-Limit and X-RateLimit-Remaining headers. If the limit is reached, a 429 error is returned along with a Retry-After header that specifies the time in seconds to wait before making the next request.
Endpoints Currently Rate Limited:
- Creating workflows
Failed Workflows and Tasks
Workflows and tasks that complete with an error will have their status set to error. More details about the error can be found in the error field within each task, system errors are listed below. In addition to these check the task documentation for Task specific errors.
| Error Code | Description |
|---|---|
| 0 | Unknown system error. |
| 1 | A generic server error occurred. |
| 2 | The server is currently unavailable. |
| 3 | The request was malformed or invalid. |
| 4 | The server received an invalid response from the upstream server. |
| 5 | The gateway is currently unavailable. |
| 30 | The network request timed out. |
Please do not automatically retry tasks. Artworker internally already retries tasks if there are retryable errors (such as network errors).
Create Workflows
POST https://open-api.artworker.io/v1/taskapi/workflows?api_key=[API_KEY]
Sample Body
{
"uuid": "myworkflow-123",
"tasks": {
"import": {
"operation": "import/URL",
"payload": {
"urls": ["https://.../example.pdf"]
}
},
"fixup": {
"operation": "run/pdf-advanced-edit",
"input": "import",
"payload": {
"pageRange": "1",
"options":{
"removePrinterMarks": {
"enabled": true
}
}
}
}
}
}
Create a workflow with one more tasks. This endpoint is asynchronous and responds immediately
| Parameter | Type | Required | Description |
|---|---|---|---|
| tasks | array | true | See Tasks. |
| uuid | string | false | A string to identify the workflow, used for associating it with an ID in your application without affecting functionality. |
UUID
The uuid field has no restrictions and is just for your reference, for example you want to associate this workflow with a specific order item in your system.
Tasks
Naming
It is required to give each task a unique name. You can name these tasks however you want, but only alphanumeric characters, -, and _ are allowed in the task names.
Input
The input parameter allows you to directly reference the name of another task created within the same workflow. If a task changes the PDF in some way (e.g., adds bleed), then it will output a new PDF; a task with a specified input will use the output of the previous task (note that if the task does not change the pdf, that tasks input will be used as its output). This allows you to chain tasks together and create a workflow for your files.
Looking at the example on the right, we've chosen to name the first task import and the second fixup.
| Parameter | Type | Required | Description |
|---|---|---|---|
| operation | string | true | Name of the operation (task) to be performed |
| input | string | required for any task that does not import files | Name of the input task. |
| payload | object | true | An object unique to the specified task. Please see individual task documentation for details |
Create Workflow Response
{
"createdAt": "2025-01-31T07:03:45Z",
"id": 236,
"links": {
"self": "https://open-api.artworker.io/v1/taskapi/workflows/236"
},
"startedAt": "2025-01-31T07:03:45Z",
"status": "pending",
"tasks": [
{
"createdAt": "2025-01-31T07:03:45Z",
"dependsOn": "",
"error": null,
"id": 496,
"links": {
"self": "https://open-api.artworker.io/v1/taskapi/workflows/236/task/import"
},
"name": "import",
"operation": "import/URL",
"payload": {
"urls": [
"https://.../example.pdf"
]
},
"status": "pending",
"summary": null
},
{
"createdAt": "2025-01-31T07:03:45Z",
"dependsOn": "quick-insights",
"error": null,
"id": 498,
"links": {
"files": [
"https://open-api.artworker.io/v1/taskapi/workflows/236/task/fixup/files/1"
],
"self": "https://open-api.artworker.io/v1/taskapi/workflows/236/task/fixup"
},
"name": "fixup",
"operation": "run/pdf-advanced-edit",
"payload": {
"options": {
"removePrinterMarks": {
"enabled": true
}
},
"outputFilenames": [
{
"fileNum": 1,
"outputFilename": "output.pdf"
}
],
"pageRange": "1"
},
"status": "pending",
"summary": null
}
],
"uuid": "myworkflow-123"
}
See the Get a Workflow section for more details about the workflow response
Available Tasks
Measurement Unit
The TaskAPI allows you to work in mm or inches when working with dimensions. Anywhere in the documentation that refers ti the measurement unit is refering to a string that is either mm or inches
| Field | Type | Description |
|---|---|---|
| unit | string | one of [mm, inches] |
Get a Workflow
GET https://open-api.artworker.io/v1/taskapi/workflows/100?api_key=[API_KEY]
Sample Response
{
"id": 100,
"uuid": "myworkflow-123",
"status": "completed",
"createdAt": "2024-12-18T11:00:03.721923Z",
"endedAt": "2024-12-18T11:00:06.642034Z",
"tasks": [
{
"id": 200,
"operation": "import/URL",
"name": "import",
"payload": {
"urls": [
"https://storage.googleapis.com/kudo-web-assets/upload-examples/example_five.pdf"
]
},
"status": "completed",
"error": null,
"createdAt": "2024-12-18T11:00:03.725411Z",
"startedAt": "2024-12-18T11:00:03.725411Z",
"endedAt": "2024-12-18T11:00:03.811505Z",
"links": {
"self": "https://open-api.artworker.io/workflow/100/task/import"
}
},
{
"id": 201,
"operation": "run/pdf-advanced-edit",
"name": "fixup",
"dependsOn": "import",
"payload": {
"options": {
"removePrinterMarks": {
"enabled": true
}
},
"pageRange": "1"
},
"status": "completed",
"error": null,
"createdAt": "2024-12-18T11:00:03.725411Z",
"startedAt": "2024-12-18T11:00:03.725411Z",
"endedAt": "2024-12-18T11:00:03.811505Z",
"links": {
"self": "https://open-api.artworker.io/workflow/100/task/fixup",
"files": [
"https://open-api.artworker.io/workflow/100/task/import/files/1"
]
}
}
],
"links": {
"self": "https://open-api.artworker.io/workflow/100"
}
}
This endpoint is asynchronous and immediately responds the workflow status, even if the workflow has not completed yet.
Returns
| Field | Type | Description |
|---|---|---|
| id | int | Unique identifier of the workflow. |
| uuid | string | User-defined unique ID to track the workflow. |
| status | string | Current status of the workflow: one of pending, running, completed, or error. |
| tasks | array | List of tasks in the workflow. See the "Get Tasks" endpoint for task model details. |
| createdAt | string | ISO 8601 timestamp when the workflow was created. |
| endedAt | string | ISO 8601 timestamp when the workflow finished. |
| links | object | See Links |
Links
| Field | Type | Description |
|---|---|---|
| self | string | URL to fetch that object, in the example we have https://open-api.artworker.io/workflow/100/task/import that can be used to get the import task. |
| files | string[] | If the task provides outputs for each file, links to each file can be found in this array. In the example, we are importing one file and the fixup task outputs data for each file it processes, the output for this file can e found at https://open-api.artworker.io/workflow/100/task/import/files/1 |
Provides links for this workflow. Always contains self
Get a Task
Get https://open-api.artworker.io/v1/taskapi/workflows/100/task/fixup?api_key=[API_KEY]
Sample Response
{
"id": 201,
"operation": "run/pdf-advanced-edit",
"name": "fixup",
"dependsOn": "import",
"payload": {
"options": {
"removePrinterMarks": {
"enabled": true
}
},
"pageRange": "1"
},
"status": "completed",
"error": null,
"createdAt": "2024-12-18T11:00:03.725411Z",
"startedAt": "2024-12-18T11:00:03.725411Z",
"endedAt": "2024-12-18T11:00:03.811505Z",
"links": {
"self": "https://open-api.artworker.io/workflow/100/task/fixup",
"files": [
"https://open-api.artworker.io/workflow/100/task/import/files/1"
]
}
}
Returns
| Field | Type | Description |
|---|---|---|
| id | int | Unique identifier of the task. |
| operation | string | Name of the operation, for example import/URL or run/pdf-advanced-edit. |
| dependsOn | string | Name of previous task in workflow. |
| payload | object | Your submitted payload for the tasks. Depends on the operation type. |
| status | string | Current status of the task: one of pending, running, completed, or error. |
| createdAt | string | ISO 8601 timestamp when the task was created. |
| startedAt | string | ISO 8601 timestamp when the task started. |
| endedAt | string | ISO 8601 timestamp when the task finished. |
| links | object | See Links |
Get the file list from a task
Get https://open-api.artworker.io/v1/taskapi/workflows/100/task/gen-thumbnails/files?api_key=[API_KEY]&offset=0&size=10
Sample Response
[
{
"fileNum": 1,
"output": {
"pages": [
{
"fileNum": 1,
"output": {
"thumbnailFilename": "thumb_custom1.jpg",
"thumbnailUrl": "https://.../thumb_custom1.jpg"
},
"page": 1
}
]
}
},
{
"fileNum": 2,
"output": {
"pages": [
{
"fileNum": 2,
"output": {
"thumbnailFilename": "thumb_custom1.jpg",
"thumbnailUrl": "https://.../thumb_custom1.jpg"
},
"page": 1
}
]
}
}
]
The example to the right shows the output of a task that generates thumbnails.
Query Params
| Field | Type | Description |
|---|---|---|
| offset | int | Index of the record to start on. |
| size | object | Number of records to return. |
Returns
| Field | Type | Description |
|---|---|---|
| fileNum | int | File number. |
| output | object | Check the specified task for available output. |
Get a specific file from a task
Get https://open-api.artworker.io/v1/taskapi/workflows/100/task/gen-thumbnails/files/1?api_key=[API_KEY]
Sample Response
{
"pages": [
{
"fileNum": 1,
"output": {
"thumbnailFilename": "thumb_base123_0002.jpg",
"thumbnailUrl": "https://storage.googleapis.com/dev-imggen-results-bucket/9250b83c-31bf-45dc-b2c9-536120b727b5/thumb_base123_0002.jpg"
},
"page": 2
},
{
"fileNum": 1,
"output": {
"thumbnailFilename": "thumb_custom1.pdf.jpg",
"thumbnailUrl": "https://storage.googleapis.com/dev-imggen-results-bucket/553e8671-82fc-4aef-aadd-56ee8700ed9a/thumb_custom1.pdf.jpg"
},
"page": 1
}
]
}
The example to the right shows the output of a task that generates thumbnails.
Returns
The output for this request is defined by each individual task. Check the docs of a specific task for details.
Get a list of pages for a file in a Task
Get https://open-api.artworker.io/v1/taskapi/workflows/100/task/gen-thumbnails/files/1/pages?api_key=[API_KEY]&offset=0&size=10
Sample Response
[
{
"output": {
"thumbnailFilename": "thumb_custom1.jpg",
"thumbnailUrl": "https://.../thumb_custom1.jpg"
},
"page": 1
},
{
"output": {
"thumbnailFilename": "thumb_custom2.jpg",
"thumbnailUrl": "https://.../thumb_custom2.jpg"
},
"page": 2
}
]
The example to the right shows the output of a task that generates thumbnails.
Query Params
| Field | Type | Description |
|---|---|---|
| offset | int | Index of the record to start on. |
| size | object | Number of records to return. |
Returns
| Field | Type | Description |
|---|---|---|
| page | int | Page number. |
| output | object | Check the specified task for available output. |
Get a single page for a file in a Task
Get https://open-api.artworker.io/v1/taskapi/workflows/100/task/gen-thumbnails/files/1/pages/1?api_key=[API_KEY]
Sample Response
{
"thumbnailFilename": "thumb_custom1.jpg",
"thumbnailUrl": "https://.../thumb_custom1.jpg"
}
The example to the right show the output of a task that generates thumbnails.
Returns
The output for this request is defined by each individual task. Check the docs of a specific task for details.
Import from URL Task
POST https://open-api.artworker.io/v1/taskapi/workflows?api_key=[API_KEY]
Sample Body
{
"uuid": "myworkflow-123",
"tasks": {
"import": {
"operation": "import/URL",
"payload": {
"urls": ["https://storage.googleapis.com/kudo-web-assets/upload-examples/example_five.pdf"]
}
}
}
}
This task accepts a list of urls of files to import into the Artworker system. Each workflow must start with an import task.
Operation
import/URL
Options
| Field | Type | Description |
|---|---|---|
| urls | string array | List of urls of files to import ready for processing. |
Results
There are no results available for this operation
Quick Insights Task
This task returns key metrics about a pdf (e.g. colours used, fonts used, dimensions and more).
Optionally you can also pass in "checks" which pass, fail, or give a warning. For example, if you want the document to only include CMYK colours, then you can pass a colour check with CMYK as the only allowedColours in the checkColours check. The response will let you know if each of your checks have passed or failed.
Quick Insights Operation
run/quick-insights
Quick Insights Payload
POST https://open-api.artworker.io/v1/taskapi/workflows?api_key=[API_KEY]
Sample Body
{
"uuid": "myworkflow-123",
"tasks": {
"import": {
"operation": "import/URL",
"payload": {
"urls": ["https://.../example.pdf"]
}
},
"quick-insights": {
"operation": "run/quick-insights",
"input": "import",
"payload": {
"checks": {
"unit": "mm",
"colours": {
"checkColours": {
"checkEnabled": true,
"allowedColours": ["CMYK"]
}
},
"dimensions": {
"trim": {
"checkEnabled": true,
"width": 152,
"height": 210
},
"aspectRatio": {
"checkEnabled": true,
"passTolerancePercentage": 2,
"warnTolerancePercentage": 5
},
"orientation": {
"checkEnabled": true,
"requiredOrientation": "Portrait"
},
"bleed": {
"checkEnabled": true,
"top": 2,
"bottom": 2,
"left": 2,
"right": 2
}
},
"fonts": {
"requireEmbeddedFonts": {
"checkEnabled": true
}
},
"images": {
"resolution": {
"checkEnabled": true,
"checkResolutionSize": "actual size",
"recomendedDPI": 500,
"warnBelowDPI": 300,
"errorBelowDPI": 150
}
}
}
}
}
}
}
See the POST request to the right of this for an example payload.
Available Quick Insights
QuickInsights allow you to define specific expectations for a PDF by enabling various checks and providing the required input. Each enabled check evaluates the PDF and returns one of three outcomes: pass, fail, or warn, along with additional details.
These checks are performed on each page of the PDF individually, with results available at both the page and file levels. For example, if a 3-page PDF contains a low-resolution image on page 1, the file and page 1 will fail, while pages 2 and 3 will pass.
Colours - CheckColours
Fails if any colours exist in the pdf that aren't included in the allowedColours array.
Input
"colours": {
"checkColours": {
"checkEnabled": true,
"allowedColours": ["CMYK"]
}
}
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Whether color checks are performed. |
| allowedColours | string[] |
List of allowed color spaces ("CMYK"/"RGB"/"SPOT"/"PMS"). |
Output
{
"checkEnabled": true,
"input": {
"allowedColours": [
"CMYK"
]
},
"key": "checkColours",
"name": "Allowed Colours",
"output": {
"coloursFound": [
"CMYK"
]
},
"status": "pass",
"summary": "4 colours found"
}
| Field | Type | Description |
|---|---|---|
| coloursFound | string[] |
List of color spaces found. |
Dimensions - TrimSize
Passes if the actual height and width match the expected dimensions, or if the actual size is correct but presented in a different orientation.
Input
"dimensions": {
"trim": {
"checkEnabled": true,
"width": 152,
"height": 210
}
}
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Whether trim dimension checks are performed. |
| width | number |
Page width in the specified measurement unit. |
| height | number |
Page height in the specified measurement unit. |
Output
{
"checkEnabled": true,
"input": {
"height": 210,
"unit": "mm",
"width": 152
},
"key": "trimSize",
"name": "Trim Size",
"output": {
"allPagesUniform": true,
"height": 210,
"unit": "mm",
"width": 148
},
"status": "fail",
"summary": "Trim size does not match config: expected (152.0000x210.0000 mm), got (148.0000x210.0000 mm)."
}
| Field | Type | Description |
|---|---|---|
| allPagesUniform | boolean |
Returns true if all pages are the same height and width, not available in reponse for single page. |
| width | number |
Actual page width in the specified measurement unit. |
| height | number |
Actual page height in the specified measurement unit. |
| unit | mm, inches |
Unit used. |
Dimensions - Aspect Ratio
Requires the TrimSize check. Calculates the expected aspect ratio from trimSize.height and trimSize.width. Passes if the actual aspect ratio is within passTolerancePercentage, warns if within warnTolerancePercentage, and fails otherwise.
Input
"dimensions": {
"aspectRatio": {
"checkEnabled": true,
"passTolerancePercentage": 2,
"warnTolerancePercentage": 5
}
}
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Whether aspect ratio checks are performed. |
| passTolerancePercentage | number |
The tolerance (in percent) for the aspect ratio to pass without warnings or errors. |
| warnTolerancePercentage | number |
The tolerance (in percent) beyond which a warning is issued for the aspect ratio. |
Output
{
"checkEnabled": true,
"input": {
"passTolerancePercentage": 2,
"warnTolerancePercentage": 5
},
"key": "aspectRatio",
"name": "AspectRatioCheck",
"output": {
"allPagesUniform": true,
"aspectRatio": 0.7047621607456038,
"deviationPercentage": 2.6315435811994687
},
"status": "warn",
"summary": "Config AR=0.7238, Page AR=0.7048, diff=2.63% => warn"
}
Requires the TrimSize check. Calculates the expected aspect ratio from trimSize.height and trimSize.width. Passes if the actual aspect ratio is within passTolerancePercentage, warns if within warnTolerancePercentage, and fails otherwise.
| Field | Type | Description |
|---|---|---|
| allPagesUniform | boolean |
Returns true if all pages have the same aspect ratio, not available in reponse for single page. |
| aspectRatio | number |
Actual aspect ratio. |
| deviationPercentage | number |
Percentage the actual aspect ratio deviates from the expected aspect ratio. |
Dimensions - Orientation
Passes if orientation matches the given required orientation
Input
"dimensions": {
"orientation": {
"checkEnabled": true,
"requiredOrientation": "Portrait"
}
}
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Whether orientation checks are performed. |
| requiredOrientation | Portrait, Landscape |
Required orientation ("Portrait"/"Landscape"). |
Output
{
"checkEnabled": true,
"input": {
"orientation": "Portrait"
},
"key": "orientation",
"name": "Orientation",
"output": {
"allPagesUniform": true,
"orientation": "Portrait"
},
"status": "pass",
"summary": null
}
| Field | Type | Description |
|---|---|---|
| allPagesUniform | boolean |
Returns true if all pages have the same orientation, not available in reponse for single page. |
| orientation | Portrait, Landscape |
Actual orientation. |
Dimensions - Bleed
Passes if actual bleed matches the expected bleed for each side
Input
"dimensions": {
"bleed": {
"checkEnabled": true,
"top": 2,
"bottom": 2,
"left": 2,
"right": 2
}
}
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Whether bleed checks are performed. |
| top | number |
Top bleed in the specified measurement unit. |
| bottom | number |
Bottom bleed in the specified measurement unit. |
| left | number |
Left bleed in the specified measurement unit. |
| right | number |
Right bleed in the specified measurement unit. |
Output
{
"checkEnabled": true,
"input": {
"bottom": 0,
"left": 0,
"right": 0,
"top": 0,
"unit": "mm"
},
"key": "bleed",
"name": "Bleed",
"output": {
"allPagesUniform": true,
"bottom": 0,
"left": 0,
"right": 0,
"top": 0,
"unit": "mm"
},
"status": "pass",
"summary": null
}
| Field | Type | Description |
|---|---|---|
| allPagesUniform | boolean |
Returns true if all pages have the same bleed, not available in reponse for single page. |
| top | number |
Actual top bleed in the specified measurement unit. |
| bottom | number |
Actual bottom bleed in the specified measurement unit. |
| left | number |
Actual left bleed in the specified measurement unit. |
| right | number |
Actual right bleed in the specified measurement unit. |
| unit | mm, inches |
Unit used. |
Fonts - Require Embedded Fonts
Fails if there are one or more embedded fonts
Input
"fonts": {
"requireEmbeddedFonts": {
"checkEnabled": true
}
}
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Whether a check is performed to ensure all fonts are embedded. |
Output
{
"checkEnabled": true,
"input": null,
"key": "fontsEmbedded",
"name": "Require Embedded Fonts",
"output": {
"fontsFound": []
},
"status": "pass",
"summary": "0 unembedded fonts found"
}
| Field | Type | Description |
|---|---|---|
| fontsFound | string[] |
List of fonts found. |
Resolution
Fails if the lowest image resolution is below errorBelowDPI. Warns if it falls between warnBelowDPI and errorBelowDPI. Passes if it exceeds both thresholds. recomendedDPI is referenced in the summary.
Input
"images": {
"resolution": {
"checkEnabled": true,
"checkResolutionSize": "actual size",
"recomendedDPI": 500,
"warnBelowDPI": 300,
"errorBelowDPI": 150
}
}
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Whether image resolution checks are performed. |
| checkResolutionSize | string |
Mode for resolution checking ("actual size"/"expected size"). |
| recomendedDPI | number |
The recommended DPI for images. Used for returned summary. |
| warnBelowDPI | number |
The threshold (DPI) below which a warning is issued for image resolution. |
| errorBelowDPI | number |
The threshold (DPI) below which an error is raised for image resolution. |
Output
{
"checkEnabled": true,
"input": {
"checkResolutionSize": "actual size",
"errorBelowDPI": 150,
"recomendedDPI": 500,
"warnBelowDPI": 300
},
"key": "imageResolution",
"name": "Resolution",
"output": {
"minImageResolutionDPI": 0
},
"status": "pass",
"summary": "No images found"
}
}
| Field | Type | Description |
|---|---|---|
| minImageResolutionDPI | boolean |
Value of image in the document with the lowest DPI. |
Quick Insight Results
Response Structure
Response Object
Sample Response Structure
{
"checks": {
":check-category": {
"checks": {
":individual-check": QuickInsight Object,
"status": "pass"
},
},
"status": "fail"
}
| Field | Type | Description |
|---|---|---|
| checks | object |
List of checks divided into categories. |
| status | pass, fail, warn |
Overall status. |
sample
aspect ratio insightpage results
"aspectRatio": {
"checkEnabled": true,
"input": {
"passTolerancePercentage": 2,
"warnTolerancePercentage": 5
},
"key": "aspectRatio",
"name": "AspectRatioCheck",
"output": {
"allPagesUniform": true,
"aspectRatio": 0.75,
"deviationPercentage": 2.6
},
"status": "warn",
"summary": "Config AR=0.7238, Page AR=0.7048, diff=2.63% => warn"
}
QuickInsight Object
Results for each QuickInsight (eg aspectRatio or fontsEmbedded) are returned in a set format. Data that is specific to that particular check (eg the value of the aspectRatio or a list of fonts) is returned in the output object.
| Field | Type | Description |
|---|---|---|
| checkEnabled | boolean |
Indicates if the check is enabled (true or false). |
| input | object |
Input details for the check. The structure varies by check type. |
| key | string |
Unique identifier for the check. |
| name | string |
Human-readable name of the check. |
| output | object |
Output details of the check. The structure varies by check type. |
| status | string |
The result of the check (e.g., "passed", "failed", "warning"). |
| summary | string |
A brief description of the check result. |
If the response refers to multiple pages (eg when getting the results of a file), the following additional summary data will be available
Sample
aspect ratio insightfile results
"aspectRatio": {
"checkEnabled": true,
"failures": {
"count": 0,
"affectedPages": null
},
"input": {
"passTolerancePercentage": 2,
"warnTolerancePercentage": 5
},
"key": "aspectRatio",
"name": "AspectRatioCheck",
"output": {
"allPagesUniform": true,
"aspectRatio": 0.75,
"deviationPercentage": 2.6
},
"status": "warn",
"summary": "2 page(s) produced warnings for \"AspectRatioCheck\"",
"warnings": {
"count": 2,
"affectedPages": [
1,
2
]
}
}
| Field | Type | Description |
|---|---|---|
| failures | object |
Details of failed checks. |
| failures.count | int |
Total number of failed checks. |
| failures.affectedPages | int[], null |
Array of affected page numbers or null if no failures. |
| warnings | object |
Details of warnings. |
| warnings.count | int |
Total number of warnings. |
| warnings.affectedPages | int[],null |
Array of affected page numbers or null if no warnings. |
Sample Results
Sample Page Results
GET https://open-api.artworker.io/v1/taskapi/workflows/100/task/quick-insights/files/1/pages/1?api_key=[API_KEY]
Sample Page Response
{
"checks": {
"colours": {
"checks": {
"checkColours": {
"checkEnabled": true,
"input": {
"allowedColours": [
"CMYK"
]
},
"key": "checkColours",
"name": "Allowed Colours",
"output": {
"coloursFound": [
"CMYK"
]
},
"status": "pass",
"summary": "4 colours found"
}
},
"status": "pass"
},
"dimensions": {
"checks": {
"aspectRatio": {
"checkEnabled": true,
"input": {
"passTolerancePercentage": 2,
"warnTolerancePercentage": 5
},
"key": "aspectRatio",
"name": "AspectRatioCheck",
"output": {
"allPagesUniform": true,
"aspectRatio": 0.7047621607456038,
"deviationPercentage": 2.6315435811994687
},
"status": "warn",
"summary": "Config AR=0.7238, Page AR=0.7048, diff=2.63% => warn"
},
"bleed": {
"checkEnabled": true,
"input": {
"bottom": 0,
"left": 0,
"right": 0,
"top": 0,
"unit": "mm"
},
"key": "bleed",
"name": "Bleed",
"output": {
"allPagesUniform": true,
"bottom": 0,
"left": 0,
"right": 0,
"top": 0,
"unit": "mm"
},
"status": "pass",
"summary": null
},
"orientation": {
"checkEnabled": true,
"input": {
"orientation": "Portrait"
},
"key": "orientation",
"name": "Orientation",
"output": {
"allPagesUniform": true,
"orientation": "Portrait"
},
"status": "pass",
"summary": null
},
"trimSize": {
"checkEnabled": true,
"input": {
"height": 210,
"unit": "mm",
"width": 152
},
"key": "trimSize",
"name": "Trim Size",
"output": {
"allPagesUniform": true,
"height": 210,
"unit": "mm",
"width": 148
},
"status": "fail",
"summary": "Trim size does not match config: expected (152.0000x210.0000 mm), got (148.0000x210.0000 mm)."
}
},
"status": "fail"
},
"fonts": {
"checks": {
"fontsEmbedded": {
"checkEnabled": true,
"input": null,
"key": "fontsEmbedded",
"name": "Require Embedded Fonts",
"output": {
"fontsFound": []
},
"status": "pass",
"summary": "0 unembedded fonts found"
}
},
"status": "pass"
},
"images": {
"checks": {
"imageResolution": {
"checkEnabled": true,
"input": {
"checkResolutionSize": "actual size",
"errorBelowDPI": 150,
"recomendedDPI": 500,
"warnBelowDPI": 300
},
"key": "imageResolution",
"name": "Resolution",
"output": {
"minImageResolutionDPI": 0
},
"status": "pass",
"summary": "No images found"
}
},
"status": "pass"
}
},
"status": "fail"
}
GET https://open-api.artworker.io/v1/taskapi/workflows/:workflowId/task/:taskName/files/:fileNum?api_key=[API_KEY]
Sample File Response
{
"checks": {
"colours": {
"checks": {
"checkColours": {
"checkEnabled": true,
"failures": {
"count": 0,
"affectedPages": null
},
"input": {
"allowedColours": [
"CMYK"
]
},
"key": "checkColours",
"name": "Allowed Colours",
"output": {
"coloursFound": [
"CMYK"
]
},
"status": "pass",
"summary": "All pages passed \"Allowed Colours\"",
"warnings": {
"count": 0,
"affectedPages": null
}
}
},
"failures": {
"count": 0,
"affectedPages": null
},
"name": "colours",
"status": "pass",
"warnings": {
"count": 0,
"affectedPages": null
}
},
"dimensions": {
"checks": {
"aspectRatio": {
"checkEnabled": true,
"failures": {
"count": 0,
"affectedPages": null
},
"input": {
"passTolerancePercentage": 2,
"warnTolerancePercentage": 5
},
"key": "aspectRatio",
"name": "AspectRatioCheck",
"output": {
"allPagesUniform": true,
"aspectRatio": 0.7047621607456038,
"deviationPercentage": 2.6315435811994687
},
"status": "warn",
"summary": "2 page(s) produced warnings for \"AspectRatioCheck\"",
"warnings": {
"count": 2,
"affectedPages": [
1,
2
]
}
},
"bleed": {
"checkEnabled": true,
"failures": {
"count": 0,
"affectedPages": null
},
"input": {
"bottom": 0,
"left": 0,
"right": 0,
"top": 0,
"unit": "mm"
},
"key": "bleed",
"name": "Bleed",
"output": {
"allPagesUniform": true,
"bottom": 0,
"left": 0,
"right": 0,
"top": 0,
"unit": "mm"
},
"status": "pass",
"summary": "All pages passed \"Bleed\"",
"warnings": {
"count": 0,
"affectedPages": null
}
},
"orientation": {
"checkEnabled": true,
"failures": {
"count": 0,
"affectedPages": null
},
"input": {
"orientation": "Portrait"
},
"key": "orientation",
"name": "Orientation",
"output": {
"allPagesUniform": true,
"orientation": "Portrait"
},
"status": "pass",
"summary": "All pages passed \"Orientation\"",
"warnings": {
"count": 0,
"affectedPages": null
}
},
"trimSize": {
"checkEnabled": true,
"failures": {
"count": 2,
"affectedPages": [
1,
2
]
},
"input": {
"height": 210,
"unit": "mm",
"width": 152
},
"key": "trimSize",
"name": "Trim Size",
"output": {
"allPagesUniform": true,
"height": 210,
"unit": "mm",
"width": 148
},
"status": "fail",
"summary": "2 page(s) failed the \"Trim Size\" check",
"warnings": {
"count": 0,
"affectedPages": null
}
}
},
"failures": {
"count": 2,
"affectedPages": [
1,
2
]
},
"name": "dimensions",
"status": "fail",
"warnings": {
"count": 0,
"affectedPages": null
}
},
"fonts": {
"checks": {
"fontsEmbedded": {
"checkEnabled": true,
"failures": {
"count": 0,
"affectedPages": null
},
"input": null,
"key": "fontsEmbedded",
"name": "Require Embedded Fonts",
"output": {
"fontsFound": []
},
"status": "pass",
"summary": "All pages passed \"Require Embedded Fonts\"",
"warnings": {
"count": 0,
"affectedPages": null
}
}
},
"failures": {
"count": 0,
"affectedPages": null
},
"name": "fonts",
"status": "pass",
"warnings": {
"count": 0,
"affectedPages": null
}
},
"images": {
"checks": {
"imageResolution": {
"checkEnabled": true,
"failures": {
"count": 0,
"affectedPages": null
},
"input": {
"checkResolutionSize": "actual size",
"errorBelowDPI": 150,
"recomendedDPI": 500,
"warnBelowDPI": 300
},
"key": "imageResolution",
"name": "Resolution",
"output": {
"minImageResolutionDPI": 0
},
"status": "pass",
"summary": "All pages passed \"Resolution\"",
"warnings": {
"count": 0,
"affectedPages": null
}
}
},
"failures": {
"count": 0,
"affectedPages": null
},
"name": "images",
"status": "pass",
"warnings": {
"count": 0,
"affectedPages": null
}
}
},
"failures": {
"count": 2,
"affectedPages": [
1,
2
]
},
"status": "fail",
"warnings": {
"count": 0,
"affectedPages": []
}
}
Sample File Results
Split PDF Task
A task that splits a PDF into multiple files based on the number of pages.
Split PDF Operation
run/pdf-split
Split PDF Payload
POST https://open-api.artworker.io/v1/taskapi/workflows?api_key=[API_KEY]
Sample Body
{
"uuid": "myworkflow-123",
"tasks": {
"import": {
"operation": "import/URL",
"payload": {
"urls": ["https://.../example.pdf"]
}
},
"split": {
"operation": "run/pdf-split",
"input": "import",
"payload": {
"namingStrategy": {
"baseName": "base123",
"individualNames": ["custom1"]
}
}
}
}
}
| Field | Type | Description |
|---|---|---|
| namingStrategy.baseName | string | Required. Sets the base name for generated pages (e.g., "result" → "result_001.pdf", "result_002.pdf", etc.). |
| namingStrategy.individualNames | string[] | List of custom file names (e.g., ["page_001", "page_002"]). If not enough entries are provide, falls back to baseName. |
Split PDF Results
GET https://open-api.artworker.io/v1/taskapi/workflows/:workflowId/task/:taskName/files/:fileNum?api_key=[API_KEY]
Sample File Response
{
"splitFiles": [
{
"filename": "custom1.pdf",
"page": 1,
"url": "https://.../custom1.pdf"
},
{
"filename": "base123_0002.pdf",
"page": 2,
"url": "https://.../base123_0002.pdf"
}
]
}
| Field | Type | Description |
|---|---|---|
| filename | string | Name of saved file. |
| page | string | Page number of file. |
| url | string | Url to access file. |
Preview Generation Task
Generates thumbnails or previews for each page of a PDF.
Preview Generation Operation
build/preview
Preview Generation Payload
POST https://open-api.artworker.io/v1/taskapi/workflows?api_key=[API_KEY]
Sample Body
{
"uuid": "myworkflow-123",
"tasks": {
"import": {
"operation": "import/URL",
"payload": {
"urls": ["https://.../example.pdf"]
}
},
"thumnails-and-previews": {
"operation": "build/preview",
"input": "import",
"payload": {
"contentType": "application/pdf",
"buildThumbnails": true,
"buildPreview": true,
"thumbnailMaxWidth": 350,
"thumbnailMaxHeight": 350,
"thumbnailResolution": 300,
"thumbnailQuality": 60,
"previewMaxWidth": 1024,
"previewMaxHeight": 1024,
"previewResolution": 300,
"previewQuality": 60,
"namingStrategy": {
"baseName": "base123",
"individualNames": ["custom1"]
}
}
}
}
}
Payload
| Field | Type | Description |
|---|---|---|
| contentType | string | Required. Sets the contentType of the input file (eg "application/pdf"). |
| buildThumbnails | bool | If true, thumbnails will be generated for each page of the pdf. |
| buildPreview | bool | If true, previews will be generated for each page of the pdf. |
| namingStrategy | Naming Strategy | Optional. Sets a naming strategy for the output filenames |
| thumbnailMaxWidth | int | Optional. Sets the maximum width (px) of the generated thumbnails. |
| thumbnailMaxHeight | int | Optional. Sets the maximum height (px) of the generated thumbnails. |
| thumbnailQuality | int | Optional. Sets the quality of the generated preview image. Accepts a value between 1 (lowest quality, highest compression) and 100 (highest quality, least compression). Higher values result in better image quality but larger file sizes. 80 is the recommended value thumbnails. |
| thumbnailResolution | int | Optional. Specifies the resolution of the generated preview in dots per inch (DPI). A higher DPI results in a more detailed image but increases file size. 300 is the recommended value |
| previewMaxWidth | int | Optional. Sets the maximum width (px) of the generated previews. |
| previewMaxHeight | int | Optional. Sets the maximum height (px) of the generated previews. |
| previewQuality | int | Optional. Sets the quality of the generated preview image. Accepts a value between 1 (lowest quality, highest compression) and 100 (highest quality, least compression). Higher values result in better image quality but larger file sizes. 80 is the recommended value |
| previewResolution | int | Optional. Specifies the resolution of the generated preview in dots per inch (DPI). A higher DPI results in a more detailed image but increases file size. 300 is the recommended value |
Naming Strategy
| Field | Type | Description |
|---|---|---|
| namingStrategy.baseName | string | Required. Sets the base name for generated pages (e.g., "result" → "result_001.pdf", "result_002.pdf", etc.). |
| namingStrategy.individualNames | string[] | List of custom file names (e.g., ["page_001", "page_002"]). If not enough entries are provide, falls back to baseName. |
Preview Generation Results
Single Page
GET https://open-api.artworker.io/v1/taskapi/workflows/:workflowId/task/:taskName/files/:fileNum/pages/:pageNum?api_key=[API_KEY]
Sample File Response
{
"thumbnailFilename": "thumb_custom1.jpg",
"thumbnailUrl": "https://.../thumb_custom1.jpg",
"previewFilename": "preview_custom1.jpg",
"previewUrl": "https://.../preview_custom1.jpg"
}
File
GET https://open-api.artworker.io/v1/taskapi/workflows/:workflowId/task/:taskName/files/:fileNum?api_key=[API_KEY]
Sample File Response
{
"pages": [
{
"fileNum": 1,
"output": {
"thumbnailFilename": "thumb_custom1.jpg",
"thumbnailUrl": "https://.../thumb_custom1.jpg",
"previewFilename": "preview_custom1.jpg",
"previewUrl": "https://.../preview_custom1.jpg"
},
"page": 1
},
{
"fileNum": 1,
"output": {
"thumbnailFilename": "thumb_base123_0002.jpg",
"thumbnailUrl": "https://.../thumb_base123_0002.jpg",
"previewFilename": "preview_base123_0002.jpg",
"previewUrl": "https://.../preview_base123_0002.jpg"
},
"page": 2
}
]
}
| Field | Type | Description |
|---|---|---|
| thumbnailFilename | string | Name of saved thumbnail file. |
| thumbnailUrl | string | Url of saved thumbnail file. |
| previewFilename | string | Name of saved preview file. |
| thumbnailUrl | string | Url of saved preview file. |
Advanced PDF Edit Task
POST https://open-api.artworker.io/v1/taskapi/workflows?api_key=[API_KEY]
Sample Body
{
"uuid": "myworkflow-123",
"tasks": {
"import": {
"operation": "import/URL",
"payload": {
"urls": ["https://.../example.pdf"]
}
},
"fixup": {
"operation": "run/pdf-advanced-edit",
"input": "import",
"payload": {
"pageRange": "1",
"outputFilenames": [{
"fileNum": 1,
"outputFilename": "output.pdf"
}],
"options":{
"removePrinterMarks": {
"enabled": true
},
"removeContentOutsideBleed": {
"enabled": true
},
"addCropMarks": {
"enabled": false
},
"pageRotation": {
"enabled": false,
"angle": 0,
"pageSelector": ""
},
"removePage": {
"enabled": false,
"pageSelector": ""
},
"addPage": {
"enabled": false,
"beforeAfter": "After",
"pageSelector": "1",
"numberOfCopies": 1,
"copyContent": false
},
"splitPage": {
"enabled": false,
"pageSelector": "1*",
"reorderPage": false
},
"bleedboxFixGeometry": {
"enabled": true
},
"optimisePDF": {
"enabled": true
},
"renameLayer": {
"enabled": false,
"layerRegEx": ".*",
"newName": ""
},
"removeLayer": {
"enabled": false,
"layerRegEx": ".*"
},
"removeContentFromLayer": {
"enabled": true
},
"flattenLayers": {
"enabled": false
},
"splitInHalf": {
"enabled": false
},
"readerSpreads": {
"enabled": false,
"coverPage": true
},
"resizePage": {
"enabled": false,
"width": 210,
"height": 297,
"method": "homothetical"
},
"generateBleed": {
"enabled": true,
"sizeLeft": 3.0,
"sizeRight": 3.0,
"sizeTop": 3.0,
"sizeBottom": 3.0,
"minCheck": 80.0,
"method": "mirror",
"generateOnLayer": true,
"bleedLayerName": "generatedBleed"
},
"embedOutputIntent": {
"enabled": true,
"outputIntent": "ISO Coated v2 300% (ECI)"
},
"convertRegistrationToBlack": {
"enabled": false
},
"knockoutWhite": {
"enabled": true,
"applyTo": "Vector-Text"
},
"overprintBlackText": {
"enabled": true,
"minTextSize": 9.0
},
"convertTextToOutlines": {
"enabled": false
},
"cutPath": {
"enabled": true,
"separationName": "Thru-cut",
"alternateC": 0,
"alternateM": 0,
"alternateY": 0,
"alternateK": 0,
"layerName": "cutPath"
}
}
}
}
}
}
This task applies a set of defined edits to a PDF. The available edits are list below in the Payload section.
Operation
run/pdf-advanced-edit
Payload
| Field | Type | Description |
|---|---|---|
| pageRange | string schema | Range of pages to apply changes to. See page selector |
| outputFilenames | array [{ "fileNum": 1, "outputFilename": "output.pdf"}] | Array of filenames with specific file numbers |
| options | object | list of pdf preflight options, see below for details |
Document
REMOVE PRINTER MARKS
Printer marks (crop marks and other registration elements) will be detected (as mush as it is possible in an automated process) and removed. This cannot be turned off.
REMOVE CONTENT OUTSIDE BLEED
Any content present outside the bleed box will be removed. This cannot be turned off.
ADD CROP MARKS
Crop marks, aligned on the trim box, can be added. Please note that this action will happen near the end of the process, once the trimbox and the bleedbox have been correctly setup.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| addCropMarks.enabled | Boolean | Activate or deactivate the fixup | false | false |
ROTATE PAGE(S)
PDF pages can be rotated by a specific angle, defined by the variable rotateAngle. The default value is 0. The selection of pages can be passed as the variable pageSelector (see page-selector schema).
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| pageRotation.enabled | Boolean | Activate or deactivate the fixup | false | false |
| pageRotation.angle | Number | Angle for rotation (0, 90, 180, or 270) | false | 0 |
| pageRotation.pageSelector | String schema | List of pages to be rotated | false | "" |
REMOVE PAGE(S)
PDF pages can be removed. The selection of pages can be passed as the variable pageSelector (see page-selector schema).
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| removePage.enabled | Boolean | Activate or deactivate the fixup | false | false |
| removePage.pageSelector | String schema | List of pages to be removed | false | "" |
ADD PAGE(S)
PDF pages can be added. Pages are added before or after each current selected page. This is defined with the variable bedforeAfter. The default value is After. The selection of pages is passed to the fixup using the variable pageSelector (see page-selector schema). This fixup can add a copy of the current page (which allows duplication) or a blank page, according the variable copyContent. The default value is false, which means that a blank page will be added. With the variable numberOfCopies, it is possible to duplicate the page(s) more than one time. The default value is 1, which means one copy.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| addPage.enabled | Boolean | Activate or deactivate the fixup | false | false |
| addPage.beforeAfter | String | Add the page before or after the current page (“Before”/“After”) | false | After |
| addPage.pageSelector | String schema | List of pages where pages will be added | false | 1 |
| addPage.numberOfCopies | Number | Number of times the page should be duplicated | false | 1 |
| addPage.copyContent | Boolean | Whether the added page is blank or a copy of the current page | false | false |
SPLIT AND REORDER PAGES
The PDF file can be split into separate PDF files. The split scheme is passed using the variable pageSelector (see page-selector schema). The default value is 1*, which means every page. Merging the pages again at the end of the process results of a reordering of the pages. This is triggered by the variable reorderPage.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| splitPage.enabled | Boolean | Activate or deactivate the fixup | false | false |
| splitPage.pageSelector | String schema | Split scheme | false | 1* |
| splitPage.reorderPage | Boolean | Activate or deactivate the reordering instead of split | false | false |
SET BLEED AND GEOMETRY BOXES
Geometry boxes, and in particular bleedbox can be setup. This one is very important for the bleed generation to be performed. It should always be on.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| bleedboxFixGeometry.enabled | Boolean | Activate or deactivate the fixup | false | true |
OPTIMISE PDF
The PDF is optimised for fast web view, so it can be served more quickly over the Internet by a web server that supports byte serving.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| optimisePDF.enabled | Boolean | Activate or deactivate the fixup | false | true |
Layers
RENAME LAYER
Layers (optional content group) can be renamed in the PDF file. The list of the layers to be renamed is controlled by the variable layerRegEx, which is a regular expression (to give the most flexible options). The layer(s) will be renamed to the variable newName.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| renameLayer.enabled | Boolean | Activate or deactivate the fixup | false | false |
| renameLayer.layerRegEx | String | Regular expression to match layers to be renamed | false | .* |
| renameLayer.newName | String | Defines the new name of the layer(s) | false | "" |
REMOVE LAYER
Layers (optional content group) can be removed from the PDF file. The list of the layers to be removed is controlled by the variable layerRegEx, which is a regular expression (to give the most flexible options). The layer can be removed with and without the actual content on the layer, controlled by the variable toggleRemoveContentFromLayer. The default value is 1, which means that the content will also be removed from the file.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| removeLayer.enabled | Boolean | Activate or deactivate the fixup | false | false |
| removeLayer.layerRegEx | String | Regular expression to match layers to be removed | false | .* |
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| removeContentFromLayer.enabled | Boolean | Whether the content has to be removed as well | false | true |
FLATTEN LAYERS
Layers (optional content group) can be flattened. Please note that that this action will also remove any content on hidden layer(s).
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| flattenLayers.enabled | Boolean | Activate or deactivate the fixup | false | false |
Pages
SPLIT IN HALF
The PDF pages can be split in half. This action recognises if the page is a single or a double page automatically.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| splitInHalf.enabled | Boolean | Activate or deactivate the fixup | false | false |
READER SPREADS
This action arranges the pages in two-page spread without reordering the pages. A cover page (single page) can be used during the process (to keep book spreads), this is controlled by the variable coverPage. The default value is true, which means that the cover page will be used.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| readerSpreads.enabled | Boolean | Activate or deactivate the fixup | false | false |
| readerSpreads.coverPage | Boolean | Uses a cover page (single page) during the process | false | true |
Dimensions
RESIZE PAGE
There are two resize options, you can resize homothetically or by stretching the artwork to fit the targeted dimensions. this is controlled by the variable resizeMethod. Possible values are homothetical and stretch to fit.
When the resize is homothetic, the artwork is resized to fit the complete artwork into the new dimension.
White space may be visible left and right or top and bottom, if the new size is not nomothetical to the
original size. The process plan can handle all combinations, portrait on portrait, landscape on landscape,
portrait on landscape and landscape on portrait.
The requested size of the artwork’s trimbox is defined by the variables targetPageWidth and
targetPageHeight. The default values are 210mm wide by 297mm tall.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| resizePage.enabled | Boolean | Activate or deactivate the fixup | false | false |
| resizePage.width | Number | Target width of the trimbox of the artwork | false | 210 |
| resizePage.height | Number | Target height of the trimbox of the artwork | false | 297 |
| resizePage.method | String | Method for resize: "homothetical" or "stretch to fit" | false | homothetical |
GENERATE BLEED
The requested size of the bleed is defined by side, with the corresponding variables bleedSizeLeft, bleedSizeRight, bleedSizeTop and bleedSizeBottom. The default value is 3mm for all sides. If existing, the bleedbox will be resized to the value of the trimbox + bleedSize(side), cropbox and mediabox will be adjusted accordingly.
CHECK BLEED
First of all, the PDF file is checked to find out if bleed is necessary (white background on the edges does not require any bleed), then it will be checked to see if enough bleed is present (bleed size should be equal or bigger than bleedSize(side)). If this is the case, the existing bleed will be kept. The minimum required bleed (size that is acceptable, even if less than the requested size) is controlled by the variable bleedMinCheck. The default value is 80 (80%). Note 1: for example for a 3mm requested bleed, the acceptable bleed size would be 2.4mm if the value is 80%. Note 2: to force check to the required bleed size (no tolerance), use the value 100 (100%). If there is no bleed or there is not enough bleed, the engine will generate the missing bleed. If there is enough bleed, no bleed will be generated. If the existing bleed is bigger than the requested bleed, the over-bleed content will be removed and the bleedbox will be set to the requested size.
GENERATE BLEED
The necessary bleed will be generated at bleedSize(side) bleed size (for each side). The method for bleed generation can be “mirror”, “pixel repetition” or “stretch”. The algorithm is controlled by the variable bleedMethod. The default value is mirror. To improve the visual result of the bleed, the generated bleed will start where existing content stops. It can be at trimbox (if there is no bleed at all), or away from trimbox (if there was some bleed, but not enough). To ease selection of generated bleed (e.g. for removal if not good enough), the bleed can be generated on a specific layer (controlled by the variable onLayer), named after the variable bleedLayerName. The default value is generatedBleed.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| generateBleed.enabled | Boolean | Activate or deactivate the fixup | false | true |
| generateBleed.sizeLeft | Number | Size of the bleed on the left side of the page | false | 3.0 |
| generateBleed.sizeRight | Number | Size of the bleed on the right side of the page | false | 3.0 |
| generateBleed.sizeTop | Number | Size of the bleed on the top side of the page | false | 3.0 |
| generateBleed.sizeBottom | Number | Size of the bleed on the bottom side of the page | false | 3.0 |
| generateBleed.minCheck | Number | Acceptable bleed size from required bleed size (%) | false | 80.0 |
| generateBleed.method | String | Method for bleed generation: "mirror", "pixel repetition", or "stretch" | false | mirror |
| generateBleed.generateOnLayer | Boolean | Activate bleed generation on a specific layer | false | true |
| generateBleed.bleedLayerName | String | Name of the bleed layer if generated on a specific layer | false | generatedBleed |
Colours
EMBED OUTPUT INTENT
Output intent can be embedded in the file. The output intent is selected from a fixed list (the list can be updated but this requires a modification of the process plan) and defined by the variable outputIntent. The default value is ISO Coated v2 300% (ECI).
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| embedOutputIntent.enabled | Boolean | Activate or deactivate the fixup | false | true |
| embedOutputIntent.outputIntent | String | Defines the output intent to be embedded. The value can be 'ISO Coated v2 300% (ECI)', 'ISO Coated v2 (ECI)', 'PSO Uncoated ISO12647 (ECI)', 'PSO Coated v3 (ECI)', or 'PSO Uncoated v3 (ECI)' | false | ISO Coated v2 300% (ECI) |
CONVERT REGISTRATION TO BLACK INSIDE TRIMBOX
If registration colour has been used inside the trimbox by mistake, it can be converted to black, on overprint.Black text can be setup on overprint to avoid mis-registration when placed on a coloured background. This is particularly useful for small texts. The minimum text size under which the overprint must be setup is controlled by the variable overprintBlackTextMinimumSize. The default value is 9.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| convertRegistrationToBlack.enabled | String | Activate or deactivate the fixup | false | ISO Coated v2 300% (ECI) |
Overprinting
KNOCKOUT WHITE TEXT AND/OR VECTOR OBJECTS
White objects (vector objects and/or text) can be improperly setup to overprint, which means that the object will not be visible anymore. This fixup corrects the overprint flag by putting it on knockout. The fixup can be applied to text, vector objects, or both, according to the variable applyKnockoutWhite. The default value is Vector-Text.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| knockoutWhite.enabled | Boolean | Activate or deactivate the fixup | false | true |
| knockoutWhite.applyTo | String | Defines on which objects the fixup will perform. The value can be “Text”, “Vector” or “Vector-Text” | false | Vector-Text |
OVERPRINT BLACK TEXT
Black text can be setup on overprint to avoid mis-registration when placed on a coloured background. This is particularly useful for small texts. The minimum text size under which the overprint must be setup is controlled by the variable overprintBlackTextMinimumSize. The default value is 9.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| overprintBlackText.enabled | Boolean | Activate or deactivate the fixup | false | true |
| overprintBlackText.minTextSize | Number | The text size under which the overprint will be set up | false | 9.0 |
Fonts
CONVERT TEXT TO OUTLINES
This fixup will outline fonts. Please note that some fonts may still remain as live text, if the font’s license does not allow to outline.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| convertTextToOutlines.enabled | Boolean | Activate or deactivate the fixup | false | false |
Finishing
CREATE CUT PATH
A cut path is generated based on the width and height of the trim box.
The name of the cut path separation is set by cutPathSeparationName, which depends on the material type (Thru-cut or Route), the default value is Thru-cut.
The cut path’s alternate color is controlled by the variables alternateC, alternateM, alternateY, and alternateK. By default, all values are set to 0, making the cut path invisible.
The cut path is placed in an optional content group (layer) named after the variable cutPathLayerName, the default value is cutPath.
| Field | Type | Description | Required | Default |
|---|---|---|---|---|
| cutPath.enabled | Boolean | Activate or deactivate the fixup | false | false |
| cutPath.separationName | String | Name of the separation to be used for the cut path. It can be Thru-cut or Route | false | Thru-cut |
| cutPath.alternateC | String | Alternate Cyan channel value for the cut path | false | 0 |
| cutPath.alternateM | String | Alternate Magenta channel value for the cut path | false | 0 |
| cutPath.alternateY | String | Alternate Yellow channel value for the cut path | false | 0 |
| cutPath.alternateK | String | Alternate Black channel value for the cut path | false | 0 |
| cutPath.layerName | String | Name of the layer on which the cut path will be placed | false | cutPath |
Results
GET https://open-api.artworker.io/v1/taskapi/workflows/100/task/fixup/files/1?api_key=[API_KEY]
Sample Response
{
"output_file_url": "https://storage.cloud.google.com/preflight-profile-output-bucket/123/d39b0efe-9982-4161-bbd0-1074a8169d8f.pdf",
"output_filename": "some-output.pdf",
"report": {
"bleedboxFixGeometry": {
"details": {
"message": "",
"numFail": 0,
"numPass": 6
},
"retCode": 5
}
}
}
The results will be available at /v1/taskapi/workflows/:workflowId/task/:taskName/files/:fileNumber
Task Error Codes
This section covers error codes found in the task.error object that are specific to this task.
| Error Code | Description |
|---|---|
| 503, 508 | At least one error executing fixups. |
| 100 - 104 | An error occurred starting fixups. |
| 105, 106, 107 | The provided file is encrypted or damaged and in need of repair. |
| 130 - 159 | Fixups were terminated prematurely. Please contact support |
Response
| Field | Type | Description |
|---|---|---|
| output_file_url | String | URL of created file |
| output_filename | String | If provided, custom output filename |
| report | object | Report of issues during pdf edit, if available |
Details
| Field | Type | Description |
|---|---|---|
| message | String | error or warning message if available |
| numFail | Number | Number of fails |
| numPass | Number | Number of passes |
RetCode
| Code Number | Description |
|---|---|
| 0 | No hit, no Fixups executed |
| 1 | At least one hit with severity ‘info’, no Fixups executed |
| 2 | At least one hit with severity ‘warning’, no Fixups executed |
| 3 | At least one hit with severity ‘error’, no Fixups executed |
| 5 | No hit, Fixups have been executed |
| 6 | At least one hit with severity ‘info’, Fixups have been executed |
| 7 | At least one hit with severity ‘warning’, Fixups have been executed |
| 8 | At least one hit with severity "error", Fixups have been executed; Fixups failed |
Page Selector
A split scheme expression can be a number with an asterisk * or a more complex string.
Number with Asterisk *
- Groups pages into chunks of the defined size.
- Example:
"3*"will group the PDF into groups of 3 pages.
Simple Expressions
| Type | Syntax | Example | Description |
|---|---|---|---|
| Simple expression | number[-number] |
1-5 |
Pages 1 to 5: [1,2,3,4,5] |
5-1 |
Pages 5 to 1 in reverse: [5,4,3,2,1] |
||
8 |
Only page 8 | ||
-1 |
Last page | ||
-3--1 |
Last 3 pages: [n, n-1, n-2] |
||
-1--3 |
Last 3 pages in reverse: [n-2, n-1, n] |
||
-1-3 |
Last n - 2 pages in reverse: [n, ..., 3] |
Simple Expression with Simple Range
| Type | Syntax | Example | Description |
|---|---|---|---|
| Simple expression with Simple Range | number[-number]_number[-number]["," joker$] |
1-2_-2--1 |
First 2 and last 2 pages: [1,2,n-1,n] |
1-2_-2--1,$ |
First 2, last 2, and remaining inner pages: [1,2,n-1,n,3,...,n-2] |
||
1_1_1_1 |
4 times page 1: [1,1,1,1] |
Multipage Expressions
| Type | Syntax | Example | Description |
|---|---|---|---|
| Even pages | even_pages |
even |
All even pages (same as *2(2)) |
| Odd pages | uneven_pages |
odd |
All odd pages (same as *2(1)) |
| Packages of pages | number*[(start_page)] |
5* |
Packages of 5 pages |
5*(2) |
Packages of 5 pages, starting with page 2 | ||
| Every nth page | *number[(start_page)] |
*5 |
Every 5th page |
*5(2) |
Every 5th page, starting with page 2 | ||
*5(-20) |
Every 5th page of the last 20 pages (total 4 pages) | ||
*number[(start_page,end_page)] |
*5(2,20) |
Every 5th page, starting from page 2 to page 20 |
Simple Expression List
| Type | Syntax | Example | Description |
|---|---|---|---|
| Simple expression list | simple_expression {"," simple_expression}[ "," joker$] |
1-5,8,-3--1 |
Pages 1-5, page 8, and the last 3 pages of the PDF |
1-5,8,-1--3 |
Pages 1-5, page 8, and the last 3 pages in reverse order | ||
1-5,8,$ |
Pages 1-5, page 8, and all remaining pages |
Joker Expression
| Type | Syntax | Example | Description |
|---|---|---|---|
| Joker | <expression>,$ |
1-5,8,-3--1,$ |
Pages 1-5, page 8, the last 3 pages, and the rest of the pages of the PDF, grouped separately. |
Summary
These expressions allow flexible page selection and grouping for PDF manipulation. The syntax supports:
1. Simple expressions (specific pages or ranges).
2. Complex combinations (e.g., ranges with joker $).
3. Patterns for regular intervals (e.g., every 5th page).