Process Radar API Documentation

API Version: 1.0.0

Base URL: https://api.dkyra.com/api/v1

Authentication: API Key or JWT Token

Last Updated: 2026-07-03

Overview

Process Radar analyzes ITSM ticket workflows to automatically identify anomalies, bottlenecks, and optimization opportunities across teams. The API provides programmatic access to analysis results, prioritized situations, health metrics, and delegation workflows.

Key Concepts

Authentication

All API requests require authentication via one of:

API Key (Header)

X-API-Key: your-api-key

JWT Bearer Token

Authorization: Bearer your-jwt-token

Obtaining Credentials

API Key: Create via Settings → API Keys in the Process Radar UI.

JWT Token: Use the login endpoint:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 300
}

Access tokens are short-lived (expires_in is in seconds — 5 minutes). Use POST /api/v1/auth/refresh with the refresh token to obtain a new one before expiry. For long-running integrations, prefer API-Key authentication.

Quick Start

Step 1: Upload data

curl -X POST https://api.dkyra.com/api/v1/datasets/upload \
  -H "X-API-Key: YOUR_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "name=Q1 Analysis"

Step 2: Start analysis

curl -X POST https://api.dkyra.com/api/v1/datasets/{dataset_id}/runs \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 Deep Dive"}'

Step 3: Get results

curl https://api.dkyra.com/api/v1/executive-summary \
  -H "X-API-Key: YOUR_KEY"

Core Endpoints

Health Check

GET /health

Returns API status. No authentication required.

Response:

{
  "status": "ok"
}

Datasets & Upload

#### List Datasets

GET /api/v1/datasets

Returns all datasets for the current tenant, including run counts.

Response:

[
  {
    "dataset_id": "uuid",
    "name": "Q1 2026 Analysis",
    "status": "uploaded",
    "created_at": "2026-02-09T10:00:00Z",
    "run_count": 3,
    "ticket_count": 1500,
    "event_count": 45000
  }
]

#### Upload CSV Files

POST /api/v1/datasets/upload

Creates a dataset and uploads CSV files in one step. Uses multipart/form-data.

Form Fields:

Response (200):

{
  "dataset_id": "uuid",
  "status": "uploaded",
  "validation": {
    "tickets_count": 1500,
    "events_count": 45000,
    "warnings": []
  }
}

#### Delete Dataset

DELETE /api/v1/datasets/{dataset_id}?confirm=true

Deletes a dataset and ALL associated data. Requires confirm=true as safety guard.

Analysis Runs

#### Start Analysis Run

POST /api/v1/datasets/{dataset_id}/runs

Starts an analysis run asynchronously. Returns 202 Accepted immediately.

Request Body:

{
  "name": "Q1 Deep Dive"
}

Response (202):

{
  "run_id": "uuid",
  "status": "running",
  "name": "Q1 Deep Dive",
  "message": "Analysis started"
}

#### List Runs

GET /api/v1/runs

Returns all runs for the current tenant.

Parameters:

#### Get Run Status

GET /api/v1/runs/{run_id}

Response:

{
  "run_id": "uuid",
  "dataset_id": "uuid",
  "status": "SUCCEEDED",
  "name": "Q1 Deep Dive",
  "findings_count": 181,
  "progress_phase": "complete",
  "progress_percent": 100,
  "message": null,
  "error": null,
  "created_at": "2026-02-09T10:00:00Z",
  "started_at": "2026-02-09T10:00:00Z",
  "finished_at": "2026-02-09T10:02:30Z"
}

Executive Summary Endpoints

These aggregated endpoints are designed for AI agents, dashboards, and third-party integrations. They return high-level KPIs without requiring knowledge of internal data structures.

#### Executive Summary

GET /api/v1/executive-summary

High-level briefing with system health, prioritized situations, and trend information.

Parameters:

Response:

