REST API Reference

Base URL

https://api.igrisecurity.com

All management API endpoints are under /api/v1/.

Authentication

All requests require a Bearer API key:

Authorization: Bearer ig_...

Generate keys in Settings → API Keys in the Igris Dashboard. On 401, the response is:

{ "error": "Unauthorized" }

Connections

Encrypted credential vaults for MCP and LLM providers.

Method	Path	Description
`GET`	`/api/v1/connections`	List all connections
`POST`	`/api/v1/connections`	Create a connection
`GET`	`/api/v1/connections/:slug`	Get a connection
`PATCH`	`/api/v1/connections/:slug`	Update a connection
`DELETE`	`/api/v1/connections/:slug`	Delete a connection
`POST`	`/api/v1/connections/test`	Test a connection’s upstream
`POST`	`/api/v1/connections/:slug/rotate`	Rotate connection credentials

Connection shape:

{
  "id": "uuid",
  "slug": "github-prod",
  "name": "GitHub Production",
  "serverType": "http",
  "upstreamUrl": "https://api.github.com/mcp",
  "authType": "bearer",
  "enabled": true,
  "createdAt": "2026-01-01T00:00:00Z"
}

serverType is "http", "stdio", or "llm". LLM connections include llmProvider, allowedModels, logFullContent, and bodyRetentionDays.

Policies

Governance rules evaluated at the gateway for every tool call or LLM request.

Method	Path	Description
`GET`	`/api/v1/policies`	List all policies
`POST`	`/api/v1/policies`	Create a policy
`GET`	`/api/v1/policies/:id`	Get a policy
`PATCH`	`/api/v1/policies/:id`	Update a policy
`DELETE`	`/api/v1/policies/:id`	Delete a policy

Policy shape:

{
  "id": "uuid",
  "name": "Block delete tools",
  "connectionSlug": "github-prod",
  "rules": [
    {
      "target": { "kind": "mcp_tool", "tool": "delete_*" },
      "action": "deny"
    }
  ],
  "enabled": true,
  "createdAt": "2026-01-01T00:00:00Z"
}

connectionSlug is null for global policies (applied to all connections). action is "allow", "deny", or "alert". Rules also support conditions, limit, tokenGuard, and contentGuard fields — see the Policies guide.

Sessions

MCP agent sessions tracked by the governance gateway.

Method	Path	Description
`GET`	`/api/v1/sessions`	List sessions
`GET`	`/api/v1/sessions/:id`	Get a session
`POST`	`/api/v1/sessions/:id/suspend`	Suspend a session
`POST`	`/api/v1/sessions/:id/resume`	Resume a suspended session

Session shape:

{
  "id": "uuid",
  "connectionSlug": "github-prod",
  "status": "active",
  "userId": "alice@company.com",
  "startedAt": "2026-01-01T00:00:00Z",
  "lastSeenAt": "2026-01-01T01:00:00Z"
}

status is "active", "suspended", or "ended".

Audit Events

Complete log of all tool calls, LLM calls, anomaly signals, and policy decisions. Events are retained in Postgres, then archived to S3 and restorable on demand.

Method	Path	Description
`GET`	`/api/v1/audit-events`	List audit events (paginated)
`GET`	`/api/v1/audit-events/:id`	Get a single audit event
`POST`	`/api/v1/audit-events/restore`	Request restore of archived events from S3
`GET`	`/api/v1/audit-events/restore-jobs`	List S3 restore jobs

Audit event shape:

{
  "id": "uuid",
  "type": "mcp_tool_call",
  "source": "igris",
  "toolName": "create_branch",
  "policyAction": "allow",
  "connectionSlug": "github-prod",
  "userId": "alice@company.com",
  "traceId": "ig_trace_abc123",
  "severity": null,
  "timestamp": "2026-01-01T00:00:00Z"
}

type is "mcp_tool_call", "llm_call", or "anomaly". LLM call events include provider, model, tokensIn, tokensOut, costCents, latencyMs, and llmEndpoint. Query params: limit, offset, type, connectionSlug, severity, from, to.

Incidents

