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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.genesis.autify.com/integrations/api-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.