Dashboards API

A dashboard belongs to the organization, not to a project. Each one has a server-assigned ULID, a name, an optional description, an owner (the member who created it), and a visibility: public (every member of the organization can see it) or private.

Dashboards are available on the Pro and Enterprise plans. On any other plan every endpoint on this page, reads included, returns 403 forbidden; dashboardsEnabled on GET /api/v1/orgs/current tells you in advance. A downgrade deletes nothing: the organization’s dashboards come back as they were when the plan includes dashboards again.

A dashboard’s widgets have their own endpoints: see Dashboard widgets.

Who sees and who changes a dashboard

A member sees a dashboard when any of these holds:

it is public, and their own access to it was not revoked;
they created it;
they, or one of their user groups, were granted access to it.

Organization owners and admins see every dashboard. A member whose own access was revoked does not see the dashboard, even when it is public or one of their groups was granted it.

Only the dashboard’s creator and organization owners and admins can rename, redescribe, or delete it, or read and change its access, whatever other access a member holds. If the creator’s account is deleted, the dashboard stays and only owners and admins can change it.

The two refusals are kept apart on purpose:

a dashboard you cannot see answers 404 not_found on every endpoint, exactly like a ULID that does not exist, so its existence is never revealed;
a dashboard you can see but cannot change answers 403 forbidden on PATCH, PUT and DELETE, and on every access endpoint, reads included.

Create

POST/api/v1/dashboards

Requires the dashboards.write permission (held by owner/admin/member by default); a viewer receives 403 forbidden. The caller becomes the dashboard’s owner. Send accessMode: "private" to create a dashboard that is private from the start; without it, the dashboard starts public. A private dashboard can start with its members and groups already granted: the dashboard and its grants are created together, or not at all.

Request body

Field	Required	Notes
`name`	yes	Trimmed, 1–200 characters
`description`	no	Up to 2000 characters, or omitted/`null` for none
`accessMode`	no	`public` (default) or `private`; change it later with Replace settings or Access
`members`	no	User ULIDs of current organization members, each given a `granted` grant; private only
`groups`	no	User group ULIDs, each granted the dashboard; private only

members and groups take at most 200 ULIDs each, without repeats, and must be empty or omitted when the dashboard is public; otherwise 422 validation_failed. A ULID that is not a current member, or not a user group of the organization, returns 404 not_found and nothing is created. Listing yourself, an owner, or an admin is accepted, though they see the dashboard anyway. The body is strict: any other key returns 422 validation_failed.

Response

201 with the created dashboard. See Response fields.

Example

curl -sS -X POST \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Release health","accessMode":"private","members":["01J9Z3Q4M8R2T6V1W5X7Y9A0BC"],"groups":["01J9Z3R2K4N6P8Q0S2T4V6W8XY"]}' \
  "https://app.probara.net/api/v1/dashboards"

List

GET/api/v1/dashboards

Returns only the dashboards the caller can see, most recently updated first. Page-based pagination.

Parameter	Notes
`page`	Page number (1-based, default `1`)
`pageSize`	Items per page (default `50`, max `200`)

200 with { items, page, pageSize, total }. total counts only the dashboards the caller can see.

Get

GET/api/v1/dashboards/{dashboardUlid}

200 with the dashboard, or 404 not_found when the caller cannot see it. A malformed ULID returns 422 validation_failed.

Update

PATCH/api/v1/dashboards/{dashboardUlid}

Changes name and/or description (null clears the description). At least one field is required, and the body is strict: any other key, accessMode included, returns 422 validation_failed (visibility changes through Replace settings or Access). A body that changes nothing returns the dashboard as it is, without moving updatedAt or recording an audit event.

200 with the updated dashboard. 403 forbidden when the caller can see the dashboard but neither created it nor is an organization owner or admin; 404 not_found when the caller cannot see it.

Replace settings

PUT/api/v1/dashboards/{dashboardUlid}

Sets the whole settings state of a dashboard in one call, all or nothing. This is what the dashboard’s settings dialog in the app saves. Same 403/404 rules as Update.

Field	Required	Notes
`name`	yes	Trimmed, 1–200 characters
`description`	yes	Up to 2000 characters, or `null` for none
`accessMode`	yes	`public` or `private`
`members`	yes	User ULIDs of current organization members who hold a `granted` grant after the call
`groups`	yes	User group ULIDs granted the dashboard after the call

The lists follow the rules of Create: at most 200 ULIDs each, no repeats, empty on a public dashboard, and 404 not_found for a ULID that is not a current member or a user group of the organization (nothing changes).

After the call, exactly the listed members hold a granted grant and exactly the listed groups are granted the dashboard: missing ones are added, the rest are removed. revoked grants are not part of this state. One you do not list stays as it is; listing a member whose grant is revoked turns it into granted. Making the dashboard public removes every granted grant and every group grant, and keeps the revoked ones.

Each change is recorded like the matching Access call. A body that changes nothing returns the dashboard as it is and records nothing. updatedAt moves when the name, the description, or the visibility changes; changing only members or groups leaves it, as the Access calls do.

200 with the dashboard. See Response fields.

Delete

DELETE/api/v1/dashboards/{dashboardUlid}

Permanently deletes the dashboard and every access grant it holds. Same 403/404 rules as Update.

