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.

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 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