Update a widget
Update the supported fields of one widget.
/api/json/v1/widgets/{id}
Access and behavior
- Required scope
- api_write
- Authentication
- Bearer token
- Idempotency
- supported
- Operation ID
- updateWidget
Request headers
| Header | Presence | Description |
|---|---|---|
| Authorization | Required | Short-lived service-account bearer token. |
| Accept | Required | JSON:API response media type. |
| Idempotency-Key | Optional | Makes an unsafe request replay-safe for the configured retention window (24 hours by default). Reusing a key with different request parameters returns 409. |
| Content-Type | Required | Request document media type. |
Parameters
id
path · Required
string
No description provided.
include
query · Optional
string
Relationship paths to include in the response
fields
query · Optional
object
Limits the response fields to only those listed for each type
Request body
application/vnd.api+json
Schema: object
· Optional
config
Optional
object | null
Type-specific configuration (columns, fields, aggregations, etc.)
data_model_id
Optional
string | null
Data model id accepted by this operation.
embed_filter_allowlist
Optional
array<string> | null
Filter dimensions a public embedder may override at runtime. Defaults to allowing time_range; clear the array to lock all filters.
filters
Optional
widget_filters-input-update-type | null
Author-baseline filter set (e.g. time-range constraint) layered with dashboard/runtime overlays at read time.
name
Optional
string | null
Human-readable resource name.
type
Optional
enum: line_chart | bar_chart | map_chart | table | stat_card | markdown | heatmap | activity_feed | pivot_table | pie_chart | null
Widget visualization type
{
"data": {
"attributes": {
"config": "<config>",
"data_model_id": "00000000-0000-4000-8000-000000000001",
"embed_filter_allowlist": "<embed_filter_allowlist>",
"filters": "<filters>",
"name": "Example",
"type": "<type>"
},
"type": "resource"
}
}Success response
- Media type
- application/vnd.api+json
- Schema
- object
Errors and retries
Keep x-request-id
from failed responses. Retry only rows marked retryable, and obey
Retry-After
when present.
| Status | Code | Recovery | Meaning |
|---|---|---|---|
| 401 | unauthorized | Do not retry unchanged | A valid bearer token is required. |
| 403 | forbidden | Do not retry unchanged | The service account lacks the required scope or object access. |
| 429 | rate_limited | Retry after guidance | The request exceeded its rate window; wait for Retry-After. |
| 404 | not_found | Do not retry unchanged | The resource was not found or is not visible to the run-as member. |
| 409 | idempotency_key_reused | Do not retry unchanged | The key was previously used for a different request. |
| 422 | invalid_request | Do not retry unchanged | The request document failed resource validation. |