# Workflows API

> Event-driven automation graphs: a trigger (message, keyword, comment, referral, reaction, contact change, API call, schedule) and nodes (send message, reply / private reply, wait, condition, HTTP request, AI reply with Claude, tags, fields, sequences, assignment). Every graph change records a version; runs are durable and have a timeline.

Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer <API key or OAuth token>`.

## List workflows

`GET /workflows`

Access: `read` · MCP tool: `list-workflows` · Zernio: `GET /v1/workflows`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, updated_at, name)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `profile_id` (string)
- `account_id` (string)
- `status` (string)
- `platform` (string)
- `trigger_type` (string)

```bash
curl "https://api.socialit.com/v1/workflows" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "workflow",
      "id": "string",
      "profile_id": "string",
      "account_id": "string",
      "account_name": "string",
      "platform": "string",
      "name": "string",
      "description": "string",
      "status": "draft",
      "trigger_type": "string",
      "entry_node_id": "string",
      "nodes": [
        {
          "id": "string",
          "type": "string",
          "label": "string",
          "position": {
            "x": null,
            "y": null
          },
          "config": {}
        }
      ],
      "edges": [
        {
          "id": "string",
          "source": "string",
          "target": "string",
          "source_handle": "string"
        }
      ],
      "node_count": 1,
      "version": 1,
      "stats": {
        "total_started": 1,
        "total_completed": 1,
        "total_exited": 1,
        "total_failed": 1,
        "running": 1
      },
      "activated_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a workflow

`POST /workflows`

Validates the graph structure (unique ids, known node types, edges between real nodes, valid handles). Created as draft.

Access: `write` · MCP tool: `create-workflow` · Zernio: `POST /v1/workflows`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `profile_id` (string)
- `account_id` (string | null)
- `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter)
- `name` (string; required; 1–200 characters)
- `description` (string | null; ≤ 2000 characters)
- `nodes` (array of object; ≤ 200 items)
  - `nodes[].id` (string; required; 1–64 characters)
  - `nodes[].type` (string; required; one of trigger, send_message, reply_to_comment, private_reply, wait_for_reply, condition, set_variable, delay, http_request, ai, assign_conversation, handoff, …)
  - `nodes[].label` (string | null; ≤ 80 characters)
  - `nodes[].position` (object | null)
    - `nodes[].position.x` (number)
    - `nodes[].position.y` (number)
  - `nodes[].config` (object)
- `edges` (array of object; ≤ 400 items)
  - `edges[].id` (string; required; 1–64 characters)
  - `edges[].source` (string; required; 1–64 characters)
  - `edges[].target` (string; required; 1–64 characters)
  - `edges[].source_handle` (string | null; ≤ 64 characters)
  - `edges[].sourceHandle` (string | null; ≤ 64 characters)
- `entry_node_id` (string | null; ≤ 64 characters)

```bash
curl -X POST "https://api.socialit.com/v1/workflows" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "string",
    "account_id": "string",
    "platform": "instagram",
    "name": "string",
    "description": "string"
  }'
