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 with optional inline KPI definitions
POST
/
v1
/
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": {}
}← Custom KPI
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.
Cause: Duplicate option labels (case-insensitive)
Request
Headers
Body Parameters
Dataset description (max 2000 characters)Example:
"Monthly water consumption across all facilities"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, number_breakdown |
required | boolean | No | Whether a value is mandatory (default true) |
sort_order | integer | No | Display order (default 0) |
options | array | Conditional | Required for select and number_breakdown types (the choices of a select, the categories of a breakdown), forbidden for the others — 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.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 or number_breakdown KPI missing options
{
"detail": [
{
"loc": ["body", "kpis", 0, "__root__"],
"msg": "A select KPI must define options.",
"type": "value_error"
}
]
}
{
"detail": [
{
"loc": ["body", "kpis", 0, "__root__"],
"msg": "Option labels must be unique (case-insensitive) within a KPI.",
"type": "value_error"
}
]
}
Related Endpoints
List Datasets
View all datasets
Get Dataset
View a single dataset with KPIs
Was this page helpful?