{
  "health_score": {
    "score": 62,
    "grade": "C"
  },
  "priority_situations": [
    {
      "situation_id": "sit-abc-123",
      "headline": "Level-1-Support: Kapazitätsengpass mit steigender Tendenz",
      "situation_type": "capacity_bottleneck",
      "impact_hours": 342.5,
      "trend": "worsening",
      "recommendation": "delegate",
      "finding_count": 4,
      "tier": "critical"
    }
  ],
  "open_delegations": 2,
  "trend_summary": {
    "direction": "worsening",
    "new_situations": 1,
    "resolved_situations": 0
  },
  "period": {
    "start": "2024-01-01T00:00:00",
    "end": "2024-12-31T00:00:00",
    "run_id": "run-xyz-456"
  }
}

#### Analysis Summary

GET /api/v1/analysis-summary

Aggregated analysis KPIs — anomaly distribution, trends, and most affected roles.

Response:

{
  "total_findings": 23,
  "tier_distribution": {
    "critical": 3,
    "notable": 8,
    "observed": 12
  },
  "new_findings": 2,
  "trend_distribution": {
    "worsening": 5,
    "stable": 12,
    "improving": 4,
    "new": 2
  },
  "top_affected_roles": [
    {
      "role": "Level-1-Support",
      "finding_count": 6,
      "dominant_tier": "critical"
    }
  ],
  "last_analysis_at": "2024-12-15T14:30:00"
}

#### Flow Health

GET /api/v1/flow-health

System-wide flow health metrics — bottleneck roles and capacity status.

Response:

{
  "roles_in_bottleneck": 2,
  "total_active_roles": 8,
  "bottleneck_roles": [
    {
      "role": "Level-1-Support",
      "severity": "critical",
      "state": "persistent overload"
    },
    {
      "role": "Incident-Management",
      "severity": "notable",
      "state": "growing overload"
    }
  ],
  "health_grade": "C"
}

Findings

#### List Findings

GET /api/v1/runs/{run_id}/findings

Returns all detected anomalies for an analysis run with filtering and sorting.

Parameters:

Response:

{
  "findings": [
    {
      "finding_id": "cbf7fec4-f9a2-...",
      "finding_type": "F1_ROLE_HIGH_DWELL",
      "tier": "critical",
      "dimensions": ["role"],
      "constellation": {
        "role": "2nd Level Support"
      },
      "statements": {
        "de": "Die Rolle '2nd Level Support' zeigt eine deutlich höhere Verweildauer als der globale Median (89.4h vs. 12.0h, +645%). Robustheit: Hoch (234 Tickets).",
        "en": "Role '2nd Level Support' shows significantly higher dwell time than the global median (89.4h vs. 12.0h, +645%). Robustness: High (234 tickets)."
      },
      "confidence": {
        "level": "high",
        "description_de": "Hoch",
        "description_en": "High"
      },
      "volume": {
        "ticket_count": 234,
        "interval_count": 456
      },
      "impact_hours": 1250.5,
      "relevance_score": 0.82,
      "trend": "stable",
      "temporal": {
        "definition_id": "uuid",
        "first_seen": "2024-01-15",
        "last_seen": "2024-06-30",
        "trend": "stable",
        "status": "new"
      }
    }
  ],
  "total": 181,
  "returned": 50,
  "filters_applied": {}
}

Response fields like finding_type contain machine-readable identifiers. Use statements.de / statements.en for human-readable display. constellation names the affected dimension values; dimensions lists which dimensions define the finding.

#### Get Finding Detail

GET /api/v1/runs/{run_id}/findings/{finding_id}

Returns full details for a single finding including metrics, affected tickets, and trend data.

The response also carries type_explanation — a static, consumer-facing explanation of the finding type with four fields: what_de / what_en (what this finding type measures) and how_to_read_de / how_to_read_en (lead metric, reference baseline, unit). It never varies per run; the run-specific statement is the finding's kernaussage. null for types without an explanation — hide the block in that case.

#### Get Finding Time Series

GET /api/v1/findings/{finding_id}/timeseries

