Programmatic Workflows - Sixtyfour AI Documentation

Every workflow is a JSON definition you can keep in version control and deploy with the Workflows API, without opening the Workflow Editor. To build workflows in the UI, see Building Workflows. To run a workflow on a list of records, see Batch Processing.

The workflow definition

A workflow definition is a directed graph of blocks and edges. This is the body for a new workflow. Existing workflow updates also require the revision saved with the document being edited, as shown below.

{
  "workflow_name": "Enrich inbound leads",
  "workflow_description": "Incoming webhook → enrich people → outgoing webhook",
  "workflow_definition": {
    "blocks": [
      {
        "block_id": "6f1c2a4e-1b7d-4c55-9a43-0d1e5f6a7b01",
        "sequence_number": 1,
        "block_type": "io",
        "block_name": "webhook",
        "specs": {
          "input_schema": { "email": { "type": "string" }, "company": { "type": "string" } },
          "dataframe_type": "LEAD"
        }
      },
      {
        "block_id": "6f1c2a4e-1b7d-4c55-9a43-0d1e5f6a7b02",
        "sequence_number": 2,
        "block_type": "enrichment",
        "block_name": "lead_enrichment",
        "specs": {
          "return_fields": { "title": "string", "linkedin_url": "string" }
        }
      },
      {
        "block_id": "6f1c2a4e-1b7d-4c55-9a43-0d1e5f6a7b03",
        "sequence_number": 3,
        "block_type": "output",
        "block_name": "outgoing_webhook",
        "specs": {
          "url": "https://example.com/hooks/sixtyfour",
          "timeout_seconds": 10
        }
      }
    ],
    "edges": [
      { "from_block_id": "6f1c2a4e-1b7d-4c55-9a43-0d1e5f6a7b01", "to_block_id": "6f1c2a4e-1b7d-4c55-9a43-0d1e5f6a7b02" },
      { "from_block_id": "6f1c2a4e-1b7d-4c55-9a43-0d1e5f6a7b02", "to_block_id": "6f1c2a4e-1b7d-4c55-9a43-0d1e5f6a7b03" }
    ]
  }
}

Field	Type	Description
`workflow_name`	string	Name shown in the editor and in `GET /workflows`.
`workflow_description`	string	Free-form description.
`workflow_definition.blocks`	array	The processing steps. Execution follows `edges`, not array order.
`workflow_definition.edges`	array	Directed connections from `from_block_id` to `to_block_id`.
`id`	string	Optional UUID to use as the Workflow ID. `create_workflow` returns `409` if it is taken.

Each block:

Field	Type	Description
`block_id`	string	Optional UUID referenced by `edges`.
`sequence_number`	integer	Display order in the editor.
`block_type`	string	Block category, such as `io`, `enrichment`, or `output`.
`block_name`	string	The block to run, such as `lead_enrichment`. See the Workflow Blocks Reference.
`specs`	object	Block configuration. The schema depends on `block_name`.

block_name selects what the block does. Changing it while hand-editing JSON changes or breaks the workflow.

Get the JSON for an existing workflow

Build the workflow in the editor once, then export it:

In the editor, open the More options menu (⋮) next to Run and select View Workflow Definition. The dialog shows the Workflow ID and the JSON definition.
With the API, GET /workflows/{workflow_id} returns the graph under workflow_definition and its authoring revision under edit_revision.

For an update, export the graph and revision from the same response. Run this in a fresh directory; keep workflow-base.json unchanged and edit the content fields in workflow-update.json.

set -euo pipefail
curl --fail --silent --show-error "https://api.sixtyfour.ai/workflows/WORKFLOW_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  | jq '{workflow_name: .name, workflow_description: .description, workflow_definition: .workflow_definition, expected_revision: .edit_revision}' \
  > workflow-base.json
cp workflow-base.json workflow-update.json

Keep expected_revision unchanged while editing. It belongs to this workflow’s exported base, even if another editor saves a newer version before CI runs.

Create a workflow from JSON

