Create Dataset

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', description: '<string>', kpis: {}})
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets"

payload = {
    "name": "<string>",
    "description": "<string>",
    "kpis": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/custom-kpi-datasets \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "kpis": {}
}
'

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": {},
  "created_by": {},
  "created_at": {},
  "updated_at": {},
  "kpis": {}
}

POST

custom-kpi-datasets

Create Dataset

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', description: '<string>', kpis: {}})
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets"

payload = {
    "name": "<string>",
    "description": "<string>",
    "kpis": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/custom-kpi-datasets \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "kpis": {}
}
'

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": {},
  "created_by": {},
  "created_at": {},
  "updated_at": {},
  "kpis": {}
}

Create Dataset

Create a new custom KPI dataset for your organization. You can optionally include KPI definitions inline — each KPI defines a question that data owners will answer during campaigns.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Body Parameters

string

required

Dataset name (1–255 characters)Example: "Water Usage Survey"

string

Dataset description (max 2000 characters)Example: "Monthly water consumption across all facilities"

array[object]

Optional list of KPI definitions to create with the dataset (max 100).Each KPI object accepts:

Field	Type	Required	Description
`name`	string	Yes	KPI name (1–255 chars)
`description`	string	No	KPI description (max 2000 chars)
`unit`	string	No	Measurement unit (max 50 chars), e.g. `"m³"`, `"kWh"`
`value_type`	string	No	Answer type: `number` (default), `text`, `percentage`, `date`, `boolean`, `select`
`required`	boolean	No	Whether a value is mandatory (default `true`)
`sort_order`	integer	No	Display order (default `0`)
`options`	array	Conditional	Required for `select` type — list of `{label, sort_order}` objects (2–100 options)

Response

Returns the created dataset with its KPI definitions (HTTP 201). The response uses the same shape as Get Dataset.

string

Dataset UUID.

string

UUID of the organization that owns this dataset.

string

Dataset display name.

string | null

Dataset description.

string | null

UUID of the user who created the dataset.

datetime

Timestamp when the dataset was created

datetime | null

Timestamp when the dataset was last updated

array[object]

KPI definitions created with this dataset. See Get Dataset for the full KPI object shape.

Example

curl -X POST "https://api.dcycle.io/v1/custom-kpi-datasets" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Water Usage Survey",
    "description": "Monthly water consumption across facilities",
    "kpis": [
      {
        "name": "Total water consumed",
        "unit": "m³",
        "value_type": "number",
        "required": true,
        "sort_order": 0
      },
      {
        "name": "Water source",
        "value_type": "select",
        "options": [
          {"label": "Municipal supply", "sort_order": 0},
          {"label": "Well water", "sort_order": 1},
          {"label": "Rainwater harvesting", "sort_order": 2}
        ],
        "sort_order": 1
      }
    ]
  }'

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",
}

response = requests.post(
    "https://api.dcycle.io/v1/custom-kpi-datasets",
    headers=headers,
    json={
        "name": "Water Usage Survey",
        "description": "Monthly water consumption across facilities",
        "kpis": [
            {
                "name": "Total water consumed",
                "unit": "m³",
                "value_type": "number",
                "required": True,
                "sort_order": 0,
            },
            {
                "name": "Water source",
                "value_type": "select",
                "options": [
                    {"label": "Municipal supply", "sort_order": 0},
                    {"label": "Well water", "sort_order": 1},
                    {"label": "Rainwater harvesting", "sort_order": 2},
                ],
                "sort_order": 1,
            },
        ],
    },
)

dataset = response.json()
print(f"Created dataset: {dataset['id']} with {len(dataset['kpis'])} KPIs")

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',
};

axios.post('https://api.dcycle.io/v1/custom-kpi-datasets', {
  name: 'Water Usage Survey',
  description: 'Monthly water consumption across facilities',
  kpis: [
    { name: 'Total water consumed', unit: 'm³', value_type: 'number', required: true, sort_order: 0 },
    {
      name: 'Water source',
      value_type: 'select',
      options: [
        { label: 'Municipal supply', sort_order: 0 },
        { label: 'Well water', sort_order: 1 },
        { label: 'Rainwater harvesting', sort_order: 2 },
      ],
      sort_order: 1,
    },
  ],
}, { headers })
.then(response => console.log(`Created: ${response.data.id}`));

Successful Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "name": "Water Usage Survey",
  "description": "Monthly water consumption across facilities",
  "created_by": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "updated_by": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": null,
  "kpis": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Total water consumed",
      "description": null,
      "unit": "m³",
      "value_type": "number",
      "required": true,
      "sort_order": 0,
      "options": [],
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": null
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Water source",
      "description": null,
      "unit": null,
      "value_type": "select",
      "required": true,
      "sort_order": 1,
      "options": [
        {"id": "e5f6a7b8-c9d0-1234-efab-345678901234", "label": "Municipal supply", "sort_order": 0},
        {"id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "label": "Well water", "sort_order": 1},
        {"id": "a7b8c9d0-e1f2-3456-abcd-567890123456", "label": "Rainwater harvesting", "sort_order": 2}
      ],
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": null
    }
  ]
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

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

403 Forbidden

Cause: The authenticated user is not a member of the organization

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

422 Validation Error

Cause: Select KPI missing options

{
  "detail": [
    {
      "loc": ["body", "kpis", 0, "__root__"],
      "msg": "A select KPI must define options.",
      "type": "value_error"
    }
  ]
}

Cause: Duplicate option labels (case-insensitive)

{
  "detail": [
    {
      "loc": ["body", "kpis", 0, "__root__"],
      "msg": "Option labels must be unique (case-insensitive) within a KPI.",
      "type": "value_error"
    }
  ]
}

List Datasets

View all datasets

Get Dataset

View a single dataset with KPIs

​Create Dataset

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​Related Endpoints

List Datasets

Get Dataset

Create Dataset

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Validation Error

Related Endpoints