Process Radar API Documentation
API Version: 1.0.0
Base URL: https://api.dkyra.com/api/v1Authentication: 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
| Concept | Description |
|---|---|
| Finding | An automatically detected anomaly in your ITSM workflows, for example a team with unusually long processing times, a routing loop between departments, or a seasonal capacity problem |
| Affected Dimensions | The business context of a finding: which team, category, location, or combination is affected |
| Tier | Severity classification: critical, notable, observed |
| Trend | Development over time: improving, worsening, stable, new |
| Confidence | Robustness assessment (low, medium, high) based on data volume and how stable the result is |
| Situation | A group of related findings that together describe a business-relevant problem requiring action, such as "Level-1 Support is overwhelmed" instead of 12 separate symptoms |
| Health Score | An A-through-F grade summarizing overall process health, combining throughput, bottleneck risk, and trend indicators |
| Delegation | Assignment of responsibility with feedback loop via magic-link email. Recipients need no login |
| Narrative | AI-generated explanation of a situation in plain language with recommended actions |
| Statement | Human-readable description of the finding, available in German and English |
Authentication
All API requests require authentication via one of:
API Key (Header)
X-API-Key: your-api-keyJWT Bearer Token
Authorization: Bearer your-jwt-tokenObtaining 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.
Roles
Workspace members have one of four roles: owner, admin, member, viewer. Viewers can read and download everything their workspace can see, but cannot change workspace data (status changes, assessments, delegations, analysis runs, uploads). Such requests return 403 with "code": "READ_ONLY_ROLE". API keys have the rights of a member.
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 /healthReturns API status. No authentication required.
Response:
{
"status": "ok"
}Datasets & Upload
#### List Datasets
GET /api/v1/datasetsReturns the datasets for the current tenant, including run counts. The dataset
that uploads and syncs write into comes first: the one with the most recent
successful analysis run (datasets without one follow, newest first). Retired
datasets are not listed; they stay readable via GET /api/v1/datasets/{dataset_id}
and their runs stay readable, but no new analysis can be started on them.
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/uploadUploads CSV files into the tenant's dataset in one step. Uses multipart/form-data.
A tenant has one dataset: the first upload creates it, every further upload
extends it and does not replace earlier data.
time, regardless of format) are skipped; all other rows are appended.
equivalent column names (e.g. Ticket / TicketNumber) may differ; missing or
additional columns reject the upload with 400, naming the columns, and the
dataset stays unchanged.
YYYY-MM-DD HH:MM:SS. - gruen: no finding; the upload is taken over immediately (200, status: "UPLOADED").
- gelb: notes that need a decision; nothing is taken over yet (200,
status: "PENDING_REVIEW"). Confirm or discard it with the two endpoints below
within 24 hours.
- rot: nothing is taken over (400); detail holds one sentence per finding,
pruefung.befunde the structured list.
- angenommen_mit_befund: the first upload of a tenant (no data yet) with a
rot finding is taken over anyway (200, status: "UPLOADED"). meldung tells
the customer that we look at the data and get in touch; each finding also carries
kunde, the same finding in plain words. lauf_gesperrt is true when an
analysis on this data would certainly fail; starting a run then returns 409
until a later upload without such a finding replaces the data. Once a dataset
holds data that can be analysed, rot is rejected as above.
latest three are kept); validation.sicherung names it.
Form Fields:
| Name | Type | Description |
|---|---|---|
tickets_file | file | Tickets.csv (semicolon-separated) |
history_file | file | TicketHistory.csv (semicolon-separated) |
name | string | Dataset name (default: "Neue Analyse") |
Response (200):
{
"dataset_id": "uuid",
"status": "UPLOADED",
"validation": {
"ok": true,
"ticket_count": 1800,
"event_count": 52000,
"warnings": [],
"merged": true,
"delivery": { "ticket_count": 400, "event_count": 9000 },
"dataset": { "ticket_count": 1800, "event_count": 52000 }
}
}| Field | Meaning |
|---|---|
validation.delivery | Counts in the uploaded files |
validation.dataset | Counts in the dataset after the upload |
validation.ticket_count / event_count | Same as validation.dataset |
validation.merged | true if the upload was merged into existing data |
validation.warnings | Includes a notice if the dataset's earlier raw data was missing; the upload is then taken as a first upload |
validation.pruefung | Check result: ergebnis (gruen/gelb/rot/angenommen_mit_befund), meldung, befunde (each with stufe, kategorie, satz; with angenommen_mit_befund also kunde), and for angenommen_mit_befund also stufe_pruefung (rot), lauf_gesperrt and hinweis_lauf |
|---|---|
validation.ausstehend | Only for gelb: token and gueltig_bis of the waiting upload |
validation.sicherung | Backup of the previous state (null on the first upload) |
| Status | Meaning |
|---|---|
| 200 | Uploaded (status: "UPLOADED", also for angenommen_mit_befund) or waiting for confirmation (status: "PENDING_REVIEW") |
| 400 | Rejected by the check (pruefung.ergebnis: "rot"), or not a CSV file; the dataset is unchanged |
| 413 | File larger than 100 MB |
#### Confirm or Discard a Waiting Upload
POST /api/v1/datasets/{dataset_id}/lieferung/{token}/uebernehmenPOST /api/v1/datasets/{dataset_id}/lieferung/{token}/verwerfenuebernehmen takes over an upload that is waiting after a gelb check; the response
has the same form as the upload response with status: "UPLOADED". If the dataset
changed since the check, the upload is checked again first: 409 with the new
pruefung (confirm again), or 400 if it is now rot. verwerfen discards it;
nothing is written.
| Status | Meaning |
|---|---|
| 200 | Taken over / discarded |
| 400 | Rejected after a new check; nothing is written |
| 404 | No waiting upload under this token for your dataset |
| 409 | Checked again with a new result; confirm again |
| 410 | Waited longer than 24 hours and was discarded; upload again |
#### Delete Dataset
DELETE /api/v1/datasets/{dataset_id}?confirm=trueDeletes a dataset and ALL associated data. Requires confirm=true as safety guard.
| Status | Meaning |
|---|---|
| 204 | Successfully deleted |
| 400 | Missing confirm=true parameter |
| 404 | Dataset not found |
| 409 | Cannot delete: active run in progress |
Analysis Runs
#### Start Analysis Run
POST /api/v1/datasets/{dataset_id}/runsStarts 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"
}| Status | Meaning |
|---|---|
| 202 | Analysis started |
| 402 | Not enough credits |
| 403 | Plan limit for datasets exceeded (retired datasets do not count) |
| 409 | The dataset is retired; start the analysis on the current dataset |
| 409 | The first upload has findings on which the analysis would certainly fail (lauf_gesperrt); detail says so. A later upload without such a finding lifts this |
#### List Runs
GET /api/v1/runsReturns all runs for the current tenant.
Parameters:
| Name | Type | Description |
|---|---|---|
dataset_id | query | Filter by dataset |
status | query | Filter: QUEUED, RUNNING, SUCCEEDED, FAILED |
limit | query | Max results (default: 50) |
offset | query | Pagination offset |
#### 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-summaryHigh-level briefing with system health, prioritized situations, and trend information.
Parameters:
| Name | Type | Description |
|---|---|---|
dataset_id | query | Dataset ID (uses first dataset if omitted) |
limit | query | Max priority situations, 1-10 (default: 5) |
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",
"trend_grund": "mehr_tickets",
"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-summaryAggregated 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-healthSystem-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}/findingsReturns all detected anomalies for an analysis run with filtering and sorting.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run identifier |
tier | query | Filter: critical, notable, observed |
finding_type | query | Filter by finding type identifier |
role | query | Filter by affected role |
category | query | Filter by affected category |
location | query | Filter by affected location |
min_impact | query | Minimum impact in hours |
ticket_status | query | Filter: closed (default), open, all |
workflow_status | query | Filter: active (default), new, delegate, watching, ignore, escalated, all |
sort_by | query | Sort: relevance_score (default), impact_hours, tier |
sort_order | query | Direction: asc or desc |
limit | query | Max results (default: 50, max: 500) |
offset | query | Pagination offset |
Response:
{
"findings": [
{
"finding_id": "cbf7fec4-f9a2-...",
"finding_type": "<type id>",
"tier": "critical",
"dimensions": ["role"],
"constellation": {
"role": "2nd Level Support"
},
"statements": {
"de": "Die Rolle '2nd Level Support' braucht für dieselbe Arbeit deutlich länger als üblich (89,4 h, üblich 12,0 h). Robustheit: Hoch (234 Tickets).",
"en": "Role '2nd Level Support' takes clearly longer than usual for the same work (89.4h, usually 12.0h). 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": {}
}Each finding also carries type_explanation, the same static explanation of the finding type that the detail endpoint returns (what_de / what_en, how_to_read_de / how_to_read_en; null for types without an explanation).
Response fields likefinding_typecontain machine-readable identifiers. Usestatements.de/statements.enfor human-readable display.constellationnames the affected dimension values;dimensionslists 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}/timeseriesReturns weekly time series data for a finding (affected tickets per ISO week), useful for sparklines and trend visualization.
Parameters:
| Name | Type | Description |
|---|---|---|
finding_id | path | Finding identifier |
run_id | query | Required. Analysis run identifier |
view | query | last_52_weeks (default) or full_history |
as_of | query | Time anchor (ISO-8601 UTC; default: latest event in the run) |
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}/ticketsReturns the tickets behind this finding, longest dwell time first, one page at a time. total_count is the number of all tickets behind the finding, not of the returned page; sorted_by names the order (dwell_hours_desc, or null when the source has no defined order).
Parameters:
| Name | Type | Description |
|---|---|---|
finding_id | path | Finding identifier |
run_id | query | Required. Analysis run identifier |
limit | query | Page size, 1 to 100 (default 20) |
offset | query | Tickets to skip (default 0) |
Response:
{
"finding_id": "uuid",
"finding_type": "<type id>",
"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,
"sorted_by": "dwell_hours_desc"
}Situations
On a situation, trend is the direction: worsening, improving, stable or no_data (no series available). trend_grund is the reason for a direction: mehr_tickets (more tickets), weniger_tickets (fewer tickets), dauert_laenger (takes longer) or geht_schneller (gets faster); it is empty for stable and no_data. Together they form one statement, for example "Wird schlechter · mehr Tickets". The same pair appears on findings as trend_richtung and trend_grund. trend_percent is kept for compatibility and is not a statement.
#### List Situations
GET /api/v1/runs/{run_id}/situationsReturns situations (grouped findings) for a run.
Parameters:
| Name | Type | Description |
|---|---|---|
status | query | Filter: new, delegate, watching, ignore, escalated |
tier | query | Filter: critical, notable, observed |
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.
**Short summary (kurzfassung, nullable):** a few finished sentences that
describe the situation. saetze lists them in reading order, form is thema
or zeit, stand names the version of the rules they were written under.
The value is null when no checked summary exists for the situation in this run.
{"kurzfassung": {"saetze": ["248 Stunden statt 9 liegen die Tickets in Security.", "Das betrifft 7 Befunde."], "form": "thema", "stand": "S7s"}}**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:
k_auffaellig / n_geprueft: how many values of the anchor role'spopulation 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.
n_im_band / tickets_im_band: values that were assessed and stay withinthe normal band. Values below the volume threshold are never counted here;
they are reported separately as n_nicht_bewertbar.
ticket_deckung_geprueft: share of completed role passes covered by the assessed values. Below 0.75 the relief sentence is omitted (deckung_ok
is false), while the concentration statement itself remains.
top_werte[].faktor: deviation factor of the strongest values. null means the value has no measurable time-based finding: it still counts towards k
but is rendered without a number. faktor_deckel marks display capping.
zeile_*_de fields are the rendered German sentences; the numericfields 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 names the predecessor role that a
statistically confirmed origin finding of this situation points to, together
with that edge's share of tickets and of waiting time. Present only when the
situation carries such a confirmed finding and the decomposition covers its
edge; absent otherwise (no placeholder). The same block is served on the
evidence poster endpoint with identical values. If the named edge's factor is
below 1.0, zeile_pointe_de names the origin without stating a multiple.
{
"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:
signal_kanten: exactly one entry, the inbound edge named by the confirmedorigin finding. It is the edge the rendered sentence names
(kanten_im_satz is 1). Its faktor can be below 2; the sentence then
states it as it is.
faktor: waiting-time share divided by ticket share of the edge, computedon the anchor role's completed handed-over passes over the full data range.
faktor_deckel marks display capping ("mehr als das 20-Fache").
hauptzulieferer: the edge delivering the most tickets, as contrast. The rendered sentence appears only when this edge is inconspicuous (faktor
below 2) and is not itself the named edge.
erstkontakt_wartezeit_anteil: share of the role's total waiting timethat arises without any handover (first contact) and is therefore not part
of the decomposition. Rendered as a separate honesty line from 0.25 upward.
zeile_*_de fields are the rendered German sentences; the numericfields 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 named edge.
#### Get Situation Narrative
GET /api/v1/situations/{situation_id}/narrativeReturns 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}/leitzahlReturns 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:
| Name | Type | Description |
|---|---|---|
variante | query | Override the leading phrasing for comparison (optional) |
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 percentage is invented.
leitzahl is null when the situation has no evidence inside the 12-week
window. That is an honest empty case rather than a zero sentence.
Triage Queue
GET /api/v1/runs/{run_id}/situations-queueReturns the prioritized triage queue combining situations and ungrouped findings.
Parameters:
| Name | Type | Description |
|---|---|---|
tier | query | Filter by severity |
status | query | Filter by workflow status |
limit | query | Max items (default: 20) |
gruppiert | query | One row per subject (default: true). false returns every situation as its own row |
With gruppiert=true, total and limit count rows. A subject with several situations appears as its lead situation, with its numbers unchanged, plus zeile and sprossen. zeile.ticket_count counts each ticket once across all of them, zeile.ticket_count_basis says how well evidence covers that count, and zeile.zaehlung counts situations per kind. Hours are never added up across situations. Each entry in sprossen is a full item, and delegation stays on the single situation. A situation that is alone on its subject carries neither field.
Each situation item carries kurzfassung (saetze, form, stand) or null, the same value as on the situation detail. The leader view of GET /api/v1/runs/{run_id}/triage-queue (perspective=leader) carries the same field on each situation item.
Delegations
#### Delegate Situation
POST /api/v1/situations/{situation_id}/delegateAssigns responsibility for a situation to a team member via email. The recipient receives a magic-link email with context and guiding questions. Recipients need no login, but the link alone does not open the reply page: the recipient first requests a 6-digit code (POST /api/v1/feedback/{token}/code), which is sent to the address the delegation went to, and confirms it (POST /api/v1/feedback/{token}/code/pruefen). The confirmation returns a session key (valid for 2 hours, bound to that one delegation) that must be sent in the X-Antwort-Sitzung header to read (GET) and answer (POST) at /api/v1/feedback/{token}. Five wrong codes lock the code; at most 3 codes can be requested per hour and link.
Set gemeinsames_postfach: true when the address is a shared mailbox (it is also set automatically when the address matches a pool address of the workspace); the reply page then tells the recipient that everyone reading that mailbox can open it. Delegating to your own address returns 400.
A hand-over ends the monitoring of the same entry (set aside to monitor) and marks the entry as handed over, unless the entry was set aside more recently than the hand-over was taken; in that case the hand-over still goes out and the monitoring stays. Cancelling a hand-over (PATCH /api/v1/delegations/{delegation_id}/status) sets a handed-over entry back to new only if no other open hand-over of the entry remains.
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"
}Sync mode (offline actions): a body that carries ausgefuehrt_am (ISO 8601 with offset, for example 2026-11-12T21:04:05.123+01:00) is a queued offline action. It also needs the headers Idempotency-Key (one UUID per action), X-Geraet-Jetzt (the device clock at send time, ISO 8601 with offset) and X-Erwarteter-Mandant (the workspace the device believes it writes to). The answer is 200 with ergebnis (angewendet, schon_so, ueberholt, nicht_mehr_im_lauf, lauf_laeuft), a satz for every outcome except angewendet, the plain result under delegation and text_quelle (ki or vorlage). The entry is found by its own id in the current run (nicht_mehr_im_lauf when it is gone or belongs to an older run, lauf_laeuft while a run is in progress or broke off; neither sends anything). If the workspace shows AI texts and the entry has none yet, the server writes one in the same call; when that fails or takes longer than 30 seconds the template text is sent and text_quelle is vorlage. A sync request never returns the 409 about a missing text. Errors carry a code: SCHON_AN_DIESEN_EMPFAENGER (409, with an and am), IN_ARBEIT (409: the same Idempotency-Key is still being processed), SCHLUESSEL_ANDERER_INHALT (422: the key was first used for a different request), ZUGANG_ENTZOGEN (403), SYNC_KOPF_UNGUELTIG (400: a header or timestamp is missing, or the timestamp has no offset). A repeated key returns the stored answer without running the action again; a key is valid only for the user and workspace that sent it. SYNC_NICHT_UNTERSTUETZT (501) is returned only for a kind of request that has no sync mode. Without ausgefuehrt_am the endpoint behaves as described above.
One open hand-over per entry and person (both modes): if the same address (capitalisation and surrounding blanks ignored) already holds an open hand-over of the same entry, the call returns 409 with code SCHON_AN_DIESEN_EMPFAENGER, an (the name, else the address), am (when it was sent, ISO 8601 UTC) and the sentence to show in detail, for example Schon an Max weitergegeben am 12.11.2026.. Nothing is written and no message is sent. A different address is accepted, and so is the same address once the earlier hand-over failed, was cancelled, answered, declined or ran out. A hand-over that has had no reaction for 14 days after sending moves to expired (shown as ausgelaufen); it stays in the lists, and a late answer through its link is still accepted.
#### List Delegations
GET /api/v1/delegationsReturns all delegations for the current tenant with status tracking. feedback_url is returned only to the user who sent the delegation; for everyone else, and for API keys, it is null.
System Health
#### Get Health Score
GET /api/v1/system-flow/health-scoreReturns the overall system health score for a run.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | query | Analysis run ID |
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-assessmentsReturns pre-computed per-role health assessments for a run.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | query | Analysis run ID |
severity | query | Filter: critical, notable, observed |
#### Get Role Field
GET /api/v1/runs/{run_id}/role-fieldReturns 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.
Each listed finding carries menge_zahl and menge_wort: the count the finding
refers to and the unit of that count. For most findings this is the number of
affected tickets. ticket_count is kept as a sorting value and can be larger,
for example where a finding reports a rate over a wider base.
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:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
dwell | query | Dwell basis: raw (default) or business |
min_edge | query | Minimum handovers for an edge to be listed (default 15) |
#### Get Contrasts
GET /api/v1/runs/{run_id}/kontrasteReturns the comparisons of a run: inside the area that carries most of the
working time, which groups take markedly longer than is usual there. Everything
the briefing page draws comes from this one call; the client computes nothing.
Each comparison carries both numbers side by side: the added hours and how many
times longer, plus the usual duration they are measured against, so a reader can
redo the arithmetic. Added hours can be negative, and the multiple is null when
the usual duration is too close to zero for a ratio to mean anything. Both are
returned as they are, never clipped or dropped.
geschwiegen lists what the run could not say anything about, and why.
befund is the verdict for the data space as a whole and separates "nothing
stands out" from "nothing can be measured here". Both are null when the run
never computed them. That is a third state, not an empty result.
Percentiles are given per group and are absent for groups below the minimum size
or beyond the cap; the cap travels with the response, so a reader can tell a
complete list from a trimmed one.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
sortierung | query | Order: zusatzzeit (added hours, default) or faktor |
#### Get Evidence For The Leading Comparison
GET /api/v1/runs/{run_id}/briefing-belegeReturns what the leading comparison is made of: the individual durations behind
it, and what the longest cases have in common. Three statements in this order:
how strongly the time clusters, which attribute the clustered cases share, and
who that attribute belongs to.
Drivers are only reported among cases built the same way, that is, sections that
ended by being resolved. Without that restriction the result would describe how
the data is constructed rather than what happened: a section that ends in a
handover is cut short by definition and can never grow long.
A driver that never occurs outside the top tenth carries no multiple at all.
hebel is null and the sentence says "all N cases of this kind are up here"
instead. A ratio without a denominator is not a large number, it is no number.
punkte carries every case of the stated population. When there are too many to
draw, the response says so in punkte_info: all top-tenth cases plus every
n-th of the rest, with schritt naming n. A silent sample never happens.
grund is set, and everything else empty, when the method has nothing to say:
too few cases to search, or the dimension missing from the run's artefact. That
is an answer, not an error, and it arrives with 200.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
#### List The Cases Behind An Evidence Driver
GET /api/v1/runs/{run_id}/briefing-belege/faelle?merkmal=location&wert=VeltenReturns the individual cases behind one driver named in briefing-belege: the
sections of the heaviest tenth that carry the given attribute value, longest
first, with ticket, duration in hours, the role that held the section, and the
time it started.
The list is filtered on attribute and value together. A value alone would also
match other attributes that happen to use the same word. Its length equals the
driver's faelle_oben in briefing-belege; if the list cannot be built from
exactly the population the evidence cloud uses, it comes back empty and grund
says why. That is an answer, not an error, and it arrives with 200.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
merkmal | query | Attribute of the driver, as named in briefing-belege |
wert | query | Value of that attribute |
#### Get Stellen
GET /api/v1/runs/{run_id}/stellenReturns every stelle of a run exactly once, grouped by one attribute. A stelle is one value of the
chosen attribute: one role, one category, one location, one origin, or one organisational unit. Each stelle carries a cell
per finding column with its own count; columns are never summed or ranked against each other,
since they measure in different units.
Stellen already named on the leading briefing page come first (largest share of lost time first),
then the rest, each group ordered by finding count. im_briefing marks that on each stelle;
groesster_anteil marks the single stelle that carries the run.
Each finding entry lists its further attributes in weitere_merkmale (merkmal, wort, wert).
Besides the stelle attributes it can carry gegenrolle ("Gegenrolle"): the other role of a
role pair, for findings about hand-backs between two roles. It is never an attribute you can group
by; it only names the second side of that finding. Findings without a role pair carry none.
Each finding entry carries a plain-language label (type_label_de) and headline
(kernaussage_short) instead of the internal type code; both are null when the label registry
has none for that type. A finding whose type maps to no column still counts toward the stelle's
total, listed under deckung.ohne_spalte by its type. Situations are listed per stelle in order of
twelve-week impact; the client resolves their display label from the situation list it already has.
The response also carries aussage: statements about the whole attribute, one row per comparison
group (for example "within role X, locations differ from A to B"). Each row names its comparison
group, its range, two counts and its slow and fast end; kennung identifies the comparison it rose
from. im_briefing marks the one row the briefing page shows as its typical case; that row is
listed first. wiederholte_enden lists each value that is the slow end in at least two rows,
counted separately per kind of comparison group (als_langsames_ende of zeilen). These counts are
never added across kinds: groups of different kinds can hold the same tickets. When no row exists,
grund says why: for role, because a role is always the comparison group, never the attribute
that is compared. ou (organisational unit) is accepted as attribute; findings carry no
organisational unit, so its grid stays empty, raster_grund says so, and aussage carries its rows.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
merkmal | query | Attribute: role (default), category, location, predecessor_role, or ou |
Response:
{
"run_id": "uuid",
"merkmal": "role",
"merkmal_wort": "Rolle",
"spalten": [
{ "id": "laenger", "titel": "Dauert länger", "sortierung": "Wievielfaches des Üblichen" }
],
"stellen": [
{
"merkmal": "role",
"wert": "IMS Operations",
"im_briefing": true,
"groesster_anteil": true,
"befunde": 20,
"situationen": [
{ "id": "uuid", "title": "IMS Operations: Kapazitätsengpass", "impact_hours_12w": 66835.0, "ticket_count": 4622, "finding_count": 37 }
],
"zellen": {
"laenger": {
"n": 5,
"kritisch": 0,
"eintraege": [
{
"snapshot_id": "uuid", "definition_id": "uuid",
"type_label_de": "Prozess-Engpass", "kernaussage_short": "IMS braucht länger",
"tier": "notable", "deviation_factor": 10.7, "ticket_count": 32,
"time_impact_hours": null, "friction_impact_count": null, "trend": "stable",
"weitere_merkmale": [{ "merkmal": "predecessor_role", "wort": "Herkunft", "wert": "KC-Logistik" }],
"situation_id": "uuid"
}
]
}
}
}
],
"deckung": {
"befunde_scharf": 127, "befunde_mit_stelle": 102, "stellen": 27, "stellen_im_briefing": 11,
"ohne_spalte": {}, "unbekannte_typen": []
}
}Building-Block Briefing
#### Get The Building-Block Briefing
GET /api/v1/runs/{run_id}/bausteine-briefingReturns one page in one payload: the same measures the leading briefing uses,
arranged as a chain instead of side by side. Each block consumes the result of
the one before it: which area carries the run, who carries that area, where it
stalls, how it moved week by week, and what can be handed on.
Every number arrives with the population it was measured on and the window it
was measured in. Nothing here is ranked against anything from another block:
hours, counts and rates are different units, and a ranking across them would be
an arithmetic that has no meaning.
traeger says who carries the area, and in which of three modes the page
speaks: one value leads, no value leads, or the baseline is so close to zero
that leading is not a claim anyone can make. The third case is checked first.
A baseline near zero measures the denominator, not the difference.
eingang lists the intake roles of the run: a role that is the first role of
most tickets and hands them on at once. It is measured per run from the
interval table, never from the role's name, and it is empty or null when no
role qualifies or the run predates the measurement. Each entry carries
erstrolle_anteil (share of tickets that start there), weitergabe_anteil
(share of its finished steps that end in a hand-over) and median_h. An intake
role is named but never compared: it is not the counterpart (gut) of any
comparison, and its time is not rated. Where no other group remains for a
comparison, typisch.gut has all fields null and the comparison is stated
against the usual time alone.
typisch is the one comparison the page is about, and every other block on
the page follows it: the point cloud in wolke and the counterparts in
kandidaten.extrem look at the same area rather than choosing their own.
typisch.bestaetigung says what the comparison rests on: whether the spread
across all groups exceeds chance (achsenband), and how many single values
were confirmed on their own out of how many tested (bestaetigt, geprueft),
with their names (werte) and the period that test ran on. The two tests run
on different periods and answer different questions, so they are reported
side by side and never combined. schlecht_bestaetigt says whether the slow
end shown is itself one of the confirmed values. When the usual time of a
comparison is below half an hour, unter_sockel is true and faktor is
null: a ratio against a baseline near zero measures the denominator, so only
the two measured ends are given. Such a comparison can still lead the page.
typisch.befunde (and the same field on each entry of kandidaten.typisch)
names the open findings that speak about the same place as the comparison:
gleich for the same trait, the same value and the same population, verwandt
for a broader finding on the same trait and value (for example the whole
organisation instead of one company). It carries identifiers and the finding
type only, never a second number: the comparison keeps its own figure, and the
finding states its own, with unit and window, on its detail page.
schwellen carries the thresholds the answer was gated with, so a reader can
see why a block stayed silent instead of guessing. The thresholds are set
values, not derived ones, and they are the same for every data space.
entwicklung reports the weekly series computed from this run's own sections,
on the same population and window as the rest of the page. Weeks at either edge
of the window are marked, because a week cut off by the end of the data is not a
week with less work in it.
kandidaten holds the shortlists behind each block. Anything already handed on
is filtered out server-side, so the next candidate moves up on its own rather
than being remembered by the caller.
The bundled findings in kandidaten.vorgang are sorted into four baskets, one
for each unit they are measured in: time, friction, time of day and outcome.
korb names the basket; elle and elle_wert name the measure the basket is
ordered by: inside the time basket the share of that basket's lost time, in the
others the number of cases affected in the window. The list runs basket by
basket in that fixed order and is ordered only inside a basket, never across
baskets. Findings already marked as seen are left out, and no entry carries an
hour total. in_station3 names the blocks further up the page that already show
the same place, so it need not appear twice. deckung.ohne_korb lists anything
that fits no basket; it is meant to stay empty.
Every entry in kandidaten.vorgang also carries befunde: the individual
findings behind it, grouped by their own basket, anchor finding first, then
the validation result (confirmed before untested before not
confirmed), then severity tier, then case count. Each finding carries that
result as zufall_geprueft (geprueft, nicht_bestaetigt, nicht_pruefbar,
or null for runs from before validation existed), so a page can tell a
confirmed finding from an unconfirmed one instead of ordering both by size. len(befunde) equals the entry's own
findings count exactly -- every member is counted, whether or not it carries
a time-window impact. No finding here carries an hour total either; a case
count is the only currency-free measure that spans all finding types.
Every entry in kandidaten.vorgang also carries gruppen: the same findings ordered by the kind of their
counterpart, i.e. everything in a finding's ort except the entry's own side (merkmal_roh/wert).
Each group is {"merkmale": ["location"], "befunde": [0, 3, 4], "anzahl_seiten": 2}; merkmale are the raw
trait keys of the counterpart, anzahl_seiten is the number of distinct counterparts in the group (several
findings on the same counterpart count once), befunde are indices into the entry's befunde, in the order they appear there. The group of
the finding behind the first summary sentence comes first, then larger groups before smaller ones. A finding
with no counterpart is in no group and stays in befunde only. befunde itself is not reordered.
Each finding in befunde can also carry mass_satz: a ready-made sentence
built from that finding's own stored measurements, one wording per finding
type. It is null for a finding type with no wording of its own -- a shared
wording across different measures would misstate at least one of them.
zeitpunkt reports the finding's raw cyclical coordinate (a weekday, a
time-of-day bucket, or a weekend flag) when it has one, untranslated; null
when it has none. thema names the finding's topic (speed, distance, timing
or outcome), read directly from the finding type's registry entry -- null
only for a type outside that registry. It is independent of korb: a
finding type with no unit of measurement can still carry a topic here.
Each finding's ort lists its traits as raw key and value pairs (role,
category, location, predecessor_role). A finding that is about a pair of
roles (for example a repeated back-and-forth between two teams) also lists the
second role, as a further role entry after the others.
Each entry in kandidaten.vorgang can also carry kurzfassung: a short text
of checked sentences (saetze, form, stand), or null. seiten inside it
lists the traits (raw key and value, same shape as ort) of the finding the
first sentence is about, all of them, without a choice between them. It is
null while it has not been filled in for that text.
kandidaten.verhalten lists findings about how the process behaves as a whole,
without a fixed place in the organisation. Each entry carries satz: one short
sentence, written by the server in the form "when something happens, this
follows", built only from the findings own figures. Show it word for word. An
entry also has typ, identity_key and nenner (the count the sentence rests
on, as number and word). It has no addressee and no internal note.
Each entry in kandidaten.vorgang can also carry uebergaenge: the busiest
counterpart roles handing cases into, and taking cases out of, its anchor
role, up to three per direction, together with the total case count in each
direction (counting every transition the run recorded, not only the three
shown). null when the entry has no anchor role, or the underlying signal
has nothing for this run.
Each entry in kandidaten.vorgang, and each entry in its sprossen, carries
kurzfassung: {"saetze": [...], "form": "thema" | "zeit", "stand": "..."},
a short text of up to three sentences about that entry, checked against the
underlying evidence before it is stored. It is null when no checked text is
available for the entry; the payload never carries a reason or a substitute
text in that case.
Each entry in kandidaten.vorgang, and each entry in its sprossen, carries
weitergaben: every hand-over of that entry that is not cancelled, oldest
first, as {"an", "am", "zustand_wort"} (an is the recipient's name, else
the e-mail address; am the send time, ISO 8601 UTC; zustand_wort one of
uebergeben, angefangen, beantwortet, abgelehnt, ausgelaufen). A
hand-over that ran out unanswered stays in the list. A hand-over that could
not be sent is not listed. weitergegeben_satz is the ready sentence, for
example "Weitergegeben an Anna und Ben.", or null without a hand-over.
Both fields depend only on the hand-overs, not on status: they stay filled
after the entry is put aside. The same two fields sit on every entry of
in_beobachtung whose art is vorgang.
Candidates in kandidaten.weitere carry definition_id, the stable reference
used to accept one of them (see below), never the text key identity_key,
which is not unique for these entries.
A candidate that has been accepted as a known trade-off is filtered out of
kandidaten.vorgang / kandidaten.weitere and listed in angenommen[]
instead, together with the yardstick recorded at acceptance and the two
thresholds derived from it. A candidate that a run just sent back, because the
direction turned for the worse or its height or width outgrew that yardstick,
stays a plain card but carries rueckkehr: the reasons, the yardstick, and
the values measured now. It carries rueckkehr only in the one run it came
back; a run later it is an ordinary candidate again.
Every candidate in kandidaten.vorgang and kandidaten.weitere carries
achsenwert_fehlt, true when it has no value above zero on its basket's axis
(elle_wert missing or not above zero for a bundled entry; always true for a
single finding, which carries no basket width of its own). A single finding whose underlying
definition already belongs to a bundled entry of this run is left out of
kandidaten.weitere altogether and named instead in
deckung.einzelbefund_in_eintrag, together with the entry it belongs to and
whether it is that entry's anchor. It is reachable only through that entry,
never as a finding of its own. The one exception is a single finding this same run just sent back
(see rueckkehr above): it stays a candidate even when its definition also
belongs to a bundled entry, so a returned trade-off is never lost from view.
A bundled entry at the lowest severity tier is left out of kandidaten.vorgang
and named instead in deckung.beobachtet_ausgeblendet, unless its direction
has turned for the worse on a signal reliable enough to act on, or its width
in the last 12 weeks is more than 20 percent above its width in the previous
run. An entry this same run just sent back from an accepted trade-off is
never left out on this basis, whatever its severity. This rule leaves alone
an entry that is already excluded from the page for another reason.
Each hand-over in kandidaten.unterwegs carries anteil_unterwegs: the share
of hand-over time in completed cases that this hand-over accounts for, counted
on the same completed cases as its hours and its case count.
adressen_werden_gemerkt says whether an address entered on this page will
still be there next time. Programmatic access has no person to file an entry
under, so nothing is kept then, and the page can say so before anyone types.
uebergabe_moeglich says whether this access may hand a finding on at all:
handing on needs a signed-in person, so it is false for programmatic access.
angestossen lists what has been handed on, newest first. Each entry carries
one place per delegation with its own state and deadline, plus the places that
were held back. Its status is delegiert while answers are outstanding,
ueberfaellig once an open place is past its deadline, and beantwortet as
soon as one place has answered.
ausserhalb counts the sharp findings that no block of this page mentions.
A page that only ever describes what it already shows would report its own
shape.
grund is set, and the blocks carry neutral defaults, when the method has
nothing to say for this run. That is an answer, not an error, and it arrives
with 200. A run that does not exist, or whose underlying data file is gone,
returns 404.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
#### Get What Was Checked And Left Out
GET /api/v1/runs/{run_id}/verworfenCounts what the analysis of one run examined and did not put on a page: the
comparisons that were checked and left out, and the findings that were checked
and not confirmed. The building-block briefing carries the same numbers in its
verworfen field; this endpoint is for pages that do not load the briefing.
zeilen has one line per reason. Each comparison is counted once, under exactly
one reason, so the lines add up to eintraege. je_dimension splits a line by
the trait the comparison looked at; it is data only and adds up to that line's
anzahl. nicht_bestaetigt counts findings of this run that were checked and
not confirmed. positionen_nicht_bestaetigt counts roles with dormant open
tickets that did not stand out against the overall share, and is not included in
nicht_bestaetigt. A run that never computed comparisons returns no lines.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
Response:
{
"zeilen": [
{"grund": "Feld traegt nicht", "wort": "kein auswertbarer Unterschied im Feld", "anzahl": 129, "je_dimension": {"outcome": 31}},
{"grund": "unter dem Boden", "wort": "Unterschied zu klein", "anzahl": 38, "je_dimension": {"entry_hour": 9}}
],
"eintraege": 167,
"nicht_bestaetigt": 117,
"positionen_nicht_bestaetigt": 0
}#### Hand One Finding On
POST /api/v1/runs/{run_id}/bausteine-briefing/anstossHands one finding of the building-block briefing on to someone. Every place
with an address becomes its own delegation, with the same reply link, deadline
and state as any other delegation in the app, and it appears in
GET /api/v1/delegations. Each delegation records the text as it stood on the
page: the fact, the question, the lever, and the run it came from. The snapshot
is deliberate. The numbers of the next run are different numbers, and the
question was asked about these.
Handing on requires a signed-in person, because a delegation carries its
sender. Programmatic access receives 403 before anything is written or sent;
the briefing says so in advance via uebergabe_moeglich. A hand-over needs at
least one address: when every place is held back, the call returns 422 and
nothing is recorded.
The delegations belong to the data space, not to the run. A question that is
open stays open even when the run it came from is gone, and deleting that run
never removes it.
Handing the same candidate on twice is a conflict, not a second entry: the call
returns 409 and nothing changes. That same rule is what makes the next
candidate move up on its own. The read endpoint filters everything already
handed on out of its shortlists, so nothing has to be remembered by the
caller. Once every delegation of a hand-over has been cancelled, the candidate
returns to its list and can be handed on again.
identity_key is the key the read endpoint delivered for that candidate. Take
it from the answer rather than composing it: two places forming the same key
drift apart. gruppe is the shortlist it came from: typisch, extrem,
unterwegs or weitere. empfaenger_text names a role or a place, not a
person.
A hand-over usually names several places at once: the subject and the
counterparts that work its longest cases. Send one entry per place in
stellen, each with its own address or explicitly held back. One address
cannot stand for several places, so stellen and the older single
empfaenger_email are rejected together with 422.
A message goes out for every place that carries an address, with the fact, the
question, who sent it, the deadline if one was set (due_date, YYYY-MM-DD),
an optional personal note (nachricht), and a link through which the
recipient answers without signing in. Each message also names the other places
that were written to and the ones nobody had an address for, so both sides see
the same distribution. stellen[].person_name optionally names the person
behind an address. If sending is not configured or fails, the hand-over is
still recorded and mail_versendet is false with a reason. That is a result,
not an error. nur_vermerkt is always false and kept for older clients.
An address entered here is kept for next time, filed under the trait and value
of its place, and comes back pre-filled on the next hand-over naming the same
place. gemerkt lists what was kept. Programmatic access has no person to file
an entry under, so nothing is kept then. The briefing says so in advance via
adressen_werden_gemerkt.
Request Body:
{
"identity_key": "extrem:location:Nord",
"gruppe": "extrem",
"empfaenger_text": "Standort Nord and role Dispatch",
"stellen": [
{"dimension": "location", "wert": "Nord", "name": "Standort Nord",
"email": "[email protected]", "person_name": "Alex Doe"},
{"dimension": "role", "wert": "Dispatch", "name": "Rolle Dispatch",
"zurueckgestellt": true}
],
"due_date": "2026-10-15",
"nachricht": "Could you take a look before the review?",
"payload": {
"fakt": "Cases from this location wait 3.4x longer",
"frage": "What happens to these cases before they reach you?",
"hebel": 3.4
}
}Response (201):
{
"eintrag": {
"id": "uuid",
"identity_key": "extrem:location:Nord",
"gruppe": "extrem",
"empfaenger_text": "Standort Nord and role Dispatch",
"empfaenger_email": null,
"stellen": [
{"dimension": "location", "wert": "Nord", "name": "Standort Nord",
"email": "[email protected]", "zurueckgestellt": false,
"status": "sent", "due_date": "2026-10-15", "beantwortet_am": null},
{"dimension": "role", "wert": "Dispatch", "name": "Rolle Dispatch",
"email": null, "zurueckgestellt": true,
"status": null, "due_date": null, "beantwortet_am": null}
],
"status": "delegiert",
"angestossen_am": "2026-09-02T09:00:00",
"payload": {"fakt": "...", "frage": "...", "run_id": "uuid"}
},
"mail_versendet": true,
"mail_grund": null,
"versendet_an": ["Standort Nord"],
"gemerkt": ["Standort Nord"],
"nur_vermerkt": false
}Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
#### Set A Candidate Aside To Monitor It
POST /api/v1/runs/{run_id}/bausteine-briefing/annahmeSets one candidate of the building-block briefing aside to monitor it, in the
same store as POST /api/v1/beobachtung. The state (duration, number of cases,
and direction where the candidate has one) is measured from the run behind
this page. The candidate leaves its basket until a later run finds duration or
cases more than the fixed margin above that state, or the direction turning
worse with enough confidence. Time alone never brings it back.
art is vorgang for a bundled finding or befund for a single finding.
bezug_id is the reference the read endpoint delivered for that candidate:
id for a bundled finding, definition_id for a single finding, never a text
key.
A run that does not exist, or belongs to a different data space, or does not
currently hold this candidate, returns 404. A candidate the run cannot place
in any basket returns 409, and so does setting aside a candidate that is
already being monitored. Setting the same candidate aside again after it came
back replaces the earlier state with a fresh one.
Request Body:
{
"art": "vorgang",
"bezug_id": "uuid"
}Response (201):
{
"id": "uuid",
"art": "vorgang",
"bezug_id": "uuid",
"status": "in_beobachtung",
"stand": {"zeit": 3.2, "faelle": 40, "richtung": "nicht_schlechter", "richtung_belastbar": true}
}Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
A body that also carries ausgefuehrt_am (only with art = vorgang) is a sync-mode request, handled exactly like the endpoint below: the run_id in the path is ignored completely (it may even belong to a deleted run), the entry is found by its own id in the current run, and the answer is 200 with an ergebnis. Sync mode is not available yet: a well-formed request returns 501.
#### Set A Bundled Finding Aside As A Queued Offline Action
POST /api/v1/situations/{situation_id}/annahmeSync-mode counterpart of the endpoint above for a bundled finding. The entry is addressed by its own id, and no run is named: the server always applies the action to the current run. An entry that is gone or belongs to an older run returns nicht_mehr_im_lauf; one whose run is still in progress or broke off returns lauf_laeuft. Neither writes anything. The body carries only ausgefuehrt_am (ISO 8601 with offset, required). The request needs the headers Idempotency-Key (one UUID per action), X-Geraet-Jetzt and X-Erwarteter-Mandant.
Request Body:
{
"ausgefuehrt_am": "2026-11-12T21:04:05.123+01:00"
}Response (200):
{
"ergebnis": "angewendet",
"satz": null,
"annahme": {"id": "uuid", "art": "vorgang", "bezug_id": "uuid", "status": "in_beobachtung", "stand": {}}
}ergebnis is one of angewendet, schon_so, ueberholt, nicht_mehr_im_lauf, lauf_laeuft; satz is the sentence to show for every outcome except angewendet. With ueberholt, zustand names the state the entry is in now (in_beobachtung, gezeigt, weitergegeben or status): the action is overtaken when the entry was changed later than the action was taken (the device time is corrected by the clock offset reported in X-Geraet-Jetzt; an equal moment counts as overtaken). A missing or malformed header or timestamp (including a timestamp without offset) returns 400 with code SYNC_KOPF_UNGUELTIG. Other error codes: IN_ARBEIT (409), SCHLUESSEL_ANDERER_INHALT (422), ZUGANG_ENTZOGEN (403: the X-Erwarteter-Mandant is not the workspace the request resolved to, or the membership is gone). Sync mode is not available yet: a well-formed request returns 501 with SYNC_NICHT_UNTERSTUETZT.
Parameters:
| Name | Type | Description |
|---|---|---|
situation_id | path | ID of the bundled finding |
#### Show A Monitored Candidate Again
POST /api/v1/bausteine-briefing/annahmen/{annahme_id}/zuruecknehmenSame as POST /api/v1/beobachtung/{beobachtung_id}/wieder-zeigen: the
candidate is a candidate again on the next read. The stored state is deleted,
not kept as history. An entry the caller's data space does not own returns
404.
Response (200):
{
"id": "uuid",
"geloescht": true
}Parameters:
| Name | Type | Description |
|---|---|---|
annahme_id | path | ID of the monitored entry |
#### List Everything Set Aside To Monitor
GET /api/v1/beobachtungLists everything this workspace has set aside to monitor: situations, single
findings and comparisons. Each entry carries the state when it was set aside
(stand), the limit above which it comes back (grenze), the state found by
the latest run that checked it (stand_zuletzt, null before the first
check) and, for entries the latest checked run brought back, the reasons
(rueckkehr.gruende: zeit, faelle, richtung). Nothing is recomputed at
read time.
Response (200):
{
"in_beobachtung": [
{
"id": "uuid",
"art": "vorgang",
"bezug": "uuid",
"status": "in_beobachtung",
"titel": "Lange Verweildauer in IMS ServiceDesk",
"zurueckgelegt_am": "2026-10-23T09:12:00",
"stand": {"zeit": 3.2, "faelle": 40, "richtung": "nicht_schlechter", "richtung_belastbar": true},
"grenze": {"zeit": 3.8, "faelle": 48},
"stand_zuletzt": {"am": "2026-10-24T02:00:00", "run_id": "uuid", "stand": {"zeit": 3.3, "faelle": 41}},
"rueckkehr": null
}
],
"zurueck": [],
"schwelle": 0.2
}#### Set An Entry Aside To Monitor It
POST /api/v1/beobachtungSets a situation (art: vorgang, bezug = situation id), a single finding
(befund, finding id) or a comparison (kontrast, its identity key) aside.
The state is taken from the data now, never from numbers the caller sends. The
entry comes back once a later run finds duration or cases more than the fixed
margin above that state, or the direction turning worse with enough
confidence. Time alone never brings it back. An entry that does not belong to
this workspace returns 404; one that is already being monitored returns
409. Read-only members receive 403.
Request Body:
{
"art": "kontrast",
"bezug": "identity-key"
}Response (201): one entry, same shape as in the list above.
#### Show A Monitored Entry Again
POST /api/v1/beobachtung/{beobachtung_id}/wieder-zeigenTakes an entry out of monitoring right away, without waiting for a run. The
stored state is cleared, not kept as history. An entry that does not belong to
this workspace returns 404. Read-only members receive 403.
Response (200):
{
"id": "uuid",
"art": "vorgang",
"bezug": "uuid"
}Parameters:
| Name | Type | Description |
|---|---|---|
beobachtung_id | path | ID of the monitored entry |
#### Set A Comparison Aside To Monitor It
POST /api/v1/kontraste/{kontrast_id}/akzeptierenSame as POST /api/v1/beobachtung with art: kontrast, addressed by the row id
of a comparison instead of its identity key. Kept for existing clients. A row
that does not belong to this workspace returns 404.
Response (200):
{
"id": "uuid",
"identity_key": "key",
"status": "in_beobachtung",
"beobachtung_id": "uuid"
}Parameters:
| Name | Type | Description |
|---|---|---|
kontrast_id | path | Row id of the comparison |
#### Show A Monitored Comparison Again
POST /api/v1/kontraste/{kontrast_id}/zuruecknehmenSame as POST /api/v1/beobachtung/{beobachtung_id}/wieder-zeigen, addressed by
the row id of a comparison. Returns the comparison with status: offen.
Parameters:
| Name | Type | Description |
|---|---|---|
kontrast_id | path | Row id of the comparison |
#### Look Up The Address Of Each Place
POST /api/v1/runs/{run_id}/bausteine-briefing/adressenReturns, in the order asked, the address already on file for each place a
hand-over names: the address, who it is filed under, and when that entry was
last touched. A place with nothing on file comes back with email set to
null. That is an answer, not a gap, so a client can show a visibly empty field
instead of no field at all.
Places are identified by trait and value together. A value like Anwendung can
be a role and a topic at the same time, and those are two different places with
two different addresses.
Whether an address entered now will still be there next time is answered once
for the whole page, by adressen_werden_gemerkt on the briefing itself, so it
can be said before anyone starts typing.
Request Body:
{
"stellen": [
{"dimension": "location", "wert": "Nord"},
{"dimension": "role", "wert": "Dispatch"}
]
}Response (200):
{
"stellen": [
{"dimension": "location", "wert": "Nord", "email": "[email protected]",
"name": "Standort Nord", "zuletzt": "2026-09-02T09:00:00"},
{"dimension": "role", "wert": "Dispatch", "email": null,
"name": null, "zuletzt": null}
]
}Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
Time In Transit
#### Get Time In Transit
GET /api/v1/runs/{run_id}/unterwegsReturns how much of the waiting time was spent at stations that did not solve
the case: in hours, and as a share of the total waiting time. The share is what
makes two data spaces comparable; the hours are what makes the share concrete.
Counted are only completed cases. The filter matters: it changes the number
substantially, and without it the result measures how the data was cut rather
than how work flowed. Cases that passed through a single station have a value of
zero by construction. That is a statement, not a gap.
stufe says how much room the number deserves: fuehrt when transit time is the
larger story, voll when it is a full one, satz when it is small enough that a
single sentence is the honest form. The thresholds behind it are deliberate
estimates, adjustable, and live in one place.
Drivers name where the time sat, not why. The number of sections is reported
next to the hours because the two together separate a busy way-station from a
parked case: the same share of hours means something different across eight
thousand short sections than across fifty long ones.
ueberschneidung counts how many of these cases also appear among the longest
waiting times overall. The two views are connected through the same cases, never
by adding their numbers together.
A run computed before this measure existed answers 200 with
vorhanden: false and a reason. That is a third state, not an empty result.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID |
#### Get Time In Transit Over Runs
GET /api/v1/runs/{run_id}/unterwegs/verlaufReturns the same measure across the runs of this data space, oldest first, so a
reader can tell a snapshot from a trend. Each entry carries the run, its date,
the share, the hours, and how much of it the top tenth carried.
Only runs that computed the measure appear. Earlier runs are absent rather than
zero. A missing value and a value of zero are different claims.
Parameters:
| Name | Type | Description |
|---|---|---|
run_id | path | Analysis run ID (identifies the data space) |
Billing & Credits
#### Get AI Credits Status
GET /api/v1/billing/ai-creditsReturns 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-typesReturns available connector types (e.g., Matrix42, Jira Service Management).
#### Create Connector
POST /api/v1/connectorsCreates a new ITSM connector for automated data synchronization.
#### Test Connection
POST /api/v1/connectors/{connector_id}/testTests connectivity to the ITSM system without importing data.
#### Start Sync
POST /api/v1/connectors/{connector_id}/syncTriggers 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.
A sync replaces the dataset completely. If CSV uploads have been merged into the
dataset, the sync is refused with 409 so that this data is not lost. A dataset
filled by a single CSV upload (without a merge) can still be switched to a connector.
Authentication
#### Login
POST /api/v1/auth/loginRequest 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/refreshRefreshes an expired access token using the refresh token.
#### Current User
GET /api/v1/auth/meReturns the current authenticated user and tenant information.
Each entry of tenants also carries the current state of that workspace's analysis runs:
| Field | Type | Meaning |
|---|---|---|
aktueller_lauf | object or null | run_id and finished_at (ISO 8601, UTC) of the most recently finished successful run; null if there is none. Retired data spaces are ignored. |
lauf_laeuft | boolean | true while the newest run is queued, running or failed; false when it succeeded or no run exists. |
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:
GET /api/v1/executive-summary: Top situations, health score, trendsContinuous Monitoring:
GET /api/v1/flow-health: Check for new bottlenecksGET /api/v1/analysis-summary: Track anomaly trendsDeep Dive:
GET /api/v1/runs/{id}/findings?tier=critical: Critical anomaliesGET /api/v1/situations/{id}: Situation contextGET /api/v1/situations/{id}/narrative: AI-generated explanationDelegation Automation:
GET /api/v1/runs/{id}/situations-queue: Triage queuePOST /api/v1/situations/{id}/delegate: Assign responsibilityGET /api/v1/delegations: Track follow-upsWhat 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
critical, notable, observedimproving, stable, worsening, newhigh, medium, lowstatements.de / statements.enCache-Control: private, max-age=300Error 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:
| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 202 | Accepted (async operation started) |
| 204 | Deleted (no content) |
| 400 | Bad request (validation error) |
| 401 | Authentication required |
| 403 | Insufficient permissions or feature not available |
| 404 | Resource not found |
| 409 | Conflict (e.g., run still in progress) |
| 422 | Validation error (detailed field-level errors) |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
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-summarySupported ITSM Systems
| System | Integration | Status |
|---|---|---|
| Matrix42 | Native connector | Available |
| Jira Service Management | Native connector | Available |
| ServiceNow | Planned | Coming soon |
| TOPdesk | Planned | Coming soon |
| Any ITSM | CSV import | Available |