Security incidents auto-opened by anomaly detection or alert-action policies.

Method	Path	Description
`GET`	`/api/v1/incidents`	List incidents (paginated)
`GET`	`/api/v1/incidents/count`	Open incident count
`GET`	`/api/v1/incidents/:id`	Get an incident
`GET`	`/api/v1/incidents/:id/events`	Get audit events for an incident
`PATCH`	`/api/v1/incidents/:id`	Update (resolve, assign, add note)

Incident shape:

{
  "id": "uuid",
  "title": "Anomaly: rate spike on github-prod",
  "status": "open",
  "severity": "high",
  "connectionSlug": "github-prod",
  "createdAt": "2026-01-01T00:00:00Z",
  "resolvedAt": null
}

status is "open", "investigating", or "resolved". Idle incidents auto-resolve after 7 days.

LLM Cost

Cost and token usage for LLM gateway traffic.

Method	Path	Description
`GET`	`/api/v1/observe/llm-cost/summary`	Aggregate cost and token summary
`GET`	`/api/v1/observe/llm-cost/timeseries`	Cost time-series data

Summary shape:

{
  "totalCostCents": 12345,
  "totalInputTokens": 1000000,
  "totalOutputTokens": 500000,
  "byConnection": [...],
  "byProvider": [...],
  "byModel": [...]
}

Query params: from, to, connectionSlug, provider.

Observe

CISO dashboard metrics for MCP traffic.

Method	Path	Description
`GET`	`/api/v1/observe/summary`	Dashboard summary metrics
`GET`	`/api/v1/observe/risk-map`	Per-connection risk scores
`GET`	`/api/v1/observe/stats`	Traffic and policy stats

Webhooks

Outbound HTTP webhooks for real-time event delivery.

Method	Path	Description
`GET`	`/api/v1/webhooks`	List webhooks
`POST`	`/api/v1/webhooks`	Create a webhook
`PATCH`	`/api/v1/webhooks/:id`	Update a webhook
`DELETE`	`/api/v1/webhooks/:id`	Delete a webhook
`POST`	`/api/v1/webhooks/:id/test`	Send a test event

Webhook shape:

{
  "id": "uuid",
  "url": "https://your-service.com/hooks/igris",
  "events": ["policy_deny", "anomaly"],
  "enabled": true,
  "createdAt": "2026-01-01T00:00:00Z"
}

Event types: policy_deny, anomaly. The webhook payload includes type, teamId, serverId, sessionId, toolName, reason, and timestamp. Deliveries are signed with HMAC-SHA256; verify the X-Igris-Signature header.

API Keys

Manage programmatic access keys for the API and gateway.

Method	Path	Description
`GET`	`/api/v1/api-keys`	List API keys
`POST`	`/api/v1/api-keys`	Create an API key
`DELETE`	`/api/v1/api-keys/:id`	Revoke an API key
`GET`	`/api/v1/api-keys/verify`	Verify a key (CLI use)

API keys are shown in full only once on creation. The list endpoint returns metadata only (no raw key values).

Events (SSE)

Real-time event stream over Server-Sent Events.

Method	Path	Description
`GET`	`/api/v1/events`	Open SSE stream

GET /api/v1/events
Authorization: Bearer ig_...
Accept: text/event-stream

Event types pushed on the stream:

Event	When
`tool_call`	MCP tool call processed by gateway
`anomaly`	Anomaly signal detected
`llm_call`	LLM request processed
`llm_anomaly`	LLM anomaly signal detected

Each event is a JSON object on the data: line. The stream is org-scoped — you only receive events for your organization. Keep the connection alive; the server sends a ping comment every 30 seconds.

Pagination

List endpoints use offset pagination:

GET /api/v1/audit-events?limit=50&offset=0

Response envelope:

{
  "data": [...],
  "total": 1234,
  "limit": 50,
  "offset": 0
}

Default limit is 50; maximum is 200.

​REST API Reference

​Base URL

​Authentication

​Connections

​Policies

​Sessions

​Audit Events

​Incidents

​LLM Cost

​Observe

​Webhooks

​API Keys

​Events (SSE)

​Pagination