Skip to main content
PUT
/
api
/
dashboards
/
{id}
/
widgets
Set dashboard widget placements
curl --request PUT \
  --url https://clarus-api.com/api/dashboards/{id}/widgets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "data": {
    "type": "dashboards",
    "attributes": {
      "placements": [
        {
          "dashboard_widget_id": 12,
          "position": {
            "x": 0,
            "y": 0,
            "w": 2,
            "h": 2
          }
        },
        {
          "dashboard_widget_id": 17,
          "position": {
            "x": 2,
            "y": 0,
            "w": 4,
            "h": 2
          }
        }
      ]
    }
  }
}
'
{
  "error": "<string>"
}

​
Request Structure

{
  "data": {
    "type": "dashboards",
    "attributes": {
      "placements": [
        { "dashboard_widget_id": 12, "position": { "x": 0, "y": 0, "w": 2, "h": 2 } },
        { "dashboard_widget_id": 17, "position": { "x": 2, "y": 0, "w": 4, "h": 2 } }
      ]
    }
  }
}

​
Behavior

  • Replaces every placement on the dashboard with the supplied list, inside a single database transaction
  • A dashboard_widget_id may appear at most once in the list — duplicates are rejected with 422
  • position is optional; if omitted it is stored as an empty object and the dashboard renderer falls back to a default layout slot
  • Returns 204 No Content on success

​
Position object

position carries gridstack layout coordinates. Keys: x (column offset), y (row offset), w (column width), h (row height). All integers.

​
Acquiring widget IDs

List available widgets via the List dashboard widgets GraphQL endpoint.

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

​
X-Clarus-Subdomain
string
header
required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Path Parameters

​
id
integer
required

The unique identifier of the dashboard to set placements on

Body

application/json
​
data
object
required

Response

Operation completed successfully with no content to return