204 with no body.

Access

Who sees a dashboard is managed under /api/v1/dashboards/{dashboardUlid}/access, shaped like project access. Every endpoint here, reads included, follows the 403/404 rules of Update: only the creator and organization owners and admins use them. Every change records a dashboard.access_changed audit event; a request that changes nothing records nothing.

Read the access state

GET/api/v1/dashboards/{dashboardUlid}/access

200 with:

Field	Type	Notes
`mode`	string	`public` or `private`
`ownerUserUlid`	string \| null	The creator, who always sees and edits the dashboard
`grantedCount`	number	Members holding a `granted` grant, members who have left included
`revokedCount`	number	Members holding a `revoked` grant, members who have left included

Make a dashboard public or private

PATCH /api/v1/dashboards/{dashboardUlid}/access with { "mode": "public" } or { "mode": "private" }.

Private hides the dashboard from every member without a grant. Its creator and organization owners and admins keep seeing it without one.
Public removes every granted grant and every group grant: making it private again starts from empty lists. revoked grants stay.

mode is required and is the only field: a dashboard’s owner is always its creator and cannot be transferred. 200 with the access state; updatedAt on the dashboard moves when the mode changes.

Member grants

A member grant has an access value:

granted lets the member into a private dashboard. It is refused on a public dashboard with 409 conflict, because every member already sees it.
revoked keeps the member out: out of a public dashboard, and out of a private one even when one of their user groups was granted it.

Endpoint	Result
`GET /api/v1/dashboards/{dashboardUlid}/access/members`	`200`, page of members holding a grant, each with its `access`
`POST /api/v1/dashboards/{dashboardUlid}/access/members`	`201`, the member with its grant
`DELETE /api/v1/dashboards/{dashboardUlid}/access/members/{userUlid}`	`204`; the dashboard’s mode decides again

The list is page-based (page, pageSize), oldest member first, and shows only current members. Items carry the same member fields as the project access members list plus access. The creator and owners and admins appear only if they hold a grant.

POST takes { "userUlid": "…", "access": "revoked" }; access defaults to granted. It creates the grant or changes its value. The target must be a current member of the organization, otherwise 404 not_found. DELETE removes the grant whatever its value, also for a member who has since left the organization; 404 not_found when the member holds none.

Group grants

Endpoint	Result
`GET /api/v1/dashboards/{dashboardUlid}/access/groups`	`200`, page of granted groups, by name
`POST /api/v1/dashboards/{dashboardUlid}/access/groups`	`201`, the group
`DELETE /api/v1/dashboards/{dashboardUlid}/access/groups/{userGroupUlid}`	`204`

POST takes { "userGroupUlid": "…" }. Every current and future member of the group sees the dashboard while it is private. A group grant on a public dashboard is refused with 409 conflict, because every member already sees it. Group items carry ulid, name, description and userCount (current members). An unknown group, or a DELETE for a group that holds no grant, returns 404 not_found.

Example

curl -sS -X POST \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userUlid":"01J9Z3Q4M8R2T6V1W5X7Y9A0BC","access":"revoked"}' \
  "https://app.probara.net/api/v1/dashboards/$DASHBOARD_ULID/access/members"

Response fields

Field	Type	Notes
`ulid`	string	The dashboard’s ULID
`name`	string
`description`	string \| null
`ownerUserUlid`	string \| null	The member who created it; `null` once that account is deleted
`accessMode`	string	`public` or `private`
`createdAt`	number	Epoch milliseconds
`updatedAt`	number	Epoch milliseconds; moves on every rename, description change, visibility change, or widget change
`canEdit`	boolean	Whether you may rename and delete it: `true` for its creator and owners and admins

Audit events

Every create, update, delete, and access change records an event in the organization’s activity feed with entity type dashboard, labelled with the dashboard’s name: dashboard.created (metadata accessMode), dashboard.updated (metadata changes, one entry per changed field), dashboard.deleted, and dashboard.access_changed. The metadata reason of an access change is one of:

`reason`	Other metadata	Change
`mode_toggle`	`mode`	Made public or private
`member_granted`	`targetUserId`	Member grant set to `granted`
`member_revoked`	`targetUserId`	Member grant set to `revoked`
`member_cleared`	`targetUserId`, `previousAccess`	Member grant removed
`group_granted`	`userGroupUlid`	Group granted
`group_revoked`	`userGroupUlid`	Group grant removed

A create that grants members and groups records dashboard.created followed by one member_granted or group_granted event per grant. A settings replace records dashboard.updated when the name or description changed, then one dashboard.access_changed event per change: mode_toggle, member_granted, member_cleared (with previousAccess: "granted"), group_granted, group_revoked. Making a dashboard public with PATCH …/access records mode_toggle followed by one group_revoked per group grant it removed.

See Audit events.

MCP

The same operations are available as the MCP tools list_dashboards, get_dashboard, create_dashboard (with members and groups), update_dashboard, replace_dashboard_settings, and delete_dashboard, and for access get_dashboard_access, update_dashboard_access, list_dashboard_access_members, set_dashboard_access_member, remove_dashboard_access_member, list_dashboard_access_groups, add_dashboard_access_group, and remove_dashboard_access_group, with the same plan and access rules. See the MCP tool reference.