Block and Action Discovery

Discover blocks and actions

Use this read-only catalog to discover the actions available in the deployed version of Loopfour. Responses include action IDs, input types and declared nested schemas, field requirements, static choices, and output field names. The same metadata is available to workflow chat authoring.

Agents can start from the public OpenAPI specification or machine-readable API catalog. REST responses also advertise these resources through the standard Link header, including authentication errors. In OpenAPI, use listBlocks when the integration is unknown and getBlock when its type is already known.

Both endpoints require authentication with the x-api-key header and the workflows:read scope. Session authentication is also accepted. The standard read rate limit applies. The catalog is shared across workspaces; it contains no connection credentials, company records, or workflow data, and makes no provider API calls.

GET /api/v1/blocks
GET /api/v1/blocks/:type

The list accepts an optional kind query parameter: core, integrations, or triggers. It returns the complete matching catalog without pagination. Hidden internal blocks are excluded from both endpoints.

Each result includes links.self for its detail endpoint and links.collection for the catalog. These are root-relative URLs: resolve them against the API origin. If you already know the integration, request /blocks/quickbooks directly to avoid downloading the complete catalog.

curl -fsS 'https://workflow.loopfour.ai/api/v1/blocks?kind=integrations' \
  -H 'x-api-key: wfk_your_api_key' \
  | jq '.data[] | {type, name, actions}'

Discover QuickBooks reports

curl -fsS 'https://workflow.loopfour.ai/api/v1/blocks/quickbooks' \
  -H 'x-api-key: wfk_your_api_key' \
  | jq '.data | {actions, inputs, outputs, report: (.subBlocks[] | select(.id == "reportType"))}'

The response includes quickbooks.runReport in actions and all 30 report names in the reportType field's options. For example, the Profit and Loss choice has id: "ProfitAndLoss". Use the option ID in workflow configuration, rather than its display label.

The list response is { "success": true, "data": [...] }; the detail response is { "success": true, "data": { ... } }. Every block has these fields:

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 identifies the authoring control, such as combobox; it is not the value type.

visibleWhen determines whether a field applies to the selected configuration. For QuickBooks reports it is { "field": "operation", "value": "runReport" }. Compare the named field with value; an array matches any listed value. not: true negates that comparison. An optional and condition must also match. When a field is applicable, required: true makes it mandatory; requiredWhen instead makes it mandatory only when that condition matches. An absent requirement means optional.

These are the block's authoring definitions, not exhaustive provider validation schemas. A nested schema is included only where declared. Connection-dependent choices are not fetched. Report and action availability can depend on the QuickBooks company's plan, permissions, or region and is checked during execution.

Build and run the discovered action

Use the discovered ID in a workflow action step:

{
  "id": "report",
  "type": "action",
  "action": "quickbooks.runReport",
  "config": {
    "connection": "<quickbooks-connection-id>",
    "reportType": "ProfitAndLoss",
    "startDate": "2026-01-01",
    "endDate": "2026-01-31"
  }
}

Create the workflow with POST /api/v1/workflows and execute it with POST /api/v1/workflows/:id/run. Running a report returns Header, Columns, and nested Rows for downstream analysis. Discovery itself never executes an action.

Errors