API Overview

The MITRITY REST API provides programmatic access to the full MITRITY platform. Manage agents, policies, audit logs, and integrations through a consistent, well-documented API.

Base URL

All API requests are made to:

https://api.mitrity.com/api/v1/

The API is versioned via the URL path. The current version is v1. When breaking changes are introduced, a new version will be released alongside the existing version with a documented migration path.

Authentication

All API requests require authentication via a Bearer token. Generate API keys in the MITRITY dashboard at Settings > API Keys.

curl https://api.mitrity.com/api/v1/agents \
  -H "Authorization: Bearer mk_your-api-key-here"

API keys are scoped to a tenant and have configurable permissions:

Key prefix	Environment
mk_	Production
mk_test_	Sandbox/testing

Treat API keys as secrets. Do not commit them to source control or expose them in client-side code. Rotate keys regularly in Settings > API Keys.

Rate Limits

Rate limits depend on your subscription plan:

Plan	Requests/minute	Burst
Starter	60	10
Professional	600	50
Enterprise	6,000	200

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1709312400

When the rate limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Response Format

All responses are JSON. Successful responses use standard HTTP status codes:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-01T12:00:00Z"
  }
}

Error responses include a machine-readable error code and a human-readable message:

{
  "error": {
    "code": "invalid_request",
    "message": "The action_pattern field is required.",
    "request_id": "req_abc123"
  }
}

Pagination

List endpoints return paginated results. Use cursor and limit query parameters:

GET /api/v1/agents?limit=25&cursor=eyJpZCI6MTAwfQ

The response includes a next_cursor field. When next_cursor is null, you have reached the end of the list.

Key Endpoints

Agents

Method	Endpoint	Description
GET	/api/v1/agents	List all agents
POST	/api/v1/agents	Register a new agent
GET	/api/v1/agents/{id}	Get agent details
PATCH	/api/v1/agents/{id}	Update agent configuration
DELETE	/api/v1/agents/{id}	Deregister an agent

Policies

Method	Endpoint	Description
GET	/api/v1/policies	List all policies
POST	/api/v1/policies	Create a new policy
GET	/api/v1/policies/{id}	Get policy details
PATCH	/api/v1/policies/{id}	Update a policy
DELETE	/api/v1/policies/{id}	Delete a policy

Audit Log

Method	Endpoint	Description
GET	/api/v1/audit	Query audit events (filterable by agent, action, decision, time range)
GET	/api/v1/audit/{id}	Get full event details including drift score and behavioral context

Credentials

Method	Endpoint	Description
GET	/api/v1/credentials	List credentials (the secret value is never returned)
POST	/api/v1/credentials	Create a credential
GET	/api/v1/credentials/{id}	Get credential metadata
PATCH	/api/v1/credentials/{id}	Update a credential (PUT also accepted)
DELETE	/api/v1/credentials/{id}	Delete a credential (cascades to its grants + leases)
GET	/api/v1/credentials/{id}/grants	List grants on a credential
POST	/api/v1/credentials/{id}/grants	Grant an agent access (idempotent: 201 create / 200 update)
DELETE	/api/v1/credentials/{id}/grants	Revoke grants — one agent via ?agent_id=, or all without it
POST	/api/v1/credentials/{id}/leases	Create a time-bound lease

See Credential Broker for the full credential → grant → lease model.

Delegation Chains

Method	Endpoint	Description
GET	/api/v1/delegation-chains	List chains for the tenant (filters: agent_id, status, blocked_reason, min_depth, date range)
GET	/api/v1/delegation-chains/{chain_id}	Get a single chain with all hops
GET	/api/v1/delegation-chains/summary	Aggregate counts by status / blocked reason, top initiators / delegates
GET	/api/v1/delegation-chains/settings	Get tenant delegation governance settings (Pro+)
PUT	/api/v1/delegation-chains/settings	Update tenant delegation governance settings (Pro+)

Threat Intelligence

Method	Endpoint	Description
GET	/api/v1/threat-intelligence/indicators	List indicators visible to the tenant (includes per-tenant overrides)
GET	/api/v1/threat-intelligence/indicators/{id}	Get a single indicator
PUT	/api/v1/threat-intelligence/indicators/{id}/override	Set severity / action override (Pro+)
DELETE	/api/v1/threat-intelligence/indicators/{id}/override	Clear override and any suppression (Pro+)
POST	/api/v1/threat-intelligence/indicators/{id}/suppress	Suppress in log-only or silent mode (Pro+)
DELETE	/api/v1/threat-intelligence/indicators/{id}/suppress	Lift suppression (Pro+)
GET	/api/v1/threat-intelligence/matches	List threat matches for the tenant
GET	/api/v1/threat-intelligence/matches/summary	Aggregate match counts by severity / action / type
GET	/api/v1/threat-intelligence/trending	Indicators ranked by match volume in a rolling window
GET	/api/v1/threat-intelligence/settings	Get tenant feed-subscription + default action
PUT	/api/v1/threat-intelligence/settings	Update tenant feed-subscription + default action

LLM Usage

Method	Endpoint	Description
GET	/api/v1/llm-usage	List per-call LLM Gateway usage records (filters: agent_id, provider, model, decision, time range)
GET	/api/v1/llm-usage/summary	Aggregate calls, tokens, and estimated cost grouped by model, agent, or day
GET	/api/v1/llm-usage/bom	LLM Bill of Materials -- per-agent provider/model inventory with lifetime totals

Integrations

Method	Endpoint	Description
GET	/api/v1/integrations	List configured integrations
POST	/api/v1/integrations/siem	Create a SIEM integration
POST	/api/v1/integrations/webhook	Create a webhook integration
DELETE	/api/v1/integrations/{id}	Remove an integration

Health & Readiness

Unauthenticated endpoints for load balancers and uptime checks (no /api/v1 prefix):

Method	Endpoint	Description
GET	/healthz	Liveness — 200 while the API process is serving
GET	/readyz	Readiness — 200 when dependencies (Postgres, Redis) are reachable; 503 when one is down

SDKs and Tools

Official SDKs are available for common languages:

• Python: pip install mitrity
• Go: go get github.com/mitrity/mitrity-go
• TypeScript: npm install @mitrity/sdk

Each SDK wraps the REST API with typed methods, automatic pagination, retry logic, and token management.

Interactive API Reference

Explore the full API with request/response schemas, example payloads, and a built-in request testing panel in the interactive API reference.