Dashboards API

Dashboards of numbers, charts and tables built from your Base tables and your reports.

Module code dashboards · 6 actions · 2 data models · 3 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: dashboards (everything), dashboards:read (read only) or dashboards:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

dashboards.arrange_widgets

Rearrange widgets — Puts a board’s widgets in a new order.

Needs dashboards:write · changes data

• Canonical address: POST /api/v1/actions/dashboards.arrange_widgets

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: dashboards.dashboard_changed

What it writes: dashboard_widget (update) — Renumbers the widgets

curl -X POST https://app.getera.io/api/v1/dashboard_widgets/actions/arrange_widgets \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"dashboardId":"DASHBOARD_ID","order":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "dashboards.dashboard_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dashboardWidgets.arrangeWidgets({
  dashboardId: "DASHBOARD_ID",
  order: {}
})

era dashboard_widgets arrange_widgets --data '{"dashboardId":"DASHBOARD_ID","order":{}}'

{
  "name": "era__dashboards__arrange_widgets",
  "arguments": {
    "dashboardId": "DASHBOARD_ID",
    "order": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold dashboards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 dashboard_not_found · 429 slow down

dashboards.create_dashboard

New dashboard — Opens an empty board to put figures and charts on.

Needs dashboards:write · changes data

• REST alias: POST /api/v1/dashboards
• Canonical address: POST /api/v1/actions/dashboards.create_dashboard

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: dashboards.dashboard_created

What it writes: dashboard (insert) — Creates the board

curl -X POST https://app.getera.io/api/v1/dashboards/actions/create_dashboard \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "dashboards.dashboard_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dashboards.create({
  title: "Name"
})

era dashboards create \
  --title "Name"

{
  "name": "era__dashboards__create_dashboard",
  "arguments": {
    "title": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold dashboards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 title_required, name_taken · 429 slow down

dashboards.delete_dashboard

Delete a dashboard — Removes a board and its widgets. The tables it read are untouched.

Needs dashboards:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/dashboards/{id}
• Canonical address: POST /api/v1/actions/dashboards.delete_dashboard

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: dashboards.dashboard_deleted

What it writes: dashboard (delete) — Deletes the board; dashboard_widget (delete) — And every widget on it

curl -X POST https://app.getera.io/api/v1/dashboards/DASHBOARD_ID/actions/delete_dashboard \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "dashboards.dashboard_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dashboards.deleteDashboard("DASHBOARD_ID")

era dashboards delete_dashboard DASHBOARD_ID

{
  "name": "era__dashboards__delete_dashboard",
  "arguments": {
    "id": "DASHBOARD_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold dashboards:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 dashboard_not_found · 429 slow down

dashboards.remove_widget

Remove a widget — Takes one widget off its board.

Needs dashboards:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/dashboards.remove_widget

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: dashboards.dashboard_changed

What it writes: dashboard_widget (delete) — Deletes the widget

curl -X POST https://app.getera.io/api/v1/dashboard_widgets/DASHBOARD_WIDGET_ID/actions/remove_widget \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "dashboards.dashboard_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dashboardWidgets.removeWidget("DASHBOARD_WIDGET_ID")

era dashboard_widgets remove_widget DASHBOARD_WIDGET_ID

{
  "name": "era__dashboards__remove_widget",
  "arguments": {
    "id": "DASHBOARD_WIDGET_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold dashboards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 widget_not_found · 429 slow down

dashboards.save_widget

Add or edit a widget — Puts a figure, chart, table or note on a board, reading one Base table or view, or one of the modules’ reports.

Needs dashboards:write · changes data

• Canonical address: POST /api/v1/actions/dashboards.save_widget

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: dashboards.dashboard_changed

What it writes: dashboard_widget (upsert) — Writes the widget

curl -X POST https://app.getera.io/api/v1/dashboard_widgets/DASHBOARD_WIDGET_ID/actions/save_widget \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"dashboardId":"DASHBOARD_ID","kind":"metric","title":"Title"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "dashboards.dashboard_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dashboardWidgets.saveWidget("DASHBOARD_WIDGET_ID", {
  dashboardId: "DASHBOARD_ID",
  kind: "metric",
  title: "Title"
})

era dashboard_widgets save_widget DASHBOARD_WIDGET_ID \
  --dashboard-id "DASHBOARD_ID" \
  --kind "metric" \
  --title "Title"

{
  "name": "era__dashboards__save_widget",
  "arguments": {
    "id": "DASHBOARD_WIDGET_ID",
    "dashboardId": "DASHBOARD_ID",
    "kind": "metric",
    "title": "Title"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold dashboards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 dashboard_not_found, widget_not_found, source_table_not_found, dataset_not_found, invalid_widget_config · 429 slow down

dashboards.update_dashboard

Rename a dashboard — Changes a board’s name or description.

Needs dashboards:write · changes data

• REST alias: PATCH /api/v1/dashboards/{id}
• Canonical address: POST /api/v1/actions/dashboards.update_dashboard

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: dashboards.dashboard_changed

What it writes: dashboard (update) — Renames the board

curl -X POST https://app.getera.io/api/v1/dashboards/DASHBOARD_ID/actions/update_dashboard \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "dashboards.dashboard_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dashboards.updateDashboard("DASHBOARD_ID", {
  title: "Name"
})

era dashboards update_dashboard DASHBOARD_ID \
  --title "Name"

{
  "name": "era__dashboards__update_dashboard",
  "arguments": {
    "id": "DASHBOARD_ID",
    "title": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold dashboards:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 dashboard_not_found, name_taken, no_change · 429 slow down

Data models

DashboardWidget

Table dashboard_widget · Resource dashboard_widgets

• GET /api/v1/dashboard_widgets
• GET /api/v1/dashboard_widgets/{id}

Primary key: id

Checks:

• CHECK ((jsonb_typeof(config) = 'object'::text))
• CHECK (((dataset_key IS NULL) OR (dataset_key ~ '^[a-z0-9_]+\.[a-z0-9_]+$'::text)))
• CHECK (((kind = 'text'::text) OR (data_table_id IS NOT NULL) OR (dataset_key IS NOT NULL)))
• CHECK (((width >= 1) AND (width <= 4)))

Dashboard

Table dashboard · Resource dashboards

• GET /api/v1/dashboards
• GET /api/v1/dashboards/{id}
• POST /api/v1/dashboards → dashboards.create_dashboard
• PATCH /api/v1/dashboards/{id} → dashboards.update_dashboard
• DELETE /api/v1/dashboards/{id} → dashboards.delete_dashboard

Primary key: id

Checks:

• CHECK ((btrim(title) <> ''::text))

Events

Workflows and webhooks react to these events.