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.

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.

Trigger settings menu

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.

API access settings

• 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

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.

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

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.

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.

Response (success)

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

Use the returned executionId to check execution status.

Request example (curl)

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

GET /api/executions/{executionId}

Request headers

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

Request example (curl)

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

Response example (success)

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