API examples

These examples use the tenant-scoped base URL and a scoped API key — see Authentication. Throughout, $BASE is https://dependra.io/api/$TENANT_ID.

Create an application

Requires the write scope.

curl -X POST "$BASE/applications" \
  -H "Authorization: Bearer $DEPENDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Service",
    "technicalName": "order-service",
    "description": "Handles order lifecycle and fulfillment",
    "lifecycleState": "Production",
    "criticalityTier": "BusinessCritical",
    "ownerTeam": "Commerce Team"
  }'

const res = await fetch(`${BASE}/applications`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Order Service',
    technicalName: 'order-service',
    description: 'Handles order lifecycle and fulfillment',
    lifecycleState: 'Production',
    criticalityTier: 'BusinessCritical',
    ownerTeam: 'Commerce Team',
  }),
});
const application = await res.json();

var payload = new {
    name = "Order Service",
    technicalName = "order-service",
    description = "Handles order lifecycle and fulfillment",
    lifecycleState = "Production",
    criticalityTier = "BusinessCritical",
    ownerTeam = "Commerce Team",
};
var content = new StringContent(
    JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("applications", content);

lifecycleState — one of Planning, Development, Pilot, Production, Sunset, Retired. criticalityTier — one of Administrative, BusinessOperational, BusinessCritical, MissionCritical.

Response (201 Created) returns the created application with its generated id (a GUID).

Create a component

curl -X POST "$BASE/components" \
  -H "Authorization: Bearer $DEPENDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "3f9a…",
    "name": "Orders API",
    "technicalName": "orders-api",
    "kind": "WebAPI",
    "runtime": "Containers",
    "description": "REST API for order management",
    "isExternal": false
  }'

kind — one of WebAPI, WebApp, Database, Queue, Cache, EventBus, Worker, Storage, MobileApp, DesktopApp, ScheduledJob, Integration, Identity, Infrastructure, Other. runtime — one of Containers, Serverless, Vm, Managed, Saas, BareMetal.

Create a dependency

Component-level dependencies are directed edges between two components.

curl -X POST "$BASE/dependencies" \
  -H "Authorization: Bearer $DEPENDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceComponentId": "aaaa…",
    "targetComponentId": "bbbb…",
    "dependencyType": "Calls",
    "mode": "Hard",
    "required": true,
    "propagates": true,
    "protocol": "HTTPS",
    "transportEncryption": "TLS 1.3",
    "endpointAuthMethod": "OAuth2"
  }'

dependencyType — one of Calls, Reads, Writes, ReadsWrites, Publishes, Consumes, PubSub, TrafficFlow, UsesIdp. mode — one of Hard, Soft, Async, Degraded. The protocol, transportEncryption and endpointAuthMethod fields make the edge part of the dependency security register used for compliance evidence.

Push a health signal

Requires the health scope. Streams a component’s health into the impact pipeline; returns immediately.

curl -X POST "$BASE/components/orders-api/health" \
  -H "Authorization: Bearer $DEPENDRA_HEALTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "state": "Outage" }'

The {component} path segment accepts either the component’s GUID or its technicalName. state — one of Healthy, Warning, Degraded, Outage.

Response: 202 Accepted — the signal is queued; a consumer recomputes the cached impact snapshot, runs the incident lifecycle, and fires webhooks. A 429 means you’ve hit the per-plan health-signal rate cap.

Query blast radius

Blast radius is a GET with query parameters.

curl -G "$BASE/blast-radius" \
  -H "Authorization: Bearer $DEPENDRA_API_KEY" \
  --data-urlencode "entityId=aaaa…" \
  --data-urlencode "entityType=component" \
  --data-urlencode "direction=downstream" \
  --data-urlencode "maxDepth=3"

const params = new URLSearchParams({
  entityId: 'aaaa…',
  entityType: 'component',
  direction: 'downstream',
  maxDepth: '3',
});
const res = await fetch(`${BASE}/blast-radius?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const result = await res.json();

• entityType — application, component, capability, process, hosting-area, hosting-zone, technology, segment, or dataset.
• direction — downstream (what breaks if this fails) or upstream (what could cause this to fail).
• maxDepth — 1–10, capped per plan.
• Optional modeFilter / typeFilter — comma-separated (e.g. modeFilter=Hard,Soft).

The response rolls the reachable set up into affected components, applications, capabilities and audiences, with revenue exposure where the plan and visibility allow.

Bulk import

To bootstrap or bulk-update the landscape, author a YAML manifest.yaml and POST it to $BASE/manifest/preview (dry-run, returns the diff) then $BASE/manifest/apply. The easiest path is the dependra CLI — dependra validate, then dependra push --preview / dependra push; the manifest schema and an example are published at https://dependra.io/schema/manifest/v1/. See the MCP quickstart for the agent-driven path.