# Solo Works REST API

Base URL: https://soloworks.app/api/v1

## Authentication

All requests require an API key via the Authorization header:

```
Authorization: Bearer sk_live_YOUR_API_KEY
```

Get your API key at: https://soloworks.app/api-keys

## Quick Start

1. `GET /api/v1/workflows` — Discover available workflows
2. `GET /api/v1/workflows/:id` — Get required inputs for a workflow
3. `POST /api/v1/workflows/:id/execute` — Execute with your images and parameters
4. `GET /api/v1/executions/:id` — Poll until status is completed

---

## Discovery

### GET /api/v1/workflows

List all available AI image editing workflows. Returns workflow IDs, names, descriptions, and credit costs.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|----------|-------------|
| `tag` | string | query | No | Optional tag to filter workflows (e.g., 'fashion', 'product'). |

**Response example:**

```json
{
  "workflows": [
    {
      "id": "abc-123",
      "name": "AI Model Swap",
      "description": "Replace the model in a fashion photo",
      "tags": [
        "fashion",
        "model"
      ],
      "creditCost": {
        "min": 2,
        "max": 4
      },
      "previewImage": "https://example.com/preview.jpg"
    }
  ],
  "total": 1
}
```

**curl:**

```bash
curl https://soloworks.app/api/v1/workflows?tag=VALUE \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

---

### GET /api/v1/workflows/{id}

Get the detail and required input schema for a specific workflow, including image fields, text fields, and switch/selection fields.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|----------|-------------|
| `id` | string | path | Yes | The workflow ID to retrieve details for. |

**Response example:**

```json
{
  "id": "abc-123",
  "name": "AI Model Swap",
  "description": "Replace the model in a fashion photo",
  "creditCost": {
    "min": 2,
    "max": 4
  },
  "inputs": {
    "isBatchMode": false,
    "imageFields": [
      {
        "fieldId": "image",
        "title": "Product Photo",
        "required": true
      }
    ],
    "textFields": [
      {
        "fieldId": "prompt",
        "title": "Description",
        "defaultValue": "A professional model"
      },
      {
        "fieldId": "ethnicity",
        "title": "Ethnicity",
        "required": true,
        "presetOptions": [
          {
            "optionId": "opt_1",
            "label": "Random",
            "value": "random ethnicity"
          },
          {
            "optionId": "opt_2",
            "label": "White",
            "value": "white"
          },
          {
            "optionId": "opt_3",
            "label": "Asian",
            "value": "asian"
          }
        ]
      }
    ],
    "switchFields": [
      {
        "fieldId": "style",
        "title": "Style",
        "options": [
          {
            "optionId": "casual",
            "label": "Casual"
          },
          {
            "optionId": "formal",
            "label": "Formal"
          }
        ]
      }
    ]
  }
}
```

**curl:**

```bash
curl https://soloworks.app/api/v1/workflows/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

---

## Execution

### POST /api/v1/workflows/{id}/execute

Execute an AI image editing workflow asynchronously. Returns an execution ID to poll for results.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|----------|-------------|
| `id` | string | path | Yes | The workflow ID to execute (path parameter). |
| `images` | Record<string, string> | body | Yes | Image inputs as {fieldId: url_or_base64}. URLs are automatically downloaded by the server. |
| `texts` | Record<string, string> | body | No | Text inputs as key-value pairs: {fieldId: value}. |
| `switchSelections` | Record<string, string[]> | body | No | Switch/selection inputs as {switchFieldId: [optionId]}. |
| `globalOverrides` | { aspectRatio?: string, imageSize?: string } | body | No | Optional output overrides. aspectRatio: "1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9", "21:9". imageSize: "1K" or "2K". |

**Request body example:**

```json
{
  "images": {
    "image": "https://example.com/photo.jpg"
  },
  "texts": {
    "prompt": "A professional model wearing casual clothes"
  },
  "switchSelections": {
    "style": [
      "casual"
    ]
  },
  "globalOverrides": {
    "aspectRatio": "3:4",
    "imageSize": "1K"
  }
}
```

**Response example:**

```json
{
  "executionId": "exec-456",
  "status": "running",
  "estimatedCredits": 3
}
```

**curl:**

```bash
curl -X POST https://soloworks.app/api/v1/workflows/{id}/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -d '{
  "images": {
    "image": "https://example.com/photo.jpg"
  },
  "texts": {
    "prompt": "A professional model wearing casual clothes"
  },
  "switchSelections": {
    "style": [
      "casual"
    ]
  },
  "globalOverrides": {
    "aspectRatio": "3:4",
    "imageSize": "1K"
  }
}'
```

---

### GET /api/v1/executions/{id}

Check the status of a workflow execution. Returns progress percentage and result URLs when complete.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|----------|-------------|
| `id` | string | path | Yes | The execution ID returned by the execute endpoint. |

**Response example:**

```json
{
  "executionId": "exec-456",
  "status": "completed",
  "progress": "100%",
  "result": {
    "jpgUrl": "https://storage.example.com/result.jpg",
    "creditsConsumed": 3
  }
}
```

**curl:**

```bash
curl https://soloworks.app/api/v1/executions/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

---

## Account

### GET /api/v1/balance

Get your current API credits balance and web credits breakdown.

**Response example:**

```json
{
  "apiBalance": 50,
  "freeCredits": 10,
  "purchasedCredits": 50,
  "refundCredits": 0,
  "totalAvailable": 60
}
```

**curl:**

```bash
curl https://soloworks.app/api/v1/balance \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

---

## Error Responses

All errors return JSON with `error` (code) and `message` (human-readable):

| Status | Error Code | Description |
|--------|-----------|-------------|
| 401 | `missing_auth` | Missing Authorization header |
| 401 | `invalid_api_key` | Invalid or expired API key |
| 402 | `insufficient_credits` | Not enough API credits |
| 404 | `not_found` | Workflow or execution not found |
| 400 | `missing_image` / `invalid_image` | Image parameter issue |
| 500 | `internal_error` | Server error |