Save the new definition above as workflow.json, without expected_revision, and POST it to create_workflow. Creation needs no existing workflow. The response is the saved workflow; keep its id to run it.

curl --fail -X POST "https://api.sixtyfour.ai/workflows/create_workflow" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @workflow.json

import json, requests

with open("workflow.json") as f:
    body = json.load(f)

resp = requests.post(
    "https://api.sixtyfour.ai/workflows/create_workflow",
    headers={"x-api-key": "YOUR_API_KEY"},
    json=body,
)
resp.raise_for_status()
print("created:", resp.json()["id"])

import fs from "node:fs/promises";

const body = JSON.parse(await fs.readFile("workflow.json", "utf8"));
const resp = await fetch("https://api.sixtyfour.ai/workflows/create_workflow", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify(body),
});
if (!resp.ok) throw new Error(await resp.text());
const { id } = await resp.json();
console.log("created:", id);

Response (abridged)

{
  "id": "0b7a3c2e-5d4f-4e8a-9c61-2f3e4d5a6b7c",
  "name": "Enrich inbound leads",
  "description": "Incoming webhook → enrich people → outgoing webhook",
  "status": "ready",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "workflow_definition": { "blocks": [], "edges": [] }
}

With an API key, an invalid definition is rejected with 400 and a validation_errors list. See Validation errors.

Deploy from CI

Commit the unchanged workflow-base.json and your edited workflow-update.json together. CI submits the candidate with its stored expected_revision; it does not fetch a newer revision. Initial deployments use create_workflow. If the shared workflow changed after export, the update is refused and your files remain intact. Export the current shared document into a separate directory, compare it with the original base, and reapply your intended changes onto that new base before submitting again. Copying only a fresh revision into an older candidate overwrites intervening work. See workflow edit conflicts.

set -euo pipefail
jq -e '.expected_revision | numbers | select(. >= 0 and . == floor)' workflow-update.json > /dev/null
curl --fail -X POST "https://api.sixtyfour.ai/workflows/update_workflow?workflow_id=WORKFLOW_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @workflow-update.json

import json, os, requests

with open("workflow-update.json") as f:
    body = json.load(f)

revision = body.get("expected_revision")
if type(revision) is not int or revision < 0:
    raise ValueError("workflow-update.json must contain its exported expected_revision")
resp = requests.post(
    "https://api.sixtyfour.ai/workflows/update_workflow",
    params={"workflow_id": os.environ["WORKFLOW_ID"]},
    headers={"x-api-key": "YOUR_API_KEY"},
    json=body,
)
resp.raise_for_status()

import fs from "node:fs/promises";

const body = JSON.parse(await fs.readFile("workflow-update.json", "utf8"));
if (!Number.isSafeInteger(body.expected_revision) || body.expected_revision < 0) {
  throw new Error("workflow-update.json must contain its exported expected_revision");
}
const resp = await fetch(
  `https://api.sixtyfour.ai/workflows/update_workflow?workflow_id=${process.env.WORKFLOW_ID}`,
  {
    method: "POST",
    headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify(body),
  },
);
if (!resp.ok) throw new Error(await resp.text());

After deploying, start runs with POST /workflows/run — see Batch Processing. To deliver results to your own URL when a run completes, add an outgoing_webhook block; see Outgoing Webhooks.

Authentication

The Workflows API accepts an API key or an OAuth access token. The credential decides ownership: the definition has no organization field, so a workflow belongs to the organization of the credential that created it. An update file belongs to one workflow in that organization. To create a copy in another organization, use that organization’s credential and the creation definition without expected_revision.

Method	Use for	Header
API key	Scripts, CI, and server-to-server deploys	`x-api-key: YOUR_API_KEY`
OAuth access token	Integrations that act on behalf of a user	`Authorization: Bearer ACCESS_TOKEN`

See Get API Key and OAuth Clients. For error responses, see Handling Errors.

​The workflow definition

​Get the JSON for an existing workflow

​Create a workflow from JSON

​Deploy from CI

​Authentication

The workflow definition

Get the JSON for an existing workflow

Create a workflow from JSON

Deploy from CI

Authentication