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.

Base URL
http://localhost:3000/api/v1
Format
JSON (UTF-8); CSV for feeds
Dates
ISO 8601 — 2026-11-16 or 2026-11-16T08:00:00Z

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" } ]
  }
}
400invalid_json / invalid_parameter
401unauthorized — missing, malformed or revoked key
403plan_required — plan does not include the API
404not_found — resource not in your organization
422validation_error — body failed validation
500internal_error

Projects

GET/api/v1/projects

List 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)

Response
{ "data": [ { "id": "k3j…", "key": "LSS-7", "name": "Reduce invoice errors", "methodology": "DMAIC", "phase": "measure", "status": "on_track", "estimated_savings": 120000, … } ], "count": 1 }
GET/api/v1/projects/{id}

Retrieve one project including charter fields and financials.

GET/api/v1/projects/{id}/tasks

List the project's tasks and milestones.

POST/api/v1/projects/{id}/tasks

Create a task (e.g. from Azure DevOps, ServiceNow or a Logic App).

Request body
{
  "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

GET/api/v1/kpis

List KPIs with target, specification limits and latest value.

GET/api/v1/kpis/{id}/measurements

List measurements in time order.

Query parameters: from, to (ISO 8601 dates)

POST/api/v1/kpis/{id}/measurements

Add one or many measurements (max 5,000 per request). Out-of-control points trigger Teams/Slack alerts.

Request body
// 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" }
] }
Response
{ "data": { "inserted": 2, "ids": ["…", "…"] } }

Datasets

GET/api/v1/datasets/{id}

Retrieve a dataset's columns and rows.

PUT/api/v1/datasets/{id}/rows

Replace all rows (max 50,000). Optionally redefine columns. Each row must have one cell per column.

Request body
{
  "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)

GET/api/v1/feeds/kpis.csv

Flat KPI list with latest values. Add ?format=json for JSON.

GET/api/v1/feeds/kpi-measurements.csv

All measurements for all KPIs — ideal for Power BI time-series.

GET/api/v1/feeds/projects.csv

Project portfolio with phase, status and benefits.

Examples

cURL — add a KPI measurement
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" }'
Python — Databricks notebook (scheduled as a Databricks Job)
# 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())
Azure Data Factory — Web activity (pipeline 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"
    }
  }
}
PowerShell — list at-risk projects
$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
Prefer pull over push? Enterprise workspaces can connect Azure SQL Database, Azure Blob Storage / ADLS Gen2 and Databricks SQL warehouses directly under Integrations, run read-only queries, and refresh datasets and KPIs without writing code.