Returns weekly time series data for a finding (affected tickets per ISO week), useful for sparklines and trend visualization.

Parameters:

Response:

{
  "finding_id": "uuid",
  "run_id": "uuid",
  "as_of": "2026-01-03T15:05:42Z",
  "view": "last_52_weeks",
  "bucket": "week",
  "tz": "UTC",
  "points": [
    {
      "bucket_start": "2025-01-06T00:00:00Z",
      "bucket_end": "2025-01-13T00:00:00Z",
      "new_affected_count": 3,
      "cumulative_affected_count": 12
    }
  ]
}

#### Get Affected Tickets

GET /api/v1/findings/{finding_id}/tickets

Returns sample ticket IDs affected by this finding.

Parameters:

Response:

{
  "finding_id": "uuid",
  "finding_type": "F7_PING_PONG",
  "finding_type_label": "Ping-Pong-Effekt",
  "finding_type_label_en": "Ping-pong effect",
  "tickets": [
    {
      "ticket_id": "INC-2024-0042",
      "ticket_id_hash": "5e68376293bc",
      "role": "1st Level Support",
      "dwell_hours": 76.6,
      "effective_dwell_hours": 76.6,
      "assigned_at": "2025-12-05T11:09:23",
      "outcome": "handover",
      "category": "Identity/Access",
      "location": "Berlin"
    }
  ],
  "total_count": 234,
  "returned_count": 20
}

Situations

#### List Situations

GET /api/v1/runs/{run_id}/situations

Returns situations (grouped findings) for a run.

Parameters:

Response:

{
  "situations": [
    {
      "id": "sit-uuid",
      "title": "Level-1-Support: Kapazitätsengpass",
      "situation_type": "capacity_bottleneck",
      "anchor_role": "Level-1-Support",
      "impact_hours": 342.5,
      "finding_count": 4,
      "trend": "worsening",
      "status": "new",
      "has_narrative": true
    }
  ],
  "total": 12,
  "run_id": "uuid"
}

#### Get Situation Detail

GET /api/v1/situations/{situation_id}

Returns full situation details including member findings, delegations, and learnings.

**Concentration block (konzentration, optional):** where a situation is

concentrated across a hidden dimension. Present only when the situation has a

measurable concentration point; absent otherwise (no placeholder).

{
  "konzentration": {
    "titel_de": "Konzentration",
    "achse": "location",
    "achse_label_de": "Standorte",
    "zeile_pointe_de": "Bei IMS Operations konzentriert sich die Bearbeitungsverzögerung auf 6 von 32 geprüften Standorten (81 % der abgeschlossenen Durchläufe geprüft).",
    "zeile_kontrast_de": "Am stärksten: Karlsruhe (3,9×) · Metzingen (2,2×).",
    "zeile_entlastung_de": "26 Standorte mit 1.588 Tickets liegen im Normalband; 96 weitere sind mit unter 20 Tickets nicht bewertbar.",
    "k_auffaellig": 6,
    "n_geprueft": 32,
    "n_im_band": 26,
    "tickets_im_band": 1588,
    "n_nicht_bewertbar": 96,
    "ticket_deckung_geprueft": 0.812,
    "deckung_ok": true,
    "top_werte": [
      {"wert": "Karlsruhe", "faktor": 3.87, "faktor_deckel": false, "faktor_label_de": "3,9×", "tier": "critical"}
    ]
  }
}

Field notes:

population show a critical or notable finding, out of those with enough

volume to be assessed (at least 20 tickets). k is always a subset of n.

the normal band. Values below the volume threshold are never counted here;

they are reported separately as n_nicht_bewertbar.

assessed values. Below 0.75 the relief sentence is omitted (deckung_ok

is false), while the concentration statement itself remains.

the value has no measurable time-based finding: it still counts towards k

but is rendered without a number. faktor_deckel marks display capping.

fields carry the same values for your own formatting.

**Origin block (herkunft, optional):** where the waiting time accumulating