```

Response 201:

```json
{
  "object": "workflow",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "trigger_type": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "node_count": 1,
  "version": 1,
  "stats": {
    "total_started": 1,
    "total_completed": 1,
    "total_exited": 1,
    "total_failed": 1,
    "running": 1
  },
  "activated_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## List workflow node types

`GET /workflows/node-types`

Catalog of node types with their output handles and config JSON schema (drives the builder).

Access: `read` · MCP tool: `list-workflow-node-types`

### Query parameters

- `page` (integer; ≥ 1)
- `limit` (integer; 1–100)

```bash
curl "https://api.socialit.com/v1/workflows/node-types" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "workflow_node_type",
      "type": "string",
      "group": "string",
      "label": "string",
      "description": "string",
      "handles": [
        "string"
      ],
      "config_schema": {},
      "platforms": [
        "string"
      ],
      "alias_of": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Get a workflow

`GET /workflows/{id}`

Access: `read` · MCP tool: `get-workflow` · Zernio: `GET /v1/workflows/{workflowId}`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

```bash
curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "workflow",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "trigger_type": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "node_count": 1,
  "version": 1,
  "stats": {
    "total_started": 1,
    "total_completed": 1,
    "total_exited": 1,
    "total_failed": 1,
    "running": 1
  },
  "activated_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Update a workflow

`PATCH /workflows/{id}`

The graph (nodes, edges, entry_node_id, replaced wholesale) is editable only while draft or paused (409 workflow_not_editable); name, description and account any time. Graph, name and description changes record a version.

Access: `write` · MCP tool: `update-workflow` · Zernio: `PATCH /v1/workflows/{workflowId}`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Body

- `name` (string; 1–200 characters)
- `description` (string | null; ≤ 2000 characters)
- `account_id` (string | null)
- `nodes` (array of object; ≤ 200 items)
  - `nodes[].id` (string; required; 1–64 characters)
  - `nodes[].type` (string; required; one of trigger, send_message, reply_to_comment, private_reply, wait_for_reply, condition, set_variable, delay, http_request, ai, assign_conversation, handoff, …)
  - `nodes[].label` (string | null; ≤ 80 characters)
  - `nodes[].position` (object | null)
    - `nodes[].position.x` (number)
    - `nodes[].position.y` (number)
  - `nodes[].config` (object)
- `edges` (array of object; ≤ 400 items)
  - `edges[].id` (string; required; 1–64 characters)
  - `edges[].source` (string; required; 1–64 characters)
  - `edges[].target` (string; required; 1–64 characters)
  - `edges[].source_handle` (string | null; ≤ 64 characters)
  - `edges[].sourceHandle` (string | null; ≤ 64 characters)
- `entry_node_id` (string | null; ≤ 64 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "account_id": "string",
    "nodes": [
      {
        "id": "string",
        "type": "trigger"
      }
    ],
    "edges": [
      {
        "id": "string",
        "source": "string",
        "target": "string"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "workflow",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "trigger_type": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "node_count": 1,
  "version": 1,
  "stats": {
    "total_started": 1,
    "total_completed": 1,
    "total_exited": 1,
    "total_failed": 1,
    "running": 1
  },
  "activated_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Delete a workflow

`DELETE /workflows/{id}`

Access: `write` · MCP tool: `delete-workflow` · Zernio: `DELETE /v1/workflows/{workflowId}`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

```bash
curl -X DELETE "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "workflow",
  "id": "string",
  "deleted": true
}
```

## Activate a workflow

`POST /workflows/{id}/activate`

Requires a complete graph: one trigger, every node reachable and valid, an account when the graph messages (422 workflow_invalid with errors).

Access: `write` · MCP tool: `activate-workflow` · Zernio: `POST /v1/workflows/{workflowId}/activate`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

```bash
curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/activate" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response 200:

```json
{
  "object": "workflow",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "trigger_type": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "node_count": 1,
  "version": 1,
  "stats": {
    "total_started": 1,
    "total_completed": 1,
    "total_exited": 1,
    "total_failed": 1,
    "running": 1
  },
  "activated_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Pause a workflow

`POST /workflows/{id}/pause`

Stops new runs; in-flight runs finish.

Access: `write` · MCP tool: `pause-workflow` · Zernio: `POST /v1/workflows/{workflowId}/pause`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

```bash
curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pause" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response 200:

```json
{
  "object": "workflow",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "trigger_type": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "node_count": 1,
  "version": 1,
  "stats": {
    "total_started": 1,
    "total_completed": 1,
    "total_exited": 1,
    "total_failed": 1,
    "running": 1
  },
  "activated_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Duplicate a workflow

`POST /workflows/{id}/duplicate`

Access: `write` · MCP tool: `duplicate-workflow` · Zernio: `POST /v1/workflows/{workflowId}/duplicate`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

```bash
curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/duplicate" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response 201:

```json
{
  "object": "workflow",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "trigger_type": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "node_count": 1,
  "version": 1,
  "stats": {
    "total_started": 1,
    "total_completed": 1,
    "total_exited": 1,
    "total_failed": 1,
    "running": 1
  },
  "activated_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## List workflow versions

`GET /workflows/{id}/versions`

Access: `read` · MCP tool: `list-workflow-versions` · Zernio: `GET /v1/workflows/{workflowId}/versions`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR

```bash
curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/versions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "workflow_version",
      "id": "string",
      "workflow_id": "string",
      "version": 1,
      "name": "string",
      "description": "string",
      "entry_node_id": "string",
      "nodes": [
        {
          "id": "string",
          "type": "string",
          "label": "string",
          "position": {
            "x": null,
            "y": null
          },
          "config": {}
        }
      ],
      "edges": [
        {
          "id": "string",
          "source": "string",
          "target": "string",
          "source_handle": "string"
        }
      ],
      "account_id": "string",
      "platform": "string",
      "created_by": {
        "type": "string",
        "id": "string",
        "name": "string"
      },
      "restored_from_version": 1,
      "created_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Get a workflow version

`GET /workflows/{id}/versions/{version}`

Access: `read` · MCP tool: `get-workflow-version` · Zernio: `GET /v1/workflows/{workflowId}/versions/{version}`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)
- `version` (integer; required; ≥ 1)

```bash
curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/versions/VERSION" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "workflow_version",
  "id": "string",
  "workflow_id": "string",
  "version": 1,
  "name": "string",
  "description": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "account_id": "string",
  "platform": "string",
  "created_by": {
    "type": "string",
    "id": "string",
    "name": "string"
  },
  "restored_from_version": 1,
  "created_at": "2026-10-13T09:00:00.000Z"
}
```

## Restore a workflow version

`POST /workflows/{id}/versions/{version}/restore`

Copies the version graph back as a new version (restored_from_version). Only while draft or paused.

Access: `write` · MCP tool: `restore-workflow-version` · Zernio: `POST /v1/workflows/{workflowId}/versions/{version}/restore`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)
- `version` (integer; required; ≥ 1)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

```bash
curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/versions/VERSION/restore" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response 200:

```json
{
  "object": "workflow",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "trigger_type": "string",
  "entry_node_id": "string",
  "nodes": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "position": {
        "x": 1.5,
        "y": 1.5
      },
      "config": {}
    }
  ],
  "edges": [
    {
      "id": "string",
      "source": "string",
      "target": "string",
      "source_handle": "string"
    }
  ],
  "node_count": 1,
  "version": 1,
  "stats": {
    "total_started": 1,
    "total_completed": 1,
    "total_exited": 1,
    "total_failed": 1,
    "running": 1
  },
  "activated_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## List workflow runs

`GET /workflows/{id}/executions`

Access: `read` · MCP tool: `list-workflow-executions` · Zernio: `GET /v1/workflows/{workflowId}/executions`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, updated_at)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `status` (string)
- `contact_id` (string)

```bash
curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "workflow_execution",
      "id": "string",
      "workflow_id": "string",
      "workflow_version": 1,
      "status": "running",
      "trigger": {
        "type": "string",
        "text": "string"
      },
      "contact_id": "string",
      "conversation_id": "string",
      "platform_identifier": "string",
      "current_node_id": "string",
      "waiting_for": {
        "kind": "string",
        "node_id": "string",
        "until": "string"
      },
      "variables": {},
      "step_count": 1,
      "last_error": "string",
      "resume_at": "2026-10-13T09:00:00.000Z",
      "started_at": "2026-10-13T09:00:00.000Z",
      "completed_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Start a workflow run manually

`POST /workflows/{id}/executions`

Test run for any status, on a contact_id, conversation_id or to (phone), with text seeding last_message.

Access: `write` · MCP tool: `start-workflow-execution` · Zernio: `POST /v1/workflows/{workflowId}/executions`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `contact_id` (string)
- `conversation_id` (string)
- `to` (string; ≤ 32 characters)
- `text` (string; ≤ 4096 characters)
- `variables` (object)

```bash
curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "string",
    "conversation_id": "string",
    "to": "+15551234567",
    "text": "string",
    "variables": {}
  }'
```

Response 201:

```json
{
  "object": "workflow_execution",
  "id": "string",
  "workflow_id": "string",
  "workflow_version": 1,
  "status": "running",
  "trigger": {
    "type": "string",
    "text": "string"
  },
  "contact_id": "string",
  "conversation_id": "string",
  "platform_identifier": "string",
  "current_node_id": "string",
  "waiting_for": {
    "kind": "string",
    "node_id": "string",
    "until": "string"
  },
  "variables": {},
  "step_count": 1,
  "last_error": "string",
  "resume_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Trigger an API workflow

`POST /workflows/{id}/trigger`

For active workflows with an api_call trigger: one of contact_id, conversation_id or to, plus variables.

Access: `write` · MCP tool: `trigger-workflow` · Zernio: `POST /v1/workflows/{workflowId}/trigger`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `contact_id` (string)
- `conversation_id` (string)
- `to` (string; ≤ 32 characters)
- `variables` (object)

```bash
curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/trigger" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "string",
    "conversation_id": "string",
    "to": "+15551234567",
    "variables": {}
  }'
```

Response 201:

```json
{
  "object": "workflow_execution",
  "id": "string",
  "workflow_id": "string",
  "workflow_version": 1,
  "status": "running",
  "trigger": {
    "type": "string",
    "text": "string"
  },
  "contact_id": "string",
  "conversation_id": "string",
  "platform_identifier": "string",
  "current_node_id": "string",
  "waiting_for": {
    "kind": "string",
    "node_id": "string",
    "until": "string"
  },
  "variables": {},
  "step_count": 1,
  "last_error": "string",
  "resume_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Get a workflow run

`GET /workflows/{id}/executions/{executionId}`

Access: `read` · MCP tool: `get-workflow-execution`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)
- `executionId` (string; required; 1–80 characters): workflowExecution id (wfx_…)

```bash
curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions/wfx_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "workflow_execution",
  "id": "string",
  "workflow_id": "string",
  "workflow_version": 1,
  "status": "running",
  "trigger": {
    "type": "string",
    "text": "string"
  },
  "contact_id": "string",
  "conversation_id": "string",
  "platform_identifier": "string",
  "current_node_id": "string",
  "waiting_for": {
    "kind": "string",
    "node_id": "string",
    "until": "string"
  },
  "variables": {},
  "step_count": 1,
  "last_error": "string",
  "resume_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Stop a workflow run

`POST /workflows/{id}/executions/{executionId}/cancel`

Access: `write` · MCP tool: `cancel-workflow-execution`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)
- `executionId` (string; required; 1–80 characters): workflowExecution id (wfx_…)

```bash
curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions/wfx_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/cancel" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "workflow_execution",
  "id": "string",
  "workflow_id": "string",
  "workflow_version": 1,
  "status": "running",
  "trigger": {
    "type": "string",
    "text": "string"
  },
  "contact_id": "string",
  "conversation_id": "string",
  "platform_identifier": "string",
  "current_node_id": "string",
  "waiting_for": {
    "kind": "string",
    "node_id": "string",
    "until": "string"
  },
  "variables": {},
  "step_count": 1,
  "last_error": "string",
  "resume_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Get a run timeline

`GET /workflows/{id}/executions/{executionId}/events`

Access: `read` · MCP tool: `list-workflow-execution-events` · Zernio: `GET /v1/workflows/{workflowId}/executions/{executionId}/events`

### Path parameters

- `id` (string; required; 1–80 characters): workflow id (wf_…)
- `executionId` (string; required; 1–80 characters): workflowExecution id (wfx_…)

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR

```bash
curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions/wfx_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/events" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "workflow_execution_event",
      "id": "string",
      "execution_id": "string",
      "action": "string",
      "status": "string",
      "node_id": "string",
      "node_type": "string",
      "source_handle": "string",
      "duration_ms": 1,
      "error_message": "string",
      "meta": {},
      "at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```


---

Source: https://socialit.com/docs/api-reference/workflows/
