Push key result values via API

Any system that can make an HTTP POST request can drive a Dependra Key Result. This is the right mode when the metric comes from outside Dependra — a monitoring platform like Datadog, a CRM like Salesforce, a CI pipeline metric, or a custom report — and you want it to appear as a timestamped check-in on the KR.

Create an API key with the key-results scope

Pushed values require an API key scoped to key-results. This scope is separate from the landscape read and write scopes. See API Keys for instructions on creating and managing keys.

When creating the key:

• Set Name to something descriptive: “Datadog — reliability KRs” or “CI pipeline — deployment metrics”.
• Under Scopes, select key-results.
• Set an appropriate Expiration.

Copy the key immediately — it starts with dep_ and is shown only once.

The ingest endpoint

POST /api/{tenantId}/key-results/{krId}/ingest

Request body

{
  "value": 42.7,
  "status": "OnTrack",
  "comment": "Sprint 14 closed — 42.7 story points delivered"
}

Status values

If status is omitted, the check-in records the value without a status flag.

Response

202 Accepted — the value is recorded as a check-in on the KR. Progress and risk signals update immediately.

400 Bad Request — the request body is malformed or value is not a number.

401 Unauthorized — the API key is missing or invalid.

403 Forbidden — the API key does not have the key-results scope.

404 Not Found — the krId does not exist or does not belong to the tenant.

curl example

curl -X POST "https://dependra.io/api/$TENANT_ID/key-results/$KR_ID/ingest" \
  -H "Authorization: Bearer $DEPENDRA_KR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 42.7,
    "status": "OnTrack",
    "comment": "Sprint 14 closed — 42.7 story points delivered"
  }'

Replace $TENANT_ID, $KR_ID, and $DEPENDRA_KR_KEY with your values. Store them as environment variables or CI secrets — never hardcode them.

How pushed values appear

Each successful push creates a check-in on the KR, indistinguishable in structure from a manual check-in but attributed to the API integration. It appears in the KR’s check-in history with the push timestamp and any comment you supplied. The KR’s progress bar, objective progress, and risk signal engine all update immediately on receipt.

If you push more frequently than the KR’s cadence (e.g., hourly pushes from a Datadog metric on a Weekly-cadence KR), all values are recorded in history but the staleness indicator is based on the configured cadence, not the push frequency.

Common integration patterns

Datadog alert webhook — Configure a Datadog webhook monitor to POST to the ingest endpoint when a metric crosses a threshold. Send status: "AtRisk" when the metric degrades, status: "OnTrack" when it recovers.

CI pipeline gate — At the end of a deployment pipeline, compute a metric (test coverage %, build success rate, deployment frequency) and push it to the corresponding KR. Use the pipeline’s secret management to store the API key.

Salesforce flow — A Salesforce Process Builder or Flow can call the endpoint via an Outbound Message or HTTP callout. Suitable for revenue, NPS, or customer acquisition KRs that live in the CRM.

Weekly reporting script — A cron job or GitHub Actions scheduled workflow queries your data warehouse, computes the metric, and pushes the result each Friday. Reliable for metrics that only change weekly.

Rate limits

The ingest endpoint is subject to the same per-plan rate limits as the health-signal ingestion endpoint. Exceeding the limit returns 429 with a Retry-After header. If you need higher throughput, contact support to discuss your plan options.