at the situation's anchor role comes from. Decomposes the role's handover

waiting time across its inbound edges and reports predecessor roles whose

share of the waiting time is disproportionate to their share of handed-over

tickets. Present only when at least one inbound edge is disproportionate;

absent otherwise (no placeholder). The same block is served on the evidence

poster endpoint with identical values.

{
  "herkunft": {
    "titel_de": "Herkunft",
    "untertitel_de": "Übergaben",
    "anker_rolle": "IMS Finance",
    "zeile_pointe_de": "Bei IMS Finance trägt die Übergabe von WMD REB Support das 5,0-Fache ihres Ticket-Anteils an Wartezeit (4 % der übergebenen Tickets, 19 % der Übergabe-Wartezeit; Gesamtzeitraum der abgeschlossenen Durchläufe).",
    "zeile_hauptzulieferer_de": "Der Hauptzulieferer IT Comline liefert 88 % der übergebenen Tickets und trägt 49 % der Übergabe-Wartezeit (unauffällig).",
    "zeile_erstkontakt_de": null,
    "signal_kanten": [
      {"vorgaenger": "WMD REB Support", "tickets": 48, "ticket_anteil": 0.0382, "wartezeit_anteil": 0.1922, "faktor": 5.04, "faktor_deckel": false}
    ],
    "kanten_im_satz": 1,
    "hauptzulieferer": {"vorgaenger": "IT Comline", "tickets": 1113, "ticket_anteil": 0.8847, "wartezeit_anteil": 0.4912, "faktor": 0.56},
    "erstkontakt_wartezeit_anteil": 0.2377,
    "uebergabe_wartezeit_anteil": 0.7623
  }
}

Field notes:

their ticket share (with at least 10 distinct tickets and at least 10 % of

the handover waiting time). Sorted by faktor descending; the rendered

sentence names at most the first kanten_im_satz of them.

on the anchor role's completed handed-over passes over the full data range.

faktor_deckel marks display capping ("mehr als das 20-Fache").

rendered sentence appears only when this edge itself is inconspicuous.

that arises without any handover (first contact) and is therefore not part

of the decomposition. Rendered as a separate honesty line from 0.25 upward.

fields carry the same values for your own formatting.

(statement.owner_question_slot) additionally carries herkunft_frage_de,

a clarification question addressed to both sides of the strongest edge.

#### Get Situation Narrative

GET /api/v1/situations/{situation_id}/narrative

Returns the AI-generated narrative for a situation — a plain-language explanation with context and recommended actions.

Response:

{
  "id": "uuid",
  "situation_id": "sit-uuid",
  "language": "de",
  "headline": "Level-1-Support: Kapazitätsengpass mit steigender Tendenz",
  "body": "Der Level-1-Support zeigt seit 8 Wochen eine kontinuierlich steigende Verweildauer...",
  "next_actions": [
    "Routing-Regeln für Kategorie 'Passwort-Reset' prüfen",
    "Kapazitätsplanung für KW 15-20 anpassen"
  ],
  "status": "completed",
  "generated_at": "2026-03-01T12:00:00Z"
}

#### Get Situation Headline Phrasings

GET /api/v1/situations/{situation_id}/leitzahl

Returns every available phrasing of a situation's headline figure. Each phrasing

carries three parts: a compact wert_text for the tile, a short label_de

naming the measure and window, and a full satz_de for surfaces with room.

Also returns the concentration curve (which share of cases carries which share

of the delay) and the time share per case.

All values derive from the same per-case list that produces the situation's

12-week magnitude, so switching the phrasing never changes the number. The share

uses the same 12-week window as the numerator.

Parameters:

Response:

