Executions

A workflow execution processes a single image through a workflow. Create executions, monitor their status, and download results.

Create Execution (with uploaded image)

Create a workflow execution using a previously uploaded image. This is the recommended approach for better performance. If your workflow takes more than one input image, see Create Execution (with multiple images).

POST https://api.autoretouch.com/v1/workflow/execution/create

Query Parameters

Parameter	Type	Required	Description
`workflow`	string	Yes	Workflow ID
`version`	string	No	Workflow version ID (uses latest if omitted)
`organization`	string	Recommended	Organization ID

Request Body

{
  "image": {
    "name": "product-photo.jpg",
    "contentHash": "{hash from upload}",
    "contentType": "image/jpeg"
  },
  "labels": {
    "autoretouch_batch_id": "uuid",
    "autoretouch_batch_name": "Spring Collection",
    "autoretouch_batch_createdAt": "2024-02-08T09:09:01.960Z"
  },
  "webhooks": [
    "https://your-server.com/webhook"
  ]
}

Field	Type	Required	Description
`image.name`	string	Yes	Original filename
`image.contentHash`	string	Yes	Hash from upload endpoint
`image.contentType`	string	Yes	MIME type (image/jpeg, image/png)
`labels`	object	No	Custom key-value pairs for batching
`webhooks`	array	No	URLs to notify on completion

curl -X POST "https://api.autoretouch.com/v1/workflow/execution/create?workflow={workflowId}&organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "name": "product.jpg",
      "contentHash": "d4d4a63a03c9543f4f21d474500a95d7bb5704c83c139ddc6e005eaba6d54b22",
      "contentType": "image/jpeg"
    },
    "webhooks": ["https://your-server.com/webhook"]
  }'

import requests

response = requests.post(
    "https://api.autoretouch.com/v1/workflow/execution/create",
    params={
        "workflow": workflow_id,
        "organization": organization_id
    },
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    json={
        "image": {
            "name": "product.jpg",
            "contentHash": content_hash,
            "contentType": "image/jpeg"
        },
        "webhooks": ["https://your-server.com/webhook"]
    }
)

execution_id = response.text
print(f"Execution ID: {execution_id}")

Success Response (201 Created)

Returns the execution ID as plain text:

c8031492-b74f-44d3-8a7c-08bad01579a5

Create Execution (with multiple images)

Some workflows need more than one input image to produce a result. For these, replace the single image object with an images object that holds every input, keyed by position.

POST https://api.autoretouch.com/v1/workflow/execution/create

The endpoint and query parameters are the same as Create Execution (with uploaded image). Upload each image first with the upload endpoint to get its content hash.

Request Body

{
  "images": {
    "default": {
      "name": "main-photo.jpg",
      "contentHash": "{hash from upload}",
      "contentType": "image/jpeg"
    },
    "1": {
      "name": "additional-photo-1.jpg",
      "contentHash": "{hash from upload}",
      "contentType": "image/jpeg"
    },
    "2": {
      "name": "additional-photo-2.jpg",
      "contentHash": "{hash from upload}",
      "contentType": "image/jpeg"
    }
  },
  "labels": {
    "autoretouch_batch_id": "uuid",
    "autoretouch_batch_name": "Spring Collection",
    "autoretouch_batch_createdAt": "2024-02-08T09:09:01.960Z"
  },
  "webhooks": [
    "https://your-server.com/webhook"
  ]
}

Field	Type	Required	Description
`images.default`	object	Yes	The main image. Must always use the `default` key
`images.1`, `images.2`, …	object	No	Additional images, keyed with incremental numbers starting at `1`
`images.{key}.name`	string	Yes	Original filename
`images.{key}.contentHash`	string	Yes	Hash from upload endpoint
`images.{key}.contentType`	string	Yes	MIME type (image/jpeg, image/png)
`labels`	object	No	Custom key-value pairs for batching
`webhooks`	array	No	URLs to notify on completion

Key rules:

The main image always goes under default. An images object without a default key is invalid.
Additional images use string keys "1", "2", "3", and so on, in order, without gaps.
Send either image or images in a request, not both.

Multiple Images and Batching

Multiple images work with batching, but the two do different things:

Multiple images are inputs processed together within a single execution. All the images in images produce one output.
Batching groups separate executions together, using the batch labels.

Whether an execution uses one image or several doesn’t change how you batch it. We recommend grouping executions into batches by logical group, such as SKU, reference, or upload day. To do that, give every execution in the group the same batch labels.

Request

curl
Python

