Process Radar API Documentation

Version: 2.0

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

Authentication: API Key or JWT Token

Last Updated: 2026-03-11

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": 3600
}

Use POST /api/v1/auth/refresh with the current token to obtain a new one before expiry.

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": "healthy",
  "version": "1.0.0"
}

Datasets & Upload

#### Create Dataset

Note: Dataset CRUD endpoints use the root path (/datasets), not the /api/v1/ prefix. The full URL is https://api.dkyra.com/datasets.

POST /datasets

Creates a new empty dataset for the current tenant.

Request Body:

{
  "name": "Q1 2026 Analysis"
}

Response (201):

{
  "dataset_id": "uuid",
  "name": "Q1 2026 Analysis",
  "status": "created",
  "created_at": "2026-02-09T10:00:00Z"
}

#### List Datasets

GET /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,
  "events_processed": 45000,
  "progress_phase": "complete",
  "progress_percent": 100,
  "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 /runs/{run_id}/findings

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

Parameters:

Response:

{
  "findings": [
    {
      "finding_id": "cbf7fec4f9a2",
      "finding_type": "high_dwell_time",
      "finding_type_label": "Hohe Verweildauer in Rolle",
      "tier": "critical",
      "affected_dimensions": {
        "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,
      "temporal": {
        "first_seen": "2024-01-15",
        "last_seen": "2024-06-30",
        "trend": "stable"
      }
    }
  ],
  "total": 181,
  "returned": 50
}

Response fields like finding_type contain machine-readable identifiers. Use finding_type_label for human-readable display.

#### Get Finding Detail

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

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

#### Get Finding Time Series

GET /findings/{definition_id}/timeseries

Returns weekly time series data for a finding, useful for sparklines and trend visualization.

Parameters:

Response:

{
  "definition_id": "uuid",
  "timeseries": [
    {
      "week": "2024-W01",
      "impact_hours": 45.2,
      "ticket_count": 12,
      "tier": "notable"
    }
  ],
  "trend": "worsening",
  "trend_factor": 1.35
}

#### Get Affected Tickets

GET /findings/{finding_id}/tickets

Returns sample ticket IDs affected by this finding.

Response:

{
  "finding_id": "uuid",
  "tickets": [
    { "ticket_id": "INC-2024-0042", "impact_hours": 12.5 },
    { "ticket_id": "INC-2024-0089", "impact_hours": 8.3 }
  ],
  "total_tickets": 234,
  "sample_size": 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.

#### 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"
}

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:

Billing & Credits

#### Get AI Credits Status

GET /api/v1/billing/ai-credits

Returns remaining AI analysis credits for the current tenant.

Response:

{
  "total_credits": 100,
  "used_credits": 23,
  "remaining_credits": 77,
  "plan": "pro"
}

Connectors

Process Radar supports direct ITSM integrations for automated data import.

#### List Available Connector Types

GET /api/v1/connectors/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/{id}/test

Tests connectivity to the ITSM system without importing data.

#### Start Sync

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

Triggers a data synchronization from the connected ITSM system.

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": 3600,
  "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:

{
  "detail": "Run not found",
  "status": 404,
  "title": "Not Found",
  "trace_id": "abc123"
}

Common Status Codes:

Rate Limits

Standard: 60 requests/minute per API key. 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