Developer guide

Last updated: February 24, 2026

This page is intentionally focused on platform API integration (not deployment): how to authenticate, call UmamiAI endpoints from your services, and validate everything with curl.

Quick links

Prereqs Downloads Postman Auth + scopes Agent runs Knowledge search Webhooks Errors Testing API docs

Prereqs

You need an UmamiAI deployment URL, an organization, and at least one published agent version. Integration uses an UmamiAI API key created in the console.

Set env vars (curl)

export BASE_URL="https://<your-domain>"
export UMAMI_API_KEY="umami_<your-key>"
export ORG_ID="<uuid>"
export AGENT_VERSION_ID="<uuid>"

Tip: ORG_ID appears in the console URL (e.g. /org/<orgId>). Agent version IDs can be copied from the agent/version page URL.

Downloads

These assets are generated for integration testing. Import into Postman or run from the terminal.

Integration assets

Postman collection (JSON)Postman environment (JSON)curl_examples.sh (bash + jq)OpenAPI 3.0 spec (openapi.json)

Keep API keys server-side. Never ship umami_... keys to browsers.

Use openapi.json to generate clients or import into tools like Postman/Insomnia.

Postman setup

In Postman, click Import and import the collection JSON and the environment JSON from the Downloads section.
Select the environment and set: base_url, api_key, org_id, agent_version_id.
Run Create Agent Run. Copy the returned run_id into env var run_id.
Run Get Agent Run until status becomes succeeded or failed.

Authentication (API keys + scopes)

All Platform API calls use a Bearer token header:Authorization: Bearer umami_...

Create an API key

Open Org → API Keys.
Click Create key, choose scopes, and copy the key (shown once).
Store it securely in your backend (never ship it to browsers).

Scopes in this version: runs:create, runs:read, kb:read. Use * for full access (recommended only for development).

Agent runs API

Create a run, then poll until it completes.

1) Create a run (scope: runs:create)

curl -sS "$BASE_URL/api/v1/agent-runs" \
  -X POST \
  -H "Authorization: Bearer $UMAMI_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"org_id\":\"$ORG_ID\",\"agent_version_id\":\"$AGENT_VERSION_ID\",\"input\":\"Draft a concise incident summary for leadership.\"}"

Response contains run_id.

2) Get run status (scope: runs:read)

export RUN_ID="<run_id_from_previous_step>"

curl -sS "$BASE_URL/api/v1/agent-runs/$RUN_ID" \
  -H "Authorization: Bearer $UMAMI_API_KEY"

3) Poll until finished (bash + jq)

while true; do
  res=$(curl -sS "$BASE_URL/api/v1/agent-runs/$RUN_ID" -H "Authorization: Bearer $UMAMI_API_KEY");
  status=$(echo "$res" | jq -r ".status");
  echo "status=$status";
  if [ "$status" = "succeeded" ] || [ "$status" = "failed" ]; then
    echo "$res" | jq;
    break;
  fi;
  sleep 2;
done

On success, read output. On failure, inspect error.

Knowledge search API

Run similarity search over your org knowledge. The endpoint embeds your query server-side.

POST /api/v1/knowledge/search (scope: kb:read)

curl -sS "$BASE_URL/api/v1/knowledge/search" \
  -X POST \
  -H "Authorization: Bearer $UMAMI_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"org_id\":\"$ORG_ID\",\"query\":\"What are our top failure modes?\",\"match_count\":6}" | jq

Returns matches[] with fields: chunk_id, doc_id, content, score.

Requirement: your deployment must have OPENAI_API_KEY set.

Receiving webhooks

Configure outbound webhooks in Org → Webhooks. UmamiAI delivers signed JSON POST requests. Verify the signature before trusting the payload.

Headers

X-Umami-Event — event name
X-Umami-Delivery — delivery UUID
X-Umami-Signature — sha256=<hex-hmac>

Verify signature (curl + openssl test)

export WEBHOOK_SECRET="<your-webhook-secret>"
export WEBHOOK_URL="https://example.com/umamiai/webhook"
BODY='{"event":"agent_run.completed","org_id":"<org_id>","run_id":"<run_id>"}'
SIG=$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | sed "s/^.* //")

curl -sS "$WEBHOOK_URL" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Umami-Event: agent_run.completed" \
  -H "X-Umami-Delivery: 00000000-0000-0000-0000-000000000000" \
  -H "X-Umami-Signature: sha256=$SIG" \
  --data "$BODY"

In production, compute HMAC over the raw request body bytes (not a re-serialized JSON).

Errors + status codes

401 — missing_api_key / invalid_api_key
403 — insufficient_scope or org mismatch
400 — invalid_request
404 — not_found

Error responses are JSON: { error: string }.

Testing checklist

Start with a key that has scopes runs:create + runs:read.
Create a run and poll until succeeded or failed.
Enable kb:read only if you need knowledge search.
Test webhook receiver signature verification locally using the openssl curl recipe above.

Looking for a reference-style endpoint list? See API docs.

Looking for end-user console steps? See the user guide.