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