Block and action discovery

The blocks endpoints are a read-only catalog of the step types and integration actions in the deployed version of Loopfour. Use them to find an action ID, its inputs and its static choices before you add an action step to a workflow definition.

The catalog is the same for every company. It holds no connection credentials, company records or workflow data, and it makes no calls to provider APIs. Agents can start from the public OpenAPI specification or the API catalog. API responses also advertise both through the Link header.

List blocks

GET /api/v1/blocks

Returns every block that is not hidden from the editor toolbar.

Query parameters

curl -fsS 'https://workflow.loopfour.ai/api/v1/blocks?kind=integrations' \
  -H 'x-api-key: wfk_live_your_api_key'

The response is { "success": true, "data": [ ... ] }, one block object per entry.

Get one block

GET /api/v1/blocks/{type}

Returns one block by its type, for example quickbooks. Call it directly when you know the integration, so you do not download the whole catalog.

curl -fsS 'https://workflow.loopfour.ai/api/v1/blocks/quickbooks' \
  -H 'x-api-key: wfk_live_your_api_key'

{
  "success": true,
  "data": {
    "type": "quickbooks",
    "name": "QuickBooks",
    "description": "...",
    "kind": "integrations",
    "category": "...",
    "connectionRequired": true,
    "actions": ["quickbooks.runReport", "quickbooks.getInvoice"],
    "actionDefinitions": {},
    "inputs": [{ "key": "reportType", "type": "string" }],
    "outputs": ["Header", "Columns", "Rows"],
    "subBlocks": [
      {
        "id": "reportType",
        "title": "Report",
        "type": "combobox",
        "visibleWhen": { "field": "operation", "value": "runReport" },
        "options": [{ "id": "ProfitAndLoss", "label": "Profit And Loss" }]
      }
    ],
    "links": {
      "self": "/api/v1/blocks/quickbooks",
      "collection": "/api/v1/blocks"
    }
  }
}

The example is shortened. A real response lists every action, input and field.

Block fields

Read the field definitions

• Join subBlocks[].id to inputs[].key to get a field's value type. Value types are string, number, boolean, json, array and file.
• subBlocks[].type is the editor control, such as combobox. It is not the value type.
• visibleWhen says when a field applies. Compare the named field with value; an array matches any listed value. not: true negates the comparison, and an optional and condition must also match.
• When a field applies, required: true makes it mandatory. requiredWhen makes it mandatory only when that condition matches. No requirement means optional.
• Use an option's id in the workflow definition, not its label. For example, the QuickBooks Profit and Loss report is ProfitAndLoss.

These are authoring definitions, not full provider validation schemas. Choices that depend on a connection are not fetched. Whether a report or action is available can depend on the provider account's plan, permissions or region, and is checked when the step runs.

Get action examples

GET /api/v1/blocks/{type}/actions/{op}/examples

Returns the curated input and output example for one action. op is the part of the action ID after the dot, for example runReport for quickbooks.runReport.

{
  "success": true,
  "data": {
    "action": "quickbooks.runReport",
    "inputExample": null,
    "outputExample": null,
    "source": null,
    "providerDocsUrl": null,
    "capturedAt": null,
    "notes": { "input": null, "output": null },
    "links": { "block": "/api/v1/blocks/quickbooks" }
  }
}

Fields are null when the action exists but has no captured example. An unknown or hidden block, or an action the block does not list, returns 404.

Use a discovered action

Put the action ID and option IDs into an action step, then create the workflow with the Workflows API:

{
  "id": "report",
  "type": "action",
  "name": "Run profit and loss report",
  "action": "quickbooks.runReport",
  "config": {
    "connection": "8f14e45f-ceea-4e7a-9b1d-3c2a5d6e7f80",
    "reportType": "ProfitAndLoss",
    "startDate": "2026-01-01",
    "endDate": "2026-01-31"
  }
}

connection is the ID of a stored connection from the Connections API. Leave it out to use the company's default connection for that provider. Discovery never runs an action. The per-system action lists are in the integration action reference.

Errors