Update a dashboard

patch/v1/dashboards/{dashboard_id}

This endpoint is in the contract, but the API doesn't serve it during early access. It returns 404 for now.

Owner only. A dashboard the caller does not own, or the HOME template, returns 404. OAuth only.

curl -X PATCH "https://api.vojo-media.com/v1/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $VOJO_ACCESS_TOKEN" \
  -H "Vojo-Organisation: $VOJO_ORG" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ops overview (Q4)",
  "visibility": "organisation"
}'

const { data, error } = await api.PATCH("/v1/dashboards/{dashboard_id}", {
  params: { path: { dashboard_id: dashboardId } },
  body: {
    name: "Ops overview (Q4)",
    visibility: "organisation",
  },
});
if (error) throw new VojoApiError(error);

Response 200

{
  "data": {
    "id": "cm1dsh5q1w0001e8r4t7y2u6vo",
    "name": "Ops overview",
    "visibility": "organisation",
    "status": "published",
    "widgets": [
      {
        "id": "w1",
        "type": "stat",
        "col_span": 3,
        "row_span": 1,
        "config": {
          "metric": "plays",
          "range": "7d",
          "scope": {
            "entity": "org"
          }
        }
      }
    ],
    "is_owner": true,
    "can_edit": true,
    "created_at": "2026-09-14T08:12:45Z",
    "updated_at": "2026-10-07T09:30:00Z"
  },
  "meta": {}
}

Access

Authentication: OAuth access token only. Secret keys are rejected.
Scope: dashboards:write
User permission: Membership of the organisation is enough.

Path parameters

dashboard_idstringRequired
Dashboard id.

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
Vojo-Versionstring
Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.
date

Request body

at least 1 field

namestring
1 to 120 characters
visibilitystring
private = only the owner sees it; organisation = every member of the org sees it.
One of private, organisation
statusstring
Publication state of a dashboard.
One of draft, published
widgetsarray of objects
up to 48 items
Show 5 fields
- idstringRequired
  Widget id, unique within the dashboard.
  1 to 64 characters
- typestringRequired
  Dashboard widget type. The API validates widget types against this list. Adding a type is an additive change.
  One of comms, activity_map, stat, attention_list, verification
- col_spaninteger
  Grid width in columns.
  1 to 12
- row_spaninteger
  Grid height in row units.
  1 to 12
- configobject
  Widget-specific config (metric, range, scope …). Validated server-side per type.

Response 200

dataobjectRequired
A saved dashboard.
Show 9 fields
- idstringRequired
  Dashboard id. Opaque string — treat as an identifier, never parse it.
- namestringRequired
- visibilitystringRequired
  private = only the owner sees it; organisation = every member of the org sees it.
  One of private, organisation
- statusstringRequired
  Publication state of a dashboard.
  One of draft, published
- widgetsarray of objectsRequired
  Show 5 fields
  - idstringRequired
    Widget id, unique within the dashboard.
    1 to 64 characters
  - typestringRequired
    Dashboard widget type. The API validates widget types against this list. Adding a type is an additive change.
    One of comms, activity_map, stat, attention_list, verification
  - col_spaninteger
    Grid width in columns.
    1 to 12
  - row_spaninteger
    Grid height in row units.
    1 to 12
  - configobject
    Widget-specific config (metric, range, scope …). Validated server-side per type.
- is_ownerbooleanRequired
- can_editbooleanRequired
  Owner and not the Vojo-managed HOME template.
- created_atstringRequired
  RFC 3339 / ISO-8601 UTC timestamp.
  date-time
- updated_atstring or nullRequired
  RFC 3339 / ISO-8601 UTC timestamp, or null.
  date-time
metaobjectRequired
Response metadata for single-resource responses. Reserved; currently empty. Clients must ignore unknown members.

Response headers

Vojo-Versionstring
The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.
RateLimitstring
IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.
RateLimit-Policystring
IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.

Errors

Every error is application/problem+json. Branch on its code.

400
Malformed request: invalid JSON, a bad cursor, a missing Vojo-Organisation for an OAuth caller, or an unknown Vojo-Version.
401
Missing, invalid, expired or revoked credential.
403
The caller is authenticated but not allowed: missing scope (insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied).
404
The resource does not exist, or belongs to another organisation. Cross-org ids always 404, never 403.
422
Well-formed request that failed validation. errors[] lists each failing field.
429
Rate limit exceeded for this principal. Back off for Retry-After seconds.
500
Unexpected server failure.