Update dashboard widget

Updates widget placement and display settings.

PATCH /dashboards/{id}/widgets/{wgt_id}

Update dashboard widget

cURL

curl --request PATCH \
  --url https://api.akua.dev/v1/dashboards/{id}/widgets/{wgt_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'if-match: <if-match>' \
  --data '
{
  "position": 123
}
'

200

{
  "id": "<string>",
  "dashboard_id": "<string>",
  "snippet_id": "<string>",
  "position": 123,
  "created_at": 1,
  "updated_at": 1,
  "etag": "<string>"
}

Authorizations

Authorization · string · header · required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Headers

akua-context · string

Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens — a workspace-owned token implies its workspace.

Required string length: 1 - 53

Example:

"ws_j572abc123def456"

idempotency-key · string

Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.

Required string length: 1 - 64

Example:

"create-prod-2026-05-07"

if-match · string · required

The etag of the resource version the client last read. Required on writes when the resource exposes an etag field. Mismatch returns 409 ABORTED with the current etag in the error metadata.

Required string length: 1 - 256

Example:

"42"

Path Parameters

id · string · required

Required string length: 1 - 55

wgt_id · string · required

Required string length: 1 - 54

Body

application/json

col_span · Option 1 · enum<number> Option 2 · enum<number> Option 3 · enum<number> Option 4 · enum<number>

Available options: 1

position · integer

display_type · enum<string> | null

Controls how the snippet result is rendered in dashboard widgets

Available options: table, stat, json, logs, null

Response

200

application/json

Dashboard widget updated

id · string · required

Required string length: 1 - 54

dashboard_id · string · required

Required string length: 1 - 55

widget_type · enum<string> · required

Dashboard widget descriptor type. snippet is the first concrete type; future agent-authored widgets extend this field.

Available options: snippet

snippet_id · string · required

Required string length: 1 - 54

position · integer · required

col_span · Option 1 · enum<number> Option 2 · enum<number> Option 3 · enum<number> Option 4 · enum<number> · required

Available options: 1

display_type · enum<string> | null · required

Controls how the snippet result is rendered in dashboard widgets

Available options: table, stat, json, logs, null

created_at · integer · required

Unix timestamp (seconds)

Required range: x >= 0

updated_at · integer · required

Unix timestamp (seconds)

Required range: x >= 0

etag · string · required