Dashboards API

A dashboard is a set of widgets that chart your tables. Each widget is a component spec whose figures come from table reads; the component format is in the dashboard component reference.

These endpoints are not in the OpenAPI specification.

Who can do what

A dashboard belongs to the user who created it. Changes (update, delete, layout, widgets and sharing) are allowed only for that owner. Other users in the company can read it when it is shared with the company or with them.

An API key acts for the company, not for a user. With an API key you can list and read dashboards shared with the company. Owner-only endpoints return 404 for an API key. A dashboard created with an API key has no owner, so it cannot be read back or changed with the key. Build and edit dashboards in Studio or through MCP, and use the API key to read them.

Dashboard object

Settings

List and get

GET /api/v1/dashboards
GET /api/v1/dashboards/{id}

List returns every dashboard you can view, most recently updated first, without widgets. Get returns one dashboard with its widgets.

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

{
  "success": true,
  "data": [
    {
      "id": "6a2f9c1d-4e3b-4b7a-9d81-2c5e7f0a3b96",
      "name": "Month-end close",
      "description": "AR, AP and cash at a glance",
      "layout": {},
      "settings": { "currency": "USD", "negative": "parentheses" },
      "publishedAt": null,
      "isPublished": false,
      "revokedAt": null,
      "shareExpiresAt": null,
      "companyAccess": true,
      "userId": "3b7e1f2a-9c4d-4e6b-8a10-5d2c7f9e1a42",
      "createdAt": "2026-01-20T10:00:00.000Z",
      "updatedAt": "2026-02-10T16:30:00.000Z",
      "accessReason": "company",
      "ownerName": "Jordan Lee",
      "ownerEmail": "jordan@example.com"
    }
  ]
}

A dashboard you cannot view returns 404.

Create, update and delete

POST /api/v1/dashboards
PATCH /api/v1/dashboards/{id}
DELETE /api/v1/dashboards/{id}

Create returns 201. Update returns the dashboard. Delete removes it and returns { "id": "..." }.

Widgets and layout

POST /api/v1/dashboards/{id}/widgets
PATCH /api/v1/dashboards/{id}/widgets/{widgetId}
DELETE /api/v1/dashboards/{id}/widgets/{widgetId}
PUT /api/v1/dashboards/{id}/layout

Update replaces the whole config; it does not merge a partial spec. Send at least one of config or position. The request body is limited to 1 MB. Layout takes { "widgets": [{ "id", "x", "y", "w", "h" }] } with unique widget IDs.

Every spec is checked before it is saved: it must match the component catalog, every table must belong to your company, and every column must exist. An invalid spec returns 400. A dashboard holds at most 40 widgets, 200 table reads across its widgets and 2 MB of specs; going over returns 409.

Check a spec

POST /api/v1/dashboards/specs/check

Send { "spec": { ... } }. Runs the same checks without saving and returns { "ok": true } or { "ok": false, "issues": ["..."] }.

Sharing

PATCH /api/v1/dashboards/{id}/share
GET /api/v1/dashboards/{id}/shares
POST /api/v1/dashboards/{id}/shares
DELETE /api/v1/dashboards/{id}/shares/{userId}

PATCH .../share takes action:

All sharing endpoints are owner-only. POST .../shares invites one person in your company by userId or email; an unknown person returns 404. GET .../shares lists the people invited, and DELETE .../shares/{userId} removes one.

For sharing from Studio, see Dashboards.

Errors