curl -X POST "https://api.autoretouch.com/v1/workflow/execution/create?workflow={workflowId}&organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "images": {
      "default": {
        "name": "main-photo.jpg",
        "contentHash": "d4d4a63a03c9543f4f21d474500a95d7bb5704c83c139ddc6e005eaba6d54b22",
        "contentType": "image/jpeg"
      },
      "1": {
        "name": "additional-photo-1.jpg",
        "contentHash": "df3b47d7c2f2d5bf0333ee086e31ff041d4aa85830290e6605e92d79341f9a54",
        "contentType": "image/jpeg"
      }
    },
    "webhooks": ["https://your-server.com/webhook"]
  }'

import requests

response = requests.post(
    "https://api.autoretouch.com/v1/workflow/execution/create",
    params={
        "workflow": workflow_id,
        "organization": organization_id
    },
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    json={
        "images": {
            "default": {
                "name": "main-photo.jpg",
                "contentHash": main_hash,
                "contentType": "image/jpeg"
            },
            "1": {
                "name": "additional-photo-1.jpg",
                "contentHash": additional_hash,
                "contentType": "image/jpeg"
            }
        },
        "webhooks": ["https://your-server.com/webhook"]
    }
)

execution_id = response.text
print(f"Execution ID: {execution_id}")

Success Response (201 Created)

Returns the execution ID as plain text, the same as a single-image execution:

c8031492-b74f-44d3-8a7c-08bad01579a5

Create Execution (with file upload)

Create a workflow execution by uploading the image directly. Simpler but slower for high-volume processing.

POST https://api.autoretouch.com/v1/workflow/execution/create

Query Parameters

Parameter	Type	Required	Description
`workflow`	string	Yes	Workflow ID
`version`	string	No	Workflow version ID
`organization`	string	Recommended	Organization ID
`label[key]`	string	No	Custom labels (URL-encoded brackets)

Request Body

Multipart form data with:

Field	Type	Description
`file`	file	Image file to process

Request

curl
Python

curl -X POST "https://api.autoretouch.com/v1/workflow/execution/create?workflow={workflowId}&organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}" \
  -F "file=@product.jpg"

import requests

with open("product.jpg", "rb") as f:
    response = requests.post(
        "https://api.autoretouch.com/v1/workflow/execution/create",
        params={
            "workflow": workflow_id,
            "organization": organization_id
        },
        headers={"Authorization": f"Bearer {access_token}"},
        files={"file": f}
    )

execution_id = response.text

Response Codes

Status	Description
`201 Created`	Execution created successfully
`401 Unauthorized`	Invalid or missing access token
`404 Not Found`	Workflow not found
`422 Unprocessable Entity`	Image cannot be processed

List Executions

Get a list of workflow executions.

GET https://api.autoretouch.com/v2/workflow/execution/

Query Parameters

Parameter	Type	Default	Description
`organization`	string	-	Organization ID (recommended)
`workflowId`	string	-	Filter by workflow
`batchName`	string	-	Filter by batch name
`status`	string	-	Filter by status
`inputFileName`	string	-	Filter by exact input filename
`noBatch`	boolean	-	Filter to non-batch executions
`limit`	integer	50	Maximum results per page
`offset`	integer	0	Number of results to skip

Request

curl
Python

curl -X GET "https://api.autoretouch.com/v2/workflow/execution/?organization={organizationId}&workflowId={workflowId}&limit=50" \
  -H "Authorization: Bearer {accessToken}"

import requests

response = requests.get(
    "https://api.autoretouch.com/v2/workflow/execution/",
    params={
        "organization": organization_id,
        "workflowId": workflow_id,
        "limit": 50
    },
    headers={"Authorization": f"Bearer {access_token}"}
)
data = response.json()

for execution in data["entries"]:
    print(f"{execution['inputFileName']}: {execution['status']}")

Success Response (200)

{
  "entries": [
    {
      "id": "97830693-ec56-4773-8706-95ddf3444a40",
      "workflow": "a0f0b604-85c0-45fd-85cf-4428bb3941ba",
      "workflowVersion": "cd1be60e-6574-44aa-b1cf-f49f9028d56d",
      "organizationId": "69f7d0ac-bd88-494d-a38a-f825da7e0c88",
      "status": "COMPLETED",
      "userId": "google-oauth2|123456789",
      "createdAt": "2020-08-04T16:21:56.305Z",
      "startedAt": "2020-08-04T14:21:56.504Z",
      "finishedAt": "2020-08-04T14:21:56.933Z",
      "inputFileName": "product.jpg",
      "inputContentHash": "14a47ef8f2a302cf10ebf10e9ac2e368a32ba4c35805aff2f25710e719c38774",
      "resultContentHash": "09ad3a37cdd83475c88f99b65ee64167933c93573d7df0326cca72ab4d155a70",
      "resultFileName": "product.png",
      "resultPath": "/image/09ad3a37cdd83475c88f99b65ee64167933c93573d7df0326cca72ab4d155a70/product.png",
      "labels": {
        "autoretouch_batch_name": "Spring Collection"
      },
      "chargedCredits": 10
    }
  ],
  "total": 1
}

