Yokotra REST API
Automate your continuous-improvement data flows. Push KPI measurements from Databricks, Azure Data Factory, Logic Apps or any script; read your project portfolio; replace dataset rows; and connect Excel or Power BI to live CSV feeds. The API is JSON over HTTPS and is available on the Professional and Enterprise plans.
Authentication
Create a key in Settings → API keys (organization admins only). Keys look like sl_live_…, are shown once, and are stored only as a SHA-256 hash. Send the key in the Authorization header. Every request is scoped to the key's organization.
Authorization: Bearer sl_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Errors
Errors use conventional HTTP status codes and a consistent body.
{
"error": {
"code": "validation_error",
"message": "Request body is invalid.",
"issues": [ { "path": "value", "message": "Expected number, received string" } ]
}
}| 400 | invalid_json / invalid_parameter |
| 401 | unauthorized — missing, malformed or revoked key |
| 403 | plan_required — plan does not include the API |
| 404 | not_found — resource not in your organization |
| 422 | validation_error — body failed validation |
| 500 | internal_error |
Projects
/api/v1/projectsList projects in the organization.
Query parameters: status (on_track | at_risk | off_track | on_hold | completed | cancelled), phase (define | measure | analyze | improve | control | design | verify | closed)
{ "data": [ { "id": "k3j…", "key": "LSS-7", "name": "Reduce invoice errors", "methodology": "DMAIC", "phase": "measure", "status": "on_track", "estimated_savings": 120000, … } ], "count": 1 }/api/v1/projects/{id}Retrieve one project including charter fields and financials.
/api/v1/projects/{id}/tasksList the project's tasks and milestones.
/api/v1/projects/{id}/tasksCreate a task (e.g. from Azure DevOps, ServiceNow or a Logic App).
{
"title": "Validate gage R&R on line 3",
"status": "todo", // backlog | todo | in_progress | review | done
"priority": "high", // low | medium | high | critical
"phase": "measure",
"start_date": "2026-11-20",
"due_date": "2026-11-27",
"estimate_hours": 6,
"is_milestone": false
}KPIs
/api/v1/kpisList KPIs with target, specification limits and latest value.
/api/v1/kpis/{id}/measurementsList measurements in time order.
Query parameters: from, to (ISO 8601 dates)
/api/v1/kpis/{id}/measurementsAdd one or many measurements (max 5,000 per request). Out-of-control points trigger Teams/Slack alerts.
// single
{ "value": 2.31, "recordedAt": "2026-11-16", "note": "Line 3" }
// batch
{ "measurements": [
{ "value": 2.31, "recordedAt": "2026-11-15" },
{ "value": 2.12, "recordedAt": "2026-11-16T08:00:00Z" }
] }{ "data": { "inserted": 2, "ids": ["…", "…"] } }Datasets
/api/v1/datasets/{id}Retrieve a dataset's columns and rows.
/api/v1/datasets/{id}/rowsReplace all rows (max 50,000). Optionally redefine columns. Each row must have one cell per column.
{
"columns": [ { "name": "date", "type": "date" }, { "name": "cycle_time", "type": "number" } ],
"rows": [ ["2026-11-15", 41.2], ["2026-11-16", 38.9] ]
}Feeds (Excel & Power BI)
/api/v1/feeds/kpis.csvFlat KPI list with latest values. Add ?format=json for JSON.
/api/v1/feeds/kpi-measurements.csvAll measurements for all KPIs — ideal for Power BI time-series.
/api/v1/feeds/projects.csvProject portfolio with phase, status and benefits.
Examples
curl -X POST http://localhost:3000/api/v1/kpis/KPI_ID/measurements \
-H "Authorization: Bearer $YOKOTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "value": 2.31, "recordedAt": "2026-11-16", "note": "Line 3" }'# Databricks notebook — push daily KPI values to Yokotra
import requests
from pyspark.sql import functions as F
API = "http://localhost:3000/api/v1"
KEY = dbutils.secrets.get(scope="yokotra", key="api-key") # store the key in a secret scope
KPI_ID = "your-kpi-id"
daily = (spark.table("main.quality.order_lines")
.where(F.col("ship_date") >= F.date_sub(F.current_date(), 7))
.groupBy(F.col("ship_date").alias("d"))
.agg((F.sum("defects") / F.sum("units") * 1_000_000).alias("dpmo"))
.orderBy("d")
.collect())
payload = {"measurements": [
{"value": float(r.dpmo), "recordedAt": r.d.isoformat()} for r in daily
]}
resp = requests.post(f"{API}/kpis/{KPI_ID}/measurements",
json=payload,
headers={"Authorization": f"Bearer {KEY}"},
timeout=30)
resp.raise_for_status()
print(resp.json()){
"name": "PushKpiToYokotra",
"type": "WebActivity",
"typeProperties": {
"method": "POST",
"url": "http://localhost:3000/api/v1/kpis/@{pipeline().parameters.kpiId}/measurements",
"headers": {
"Authorization": "Bearer @{activity('GetSecret').output.value}",
"Content-Type": "application/json"
},
"body": {
"value": "@{activity('LookupDailyMetric').output.firstRow.value}",
"recordedAt": "@{formatDateTime(utcNow(), 'yyyy-MM-dd')}",
"note": "Azure Data Factory"
}
}
}$headers = @{ Authorization = "Bearer $env:YOKOTRA_API_KEY" }
Invoke-RestMethod "http://localhost:3000/api/v1/projects?status=at_risk" -Headers $headers |
Select-Object -ExpandProperty data | Format-Table key, name, phase, status