{
  "situation_id": "sit-uuid",
  "leitzahl": {
    "variante": "anteil",
    "wert_text": "88 %",
    "label_de": "der gebundenen Verzögerungszeit (12 Wochen)",
    "satz_de": "Diese Situation bindet 88 % der gesamten Verzögerungszeit der letzten zwölf Wochen.",
    "n_vorgaenge": 311,
    "stunden_gesamt": 146447.9,
    "euro_gesamt": 7322397,
    "anteil_am_lauf": 0.8846,
    "median_stunden": 122.0,
    "mittelwert_stunden": 470.9,
    "kurve": [
      {"vorgangs_anteil": 0.1, "n_vorgaenge": 31, "zeit_anteil": 0.491, "stunden": 71852.0}
    ],
    "zeit_anteil_je_vorgang": [
      {"vorgang": "ad27acedaa95", "vorgang_nummer": "TCK00030663", "stunden": 3534.0, "zeit_anteil": 0.0241}
    ],
    "varianten": {
      "anteil": {"wert_text": "88 %", "label_de": "der gebundenen Verzögerungszeit (12 Wochen)", "satz_de": "..."},
      "euro": {"wert_text": "7,3 Mio €", "label_de": "Verzögerungskosten (12 Wochen)", "satz_de": "..."},
      "stunden": {"wert_text": "146 Tsd h", "label_de": "über der Norm, 311 Vorgänge (12 Wochen)", "satz_de": "..."},
      "typisch": {"wert_text": "5,1 Tage", "label_de": "über der Norm je Vorgang, typisch (12 Wochen)", "satz_de": "..."},
      "konzentration": {"wert_text": "49 %", "label_de": "der Zeit aus 10 % der Vorgänge (31 von 311)", "satz_de": "..."}
    }
  }
}

The anteil phrasing is absent when no denominator is available — no invented

percentage.

leitzahl is null when the situation has no evidence inside the 12-week

window — an honest empty case rather than a zero sentence.

Triage Queue

GET /api/v1/runs/{run_id}/situations-queue

Returns the prioritized triage queue combining situations and ungrouped findings.

Parameters:

Delegations

#### Delegate Situation

POST /api/v1/situations/{situation_id}/delegate

Assigns responsibility for a situation to a team member via email. The recipient receives a magic-link email with context and guiding questions — no login required.

Request Body:

{
  "email": "[email protected]",
  "name": "Max Mustermann",
  "message": "Bitte prüfe die Routing-Regeln für Passwort-Reset Tickets.",
  "due_date": "2026-03-15"
}

Response (201):

{
  "delegation_id": "uuid",
  "status": "sent",
  "feedback_url": "https://app.dkyra.com/feedback/abc123"
}

#### List Delegations

GET /api/v1/delegations

Returns all delegations for the current tenant with status tracking.

System Health

#### Get Health Score

GET /api/v1/system-flow/health-score

Returns the overall system health score for a run.

Parameters:

Response:

{
  "score": 62,
  "grade": "C",
  "components": {
    "flow_balance": 55,
    "stock_trend": 70,
    "capacity_balance": 48,
    "throughput_trend": 75
  },
  "worst_roles": ["Level-1-Support", "Incident-Management"],
  "improving_roles": ["Change-Management"]
}

#### Get Role Assessments

GET /api/v1/role-assessments

Returns pre-computed per-role health assessments for a run.

Parameters:

#### Get Role Field

GET /api/v1/runs/{run_id}/role-field

Returns every role of a run as one point: number of intervals, dwell

distribution (p25/p50/p75/p90), concentration of waiting time, neighbouring

roles above a handover threshold, and the finding profile of that role.

Requires a Pro subscription.

The dwell basis switches the axis, the distribution and the concentration. It

does not change the finding counts: each detector measures on its own clock.

run_at is when the analysis ran, as an ISO-8601 timestamp with an explicit UTC

offset; run_at_source says whether that is the completion (finished) or the

start (created) of the run. Both are null if the run carries neither.

observation is the span the underlying data covers and ends earlier. Its two

timestamps are wall-clock values taken from the source data and carry no zone —

display them as they are, do not convert them. Only run_at is a machine

timestamp and therefore zone-aware.

Parameters:

Billing & Credits

#### Get AI Credits Status