Get Execution Details

Get details of a specific execution.

GET https://api.autoretouch.com/v1/workflow/execution/{executionId}

Path Parameters

Parameter	Type	Description
`executionId`	string	Execution ID

Request

curl
Python

curl -X GET "https://api.autoretouch.com/v1/workflow/execution/{executionId}?organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}"

import requests

response = requests.get(
    f"https://api.autoretouch.com/v1/workflow/execution/{execution_id}",
    params={"organization": organization_id},
    headers={"Authorization": f"Bearer {access_token}"}
)
execution = response.json()

if execution["status"] == "COMPLETED":
    result_path = execution["resultPath"]
    print(f"Result available at: {result_path}")

Success Response (200)

{
  "id": "97830693-ec56-4773-8706-95ddf3444a40",
  "workflow": "a0f0b604-85c0-45fd-85cf-4428bb3941ba",
  "workflowVersion": "cd1be60e-6574-44aa-b1cf-f49f9028d56d",
  "organizationId": "69f7d0ac-bd88-494d-a38a-f825da7e0c88",
  "status": "COMPLETED",
  "userId": "google-oauth2|123456789",
  "createdAt": "2020-08-04T16:21:56.305Z",
  "startedAt": "2020-08-04T14:21:56.504Z",
  "finishedAt": "2020-08-04T14:21:56.933Z",
  "inputFileName": "product.jpg",
  "inputContentHash": "14a47ef8f2a302cf10ebf10e9ac2e368a32ba4c35805aff2f25710e719c38774",
  "resultContentHash": "09ad3a37cdd83475c88f99b65ee64167933c93573d7df0326cca72ab4d155a70",
  "resultFileName": "product.png",
  "resultPath": "/image/09ad3a37cdd83475c88f99b65ee64167933c93573d7df0326cca72ab4d155a70/product.png",
  "labels": {},
  "chargedCredits": 10
}

Get Execution Status (Streaming)

Get the status of an execution with server-sent events. The request blocks until the execution reaches a final state.

GET https://api.autoretouch.com/v1/workflow/execution/{executionId}/status

Request

curl
Python

curl -X GET "https://api.autoretouch.com/v1/workflow/execution/{executionId}/status?organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}"

import requests

# This request blocks until completion
response = requests.get(
    f"https://api.autoretouch.com/v1/workflow/execution/{execution_id}/status",
    params={"organization": organization_id},
    headers={"Authorization": f"Bearer {access_token}"},
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode())

Response (Server-Sent Events)

id:COMPLETED
event:COMPLETED
data:COMPLETED

Download Result (Blocking)

Wait for execution to complete and download the result image in one request.

GET https://api.autoretouch.com/v1/workflow/execution/{executionId}/result/default

Request

curl
Python

curl -X GET "https://api.autoretouch.com/v1/workflow/execution/{executionId}/result/default?organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}" \
  --output result.png

import requests

# This request blocks until the result is ready
response = requests.get(
    f"https://api.autoretouch.com/v1/workflow/execution/{execution_id}/result/default",
    params={"organization": organization_id},
    headers={"Authorization": f"Bearer {access_token}"}
)

with open("result.png", "wb") as f:
    f.write(response.content)

Response

Returns the binary image file on success.

Status	Description
`200 OK`	Image file returned
`404 Not Found`	Execution not found

Download Result (by path)

Download a result image using its result path.

GET https://api.autoretouch.com{resultPath}

Request

curl
Python

curl -X GET "https://api.autoretouch.com/image/{contentHash}/filename.png?organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}" \
  --output result.png

import requests

# Use the resultPath from execution details
response = requests.get(
    f"https://api.autoretouch.com{result_path}",
    params={"organization": organization_id},
    headers={"Authorization": f"Bearer {access_token}"}
)

with open("result.png", "wb") as f:
    f.write(response.content)

Response Codes

Status	Description
`200 OK`	Image file returned
`403 Forbidden`	Not authorized to access this image
`404 Not Found`	Image not found

Retry Execution

Retry a failed or payment-required execution.

POST https://api.autoretouch.com/v1/workflow/execution/{executionId}/retry

Request

curl
Python

curl -X POST "https://api.autoretouch.com/v1/workflow/execution/{executionId}/retry?organization={organizationId}" \
  -H "Authorization: Bearer {accessToken}"

import requests

response = requests.post(
    f"https://api.autoretouch.com/v1/workflow/execution/{execution_id}/retry",
    params={"organization": organization_id},
    headers={"Authorization": f"Bearer {access_token}"}
)

Use Cases

FAILED executions: Retry at no additional cost
PAYMENT_REQUIRED executions: Retry after adding credits (will be charged)

Response Codes

Status	Description
`200 OK`	Retry initiated
`404 Not Found`	Execution not found or already completed