API Overview

The AutoRetouch API allows you to programmatically process images through your workflows. This guide covers authentication, uploading images, executing workflows, and retrieving results.

API Facts

Property	Value
Base URL	https://api.autoretouch.com
Auth Server	https://auth.autoretouch.com
Client ID	V8EkfbxtBi93cAySTVWAecEum4d6pt4J
Authentication	Bearer token (JWT)
Format	RESTful, JSON requests/responses

Quick Start Flow

The typical API integration follows this pattern:

1. Authenticate - Get an access token using the OAuth device flow
2. Upload - Upload your image and receive a content hash
3. Execute - Create a workflow execution with the image hash
4. Wait - Poll for status or use webhooks to get notified
5. Download - Retrieve the processed result image

Requirements

Before you begin, you’ll need:

• An AutoRetouch user account. Book a demo if you need an account.
• Access to the organization you’d like to use via the API
• For testing, we recommend requesting a dedicated workflow with a single ‘export’ component to minimize wait time and costs

Note

Every execution is billable by default. If you’re a test customer, confirm with your AutoRetouch contact whether you’ll be billed during testing. If you encounter PAYMENT_REQUIRED statuses, reach out to lift the limitation.

Authentication Overview

The API uses OAuth 2.0 Device Authorization Grant flow. Here’s a quick summary:

1. Request a device code from the auth server
2. User confirms the device in their browser
3. Exchange the device code for access and refresh tokens
4. Use the access token as a Bearer token in API requests
5. Refresh the access token when it expires (24 hours)

See Authentication for detailed endpoint documentation.

Data Types

Workflow Execution Status

Status	Description
CREATED	Execution created, waiting to start
ACTIVE	Currently processing
COMPLETED	Successfully finished
IN_QA	Awaiting quality assurance review
PAYMENT_REQUIRED	Insufficient credit balance
FAILED	Processing failed

Content Hash

A Base64-encoded SHA256 hash of the image content. Used as a unique identifier for uploaded images.

IDs

All IDs (workflow, execution, organization) are UUIDs. Treat them as opaque strings - the format may change.

Webhooks

Instead of polling for execution status, you can provide webhook URLs when creating executions. The API will POST to your webhook when the execution reaches certain states (COMPLETED, IN_QA, etc.).

Webhook payload structure:

{
  "event": "WORKFLOW_EXECUTION_COMPLETED",
  "content": {
    "id": "4f49c2b1-b428-44d2-8035-6949982122ce",
    "status": "COMPLETED",
    "resultPath": "/image/{hash}/filename.png",
    // ... full execution details
  }
}

Note

Event names in webhooks don’t match status values exactly. Check for event == "WORKFLOW_EXECUTION_COMPLETED" to identify completed executions.

Batching

You can group executions into batches by setting shared labels:

{
  "labels": {
    "autoretouch_batch_id": "29532657-c82b-427a-8b6a-ded598d696a9",
    "autoretouch_batch_name": "Spring Collection",
    "autoretouch_batch_createdAt": "2024-02-08T09:09:01.960Z"
  }
}

Benefits of batching:

• Related images appear together in the AutoRetouch UI as an “order”
• Quality checks are performed at the batch level
• Easier tracking and organization

Performance Best Practices

• Upload first, then execute - Separate the upload and execution steps for better throughput
• Parallel uploads - Upload multiple images concurrently
• Use webhooks - Avoid polling; let the API notify you when executions complete
• Use async endpoints - Prefer non-blocking API calls for high-volume processing

API Reference

Section	Description
Authentication	OAuth device flow, token refresh, revocation
Images	Upload images, check existence
Workflows	List and get workflow details
Executions	Create, monitor, and download results
Organizations	List organizations, check balance
Batches	List and get batch details
Errors	Status codes and error handling