> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igrisecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> REST API reference for the Igris management API.

# 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:

```http theme={null}
Authorization: Bearer ig_...
```

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

```json theme={null}
{ "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](/govern/policies).

***

## 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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 |

```http theme={null}
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:

```http theme={null}
GET /api/v1/audit-events?limit=50&offset=0
```

Response envelope:

```json theme={null}
{
  "data": [...],
  "total": 1234,
  "limit": 50,
  "offset": 0
}
```

Default `limit` is 50; maximum is 200.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.