GET /api/v1/billing/ai-credits

Returns remaining AI analysis credits and current-period usage for the current tenant.

Response:

{
  "tenant_id": "uuid",
  "tier": "pro",
  "credits_total": 100,
  "credits_included": 80,
  "credits_purchased": 20,
  "warning_level": "ok",
  "runs_remaining": 77,
  "runs_used": 23,
  "runs_limit": 100,
  "enrichment_cost_eur_today": 0.42,
  "enrichment_tokens_today": 12500,
  "enrichment_count_today": 3,
  "period_start": "2026-06-01T00:00:00Z",
  "period_end": "2026-07-01T00:00:00Z"
}

Connectors

Process Radar supports direct ITSM integrations for automated data import.

#### List Available Connector Types

GET /api/v1/connector-types

Returns available connector types (e.g., Matrix42, Jira Service Management).

#### Create Connector

POST /api/v1/connectors

Creates a new ITSM connector for automated data synchronization.

#### Test Connection

POST /api/v1/connectors/{connector_id}/test

Tests connectivity to the ITSM system without importing data.

#### Start Sync

POST /api/v1/connectors/{connector_id}/sync

Triggers a data synchronization from the connected ITSM system. Only a full

synchronization is supported ("sync_type": "full"); every sync re-imports the

complete ticket history to guarantee no data is lost.

Authentication

#### Login

POST /api/v1/auth/login

Request Body:

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 300,
  "user": {
    "user_id": "uuid",
    "email": "[email protected]",
    "role": "owner"
  }
}

#### Refresh Token

POST /api/v1/auth/refresh

Refreshes an expired access token using the refresh token.

#### Current User

GET /api/v1/auth/me

Returns the current authenticated user and tenant information.

AI Integration

Process Radar is built for programmatic and AI-agent consumption. All endpoints return structured JSON with consistent schemas.

Recommended Workflows for AI Agents

Morning Briefing:

Continuous Monitoring:

Deep Dive:

Delegation Automation:

What Process Radar Detects

Process Radar detects various types of anomalies including:

Each finding includes a human-readable label and a severity classification (critical, notable, observed).

Response Conventions

Error Handling

All errors follow RFC 7807 Problem Details format:

{
  "type": "https://dkradar/errors/NOT_FOUND",
  "title": "Not Found",
  "status": 404,
  "detail": "Run not found",
  "instance": "/api/v1/runs/unknown-id",
  "code": "NOT_FOUND",
  "trace_id": "e29f788f-ffbc-4686-be22-4a8e6d422997"
}

Validation errors (422) additionally carry a field-level errors list:

{
  "type": "https://dkradar/errors/VALIDATION_ERROR",
  "title": "Validation Error",
  "status": 422,
  "detail": "Validation error",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "loc": ["query", "run_id"], "msg": "Field required", "type": "missing" }
  ]
}

Common Status Codes:

Rate Limits

Standard: 200 requests/minute per client. Summary endpoints are cached for 5 minutes.

Higher limits available on Enterprise plans.

Integration Examples

Python

import requests

API_KEY = "your-api-key"
BASE = "https://api.dkyra.com/api/v1"
headers = {"X-API-Key": API_KEY}

# Get executive summary
summary = requests.get(f"{BASE}/executive-summary", headers=headers).json()
print(f"Health: {summary['health_score']['grade']}")
for sit in summary["priority_situations"]:
    print(f"  [{sit['tier']}] {sit['headline']} ({sit['impact_hours']}h)")

JavaScript

const API_KEY = "your-api-key";
const BASE = "https://api.dkyra.com/api/v1";

const res = await fetch(`${BASE}/executive-summary`, {
  headers: { "X-API-Key": API_KEY }
});
const summary = await res.json();
console.log(`Health: ${summary.health_score.grade}`);

cURL

curl -H "X-API-Key: YOUR_KEY" https://api.dkyra.com/api/v1/executive-summary

Supported ITSM Systems

Support