API docs

UmamiAI exposes a small, versioned HTTP API under /api/v1. Authentication is via scoped API keys.

Quickstart (curl)

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

RUN_ID=$(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\":\"Hello from API\"}" \
  | jq -r ".run_id")

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

Requires jq. Scopes needed: runs:create and runs:read.

Downloads

Import into Postman or run the same requests from your terminal.

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

Postman: import the collection and environment, then set base_url, api_key, org_id, agent_version_id. Run “Create Agent Run” and copy the returned run_id into run_id env var to fetch it.

Prefer OpenAPI? Import /integration/openapi.json into your API tooling or use it to generate SDKs.

Authentication

Use an UmamiAI API key in the Authorization header:Authorization: Bearer umami_...

Create keys in Org → API Keys. Keys are scoped. Supported scopes:runs:create, runs:read, kb:read (or *).

Endpoints

POST /api/v1/agent-runs

Create an agent run. Scope: runs:create

GET /api/v1/agent-runs/:runId

Fetch run status/output. Scope: runs:read

POST /api/v1/knowledge/search

Vector search over knowledge. Scope: kb:read

Create an agent run

Body fields: org_id, agent_version_id, input.

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\":\"Write a short update for stakeholders.\"}"

Fetch run status/output

Returns status (queued/running/succeeded/failed) and the final output.

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

Knowledge search

This endpoint embeds your query server-side. Ensure your deployment has OPENAI_API_KEY set. It returns a ranked list of chunks with similarity scores.

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 changed in the last release?\",\"match_count\":6}" | jq

Errors

401 — missing_api_key / invalid_api_key
403 — insufficient_scope
400 — invalid_request
404 — not_found

Need webhooks?

For receiving signed outbound webhooks (HMAC SHA-256), see the webhook section.