Update Dashboard

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({widgets: [{}], layouts: {}})
};

fetch('https://api.dcycle.io/v2/dashboard/{dashboard_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/dashboard/{dashboard_id}"

payload = {
    "widgets": [{}],
    "layouts": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v2/dashboard/{dashboard_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "widgets": [
    {}
  ],
  "layouts": {}
}
'

{
  "id": "<string>",
  "project_id": "<string>",
  "widgets": [
    {}
  ],
  "layouts": {},
  "created_at": {},
  "updated_at": {}
}

PATCH

dashboard

{dashboard_id}

Update Dashboard

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({widgets: [{}], layouts: {}})
};

fetch('https://api.dcycle.io/v2/dashboard/{dashboard_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/dashboard/{dashboard_id}"

payload = {
    "widgets": [{}],
    "layouts": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v2/dashboard/{dashboard_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "widgets": [
    {}
  ],
  "layouts": {}
}
'

{
  "id": "<string>",
  "project_id": "<string>",
  "widgets": [
    {}
  ],
  "layouts": {},
  "created_at": {},
  "updated_at": {}
}

Update Dashboard

Update a dashboard’s widgets and/or layouts. Only the organization that owns the project can modify its dashboards — child organizations in the hierarchy have read-only access.

Unknown fields are rejected (extra = "forbid"). Only send widgets and/or layouts in the request body.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

UUID of the dashboard to updateExample: "550e8400-e29b-41d4-a716-446655440000"

Body Parameters

array

Updated list of widget configurations. Each widget requires id, name, and config.

object

Updated responsive grid layouts by breakpoint (lg, md, sm, xs, xxs).

Response

Returns the updated dashboard object with HTTP 200.

string

Dashboard UUID

string

UUID of the associated project

array

Updated list of widget configurations

object

Updated responsive grid layouts

datetime

Creation timestamp (ISO 8601)

datetime | null

Last update timestamp (ISO 8601)

Example

curl -X PATCH "https://api.dcycle.io/v2/dashboard/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "widgets": [
      {
        "id": "widget-1",
        "name": "Total Emissions 2024",
        "type": "bar_chart",
        "config": {
          "metrics": [{
            "id": "m1",
            "category": "emissions",
            "filters": [],
            "aggregation": { "organizations": [{ "id": "org-uuid" }] }
          }],
          "periodicity": "monthly",
          "periods": [{ "start_date": "2024-01-01", "end_date": "2024-12-31" }],
          "unit": "tCO2e"
        }
      }
    ],
    "layouts": {
      "lg": [{ "i": "widget-1", "x": 0, "y": 0, "w": 12, "h": 6 }],
      "md": [{ "i": "widget-1", "x": 0, "y": 0, "w": 10, "h": 6 }],
      "sm": [{ "i": "widget-1", "x": 0, "y": 0, "w": 6, "h": 4 }],
      "xs": [{ "i": "widget-1", "x": 0, "y": 0, "w": 4, "h": 4 }],
      "xxs": [{ "i": "widget-1", "x": 0, "y": 0, "w": 2, "h": 4 }]
    }
  }'

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "Content-Type": "application/json",
}

dashboard_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.patch(
    f"https://api.dcycle.io/v2/dashboard/{dashboard_id}",
    headers=headers,
    json={
        "widgets": [
            {
                "id": "widget-1",
                "name": "Total Emissions 2024",
                "type": "bar_chart",
                "config": {
                    "metrics": [{"id": "m1", "category": "emissions"}],
                    "periodicity": "monthly",
                    "periods": [{"start_date": "2024-01-01", "end_date": "2024-12-31"}],
                    "unit": "tCO2e",
                },
            }
        ],
        "layouts": {
            "lg": [{"i": "widget-1", "x": 0, "y": 0, "w": 12, "h": 6}],
        },
    },
)

dashboard = response.json()
print(f"Updated: {len(dashboard['widgets'])} widgets")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'Content-Type': 'application/json',
};

const dashboardId = '550e8400-e29b-41d4-a716-446655440000';

axios.patch(`https://api.dcycle.io/v2/dashboard/${dashboardId}`, {
  widgets: [{
    id: 'widget-1',
    name: 'Total Emissions 2024',
    type: 'bar_chart',
    config: {
      metrics: [{ id: 'm1', category: 'emissions' }],
      periodicity: 'monthly',
      periods: [{ start_date: '2024-01-01', end_date: '2024-12-31' }],
      unit: 'tCO2e',
    },
  }],
}, { headers })
.then(response => console.log(`Updated: ${response.data.widgets.length} widgets`));

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "widgets": [
    {
      "id": "widget-1",
      "name": "Total Emissions 2024",
      "type": "bar_chart",
      "config": { ... }
    }
  ],
  "layouts": {
    "lg": [{ "i": "widget-1", "x": 0, "y": 0, "w": 12, "h": 6 }],
    "md": [],
    "sm": [],
    "xs": [],
    "xxs": []
  },
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-12-20T09:15:00Z"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The user is not a member of the organization, or your organization is not the owner of this dashboard’s project

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

{
  "detail": "Only the owning organization can modify this dashboard."
}

404 Not Found

Cause: Dashboard does not exist

{
  "detail": "Not found."
}

422 Validation Error

Cause: Request body contains unknown fields

{
  "detail": [
    {
      "loc": ["body", "unknown_field"],
      "msg": "extra fields not permitted",
      "type": "value_error.extra"
    }
  ]
}

Get Dashboard

View the current dashboard state

Delete Dashboard

Remove a dashboard

​Update Dashboard

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​Related Endpoints

Get Dashboard

Delete Dashboard

Update Dashboard

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints