> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/integrations/api-guide.md).

# API guide

This article explains the available API types in Autify Genesis, how to use them, and their limitations.

## API key management

For creating, checking, and deleting API keys, see [API key management](/settings/organization-settings/api-key-management.md).

## Triggering a workflow via API

To trigger a workflow from an external application or program, enable **API access**.

Use the following steps to enable the setting and check the endpoint.

### 1. Opening the workflow editor

Open the editor for the workflow that you want to trigger via API.

### 2. Opening the trigger settings menu

At the top of the screen, click **More actions**, then click **Triggers** in the menu.

<figure><img src="/files/JtGgmfidE9E8wcHtZijW" alt="Screenshot of the trigger settings menu"><figcaption><p>Trigger settings menu</p></figcaption></figure>

### 3. Enabling API access

By default, API access is set to OFF.

1. Turn the **API access** switch to ON.
2. Under **Concurrency**, choose how Genesis should handle a new API request while an earlier API-triggered run of the same workflow is still pending or running.

| Option                     | Description                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| Run in parallel            | Start the new run and keep the earlier run going                                                |
| Cancel previous executions | Cancel older pending or running API-triggered runs of the same workflow, then start the new run |

### 4. Checking the API endpoint

When API access is ON, the dedicated **API endpoint** is shown.

<figure><img src="/files/nJMDCe1RZ7Lj4TzMBIo1" alt="Screenshot of the API access settings"><figcaption><p>API access settings</p></figcaption></figure>

* Endpoint format: `https://genesis.autify.com/api/workflows/{templateId}/trigger`

## REST API

Using an API key, you can trigger Genesis workflows from external systems and check their execution status.

### Triggering a workflow

**Endpoint**

```http
POST /api/workflows/{templateId}/trigger
```

**Request headers**

| Header         | Value              | Description |
| -------------- | ------------------ | ----------- |
| `x-api-key`    | Issued API key     | Required    |
| `Content-Type` | `application/json` | Recommended |

**Request body**

Specify the context variables defined in the workflow as key-value pairs in JSON.

```json
{
  "variable1": "value1",
  "variable2": "value2"
}
```

{% hint style="info" %}
All payload values must be **strings**. Numbers, arrays, and objects are not supported. Including a key that is not defined in the workflow results in an error.
{% endhint %}

{% hint style="info" %}
If **Cancel previous executions** is selected in the workflow trigger settings, a new API request cancels earlier pending or running API-triggered executions of the same workflow before the new one starts.
{% endhint %}

**Response (success)**

```json
{
  "success": true,
  "executionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

Use the returned `executionId` to check execution status.

**Request example (curl)**

```bash
curl -X POST https://genesis.autify.com/api/workflows/{templateId}/trigger \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com"}'
```

### Getting execution status

**Endpoint**

```http
GET /api/executions/{executionId}
```

**Request headers**

| Header      | Value          | Description |
| ----------- | -------------- | ----------- |
| `x-api-key` | Issued API key | Required    |

**Request example (curl)**

```bash
curl -X GET https://genesis.autify.com/api/executions/{executionId} \
  -H "x-api-key: your-api-key"
```

**Response example (success)**

```json
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "running",
  "workflowName": "Workflow name",
  "blockCount": 5,
  "completedBlocks": 2,
  "createdAt": "2026-03-16T00:00:00.000Z",
  "updatedAt": "2026-03-16T00:00:05.000Z",
  "startedAt": "2026-03-16T00:00:01.000Z",
  "finishedAt": null,
  "cancelRequestedAt": null,
  "cancelReason": null,
  "error": null,
  "triggerType": "api",
  "triggerPayload": {
    "exampleField": "exampleValue"
  },
  "triggerMetadata": {
    "ip": "xxx.xxx.xxx.xxx",
    "userAgent": "curl/8.0.0",
    "apiKeyId": "ak_xxxxxxxxxxxx"
  },
  "state": {
    "workflowId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "executionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "running",
    "blocks": {
      "block-1": {
        "status": "completed",
        "startTime": "2026-03-16T00:00:01.000Z",
        "endTime": "2026-03-16T00:00:02.000Z",
        "inputs": {},
        "output": "..."
      }
    },
    "createdAt": "2026-03-16T00:00:00.000Z",
    "updatedAt": "2026-03-16T00:00:05.000Z"
  }
}
```

**Execution status values**

| Status           | Description            |
| ---------------- | ---------------------- |
| `pending`        | Waiting to run         |
| `running`        | Running                |
| `completed`      | Completed              |
| `failed`         | Failed                 |
| `cancelled`      | Cancelled              |
| `skipped`        | Skipped by a condition |
| `review_pending` | Waiting for review     |

## Troubleshooting

### Authentication errors

| Situation                                                 | Cause                                                                 | Resolution                                             |
| --------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------ |
| `Missing API key` (401)                                   | The `x-api-key` header is missing                                     | Add the `x-api-key` header                             |
| `Invalid API key` (401)                                   | The API key is invalid or does not exist                              | Verify that you are using a valid API key              |
| `API key is not associated with an organization` (403)    | The API key is not linked to an organization                          | Recreate a valid API key                               |
| `Unauthorized` (403)                                      | The user for the API key is not a member of the target organization   | Use an API key issued by a member of that organization |
| `API key does not have access to this organization` (403) | The API key's organization does not match the workflow's organization | Use an API key issued in the same organization         |

### Payload errors

| Situation                                                   | Cause                                                          | Resolution                                                |
| ----------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------- |
| `Invalid JSON payload` (400)                                | The request body is not valid JSON                             | Check the JSON syntax                                     |
| `Payload too large` (413)                                   | The payload exceeds 10 MB                                      | Keep the payload size under 10 MB                         |
| `Invalid payload: expected object with string values` (500) | A payload value is not a string (number, array, etc.)          | Use string values for all fields                          |
| `Unexpected fields in payload` (500)                        | The payload contains a key that is not defined in the workflow | Update the keys to match the workflow's context variables |

### Resource errors

| Situation                                                     | Cause                                                          | Resolution                                                            |
| ------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| `Workflow template not found or API access not enabled` (404) | The template ID does not exist, or the API trigger is disabled | Verify the template ID, or enable API access in the workflow settings |
| `Invalid template ID` (400)                                   | The template ID is not in UUID format                          | Use a valid template ID                                               |
| `Usage limit reached` (403)                                   | The organization has reached its credit limit                  | Ask an administrator to add credits                                   |
| `Workflow template must belong to a project` (400)            | The template is not linked to a project                        | Link the template to an existing project                              |
| `Project not found` (404)                                     | The project linked to the template does not exist              | Check the project settings                                            |
| `Execution not found` (404)                                   | No execution exists for the specified `executionId`            | Verify that the `executionId` is valid                                |