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

# Overview

> Base URL, authentication, errors, response format and pagination for the Igris management API.

## Base URL

```
https://api.igrisecurity.com
```

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

## Authentication

The management API accepts two kinds of credentials:

* **Session cookie.** What the dashboard uses. The session must have an active organization.
* **API key.** Send `Authorization: Bearer ig_...`. Create keys in **Settings → API Keys**.

If a session is present it is used first. Otherwise the API key is checked.

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

### API keys act as their creator

An API key does not have its own permissions. It acts with the **current role and per-member overrides of the person who created it**. If that person's role changes, the key's access changes with it. If that person leaves the organization, the key stops working and returns `401`. See [Roles and permissions](/reference/permissions).

### Errors

| Status | Body | Meaning |
| - | - | - |
| `401` | `{ "error": "Unauthorized" }` | No valid session or key, or the key's creator is no longer a member. |
| `400` | `{ "error": "No active organization. Select or create one first." }` | Session has no active organization. |
| `403` | `{ "error": "Forbidden", "required": "policies:write" }` | The caller lacks the permission listed in `required`. |
| `403` | `{ "error": "You are no longer a member of this organization." }` | Session user was removed from the organization. |
| `403` | `{ "error": "plan_feature_unavailable", "feature": "...", "currentPlan": "...", "upgradeTo": "..." }` | The feature is not on your plan. |
| `422` | `{ "success": false, "error": { "name": "ZodError", "message": "..." } }` | Validation failure on connections and policies. `message` is a JSON string of the issues. |
| `422` | `{ "error": "..." }` | Validation failure on webhooks and audit restore. |
| `400` | `{ "success": false, "error": { "name": "ZodError", "message": "..." } }` | Body validation failure on other routes (sessions, incidents, members, API keys). Same shape as the `422` above, with status `400`. |
| `400` | `{ "error": "..." }` | Route-specific checks, such as an invalid ID or a URL that points at an internal address. |

Validation errors are not uniform across routes. Check the status and body shape per endpoint. Rate limits, body size limits, and the full error format are in [Limits and errors](/reference/limits-and-errors#error-format).

### Public routes

These routes need no session. Some still need a key in the request body or header.

| Path | Notes |
| - | - |
| `GET /health`, `GET /health/ready` | Liveness and readiness. |
| `GET /api/v1/billing/plans` | Plan catalog. |
| `GET /api/v1/api-keys/verify` | Validates the `ig_` key you send as a Bearer token. See **Verify an API key** in the API Keys section. |

Other routes not covered on this page (`/api/v1/billing/webhook`, `/api/v1/admin/ops/*`, `/api/v1/ingest/*`) are for Igris's own infrastructure or log-ingestion integrations. They are not part of the client management API.

***

## Response format

Single resources and action results come back wrapped in `data`. Example bodies below show the full envelope. Action results such as `{ "deleted": true }` are also inside `data`:

```json theme={null}
{ "data": { "id": "..." } }
```

List endpoints add a `meta` object:

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

`meta.nextCursor` is present on cursor-paginated lists (audit events, incidents). Audit events also add `meta.archive` when the `from`/`to` range overlaps archived data.

## Pagination

Most lists use `limit` and `offset`:

```http theme={null}
GET /api/v1/policies?limit=50&offset=100
```

| Endpoint | Default `limit` | Max `limit` | Cursor |
| - | - | - | - |
| Connections, policies, sessions | 50 | 100 | No |
| Audit events | 50 | 500 | `cursor` |
| Incidents | 50 | 200 | `cursor` |
| API keys, webhooks | Not paginated | | No |

**Cursors.** Audit events and incidents return `meta.nextCursor` when the page is full. Pass it back as `cursor` to get the next page. When a page is not full, `nextCursor` is `null` and there is nothing more to fetch. Incidents ignore `offset`.

<Warning>
  Cursors are time-based and have limits. Audit events filter on `timestamp < cursor`, so they only page correctly with the default `sort=ts&dir=desc`. Incidents are sorted by status, then severity, then `lastSeen`, but the cursor filters on `lastSeen` alone, so paging through a mixed list can skip rows. For a complete export of incidents, page within a single `status` (and `severity`) filter.
</Warning>

***

## Other endpoints

These routes exist but are not documented in detail here. Each shows the permission it requires.

| Area | Paths | Required permission |
| - | - | - |
| Custom detectors | `GET /api/v1/detectors/catalog`, `GET /api/v1/detectors/custom`, `POST /api/v1/detectors/custom/test` | `policies:read` |
| Custom detectors | `POST /api/v1/detectors/custom`, `PATCH` and `DELETE /api/v1/detectors/custom/:id` | `policies:write` |
| Servers | `GET /api/v1/servers`, `GET /api/v1/servers/:serverId/tools` | `servers:read` |
| Servers | `POST /api/v1/servers`, `DELETE /api/v1/servers/:serverId` | `servers:write` |
| AI systems | `/api/v1/ai-systems` | `ai-systems:read` (reads), `ai-systems:write` (writes) |
| AI systems | `GET /api/v1/ai-systems/:id/conformity-declaration` | `comply:read`, plus a plan with EU AI Act support |
| AI systems | `GET /api/v1/ai-systems/:id/gdpr-record` | `comply:read`, plus a plan with GDPR support |
| Reports | `/api/v1/reports` | `reports:read`, `reports:generate`. Needs a plan with log ingestion |
| HIPAA | `/api/v1/hipaa/baa` | `hipaa:read`, `hipaa:write`. Needs a plan with HIPAA |
| SOC 2 | `POST /api/v1/soc2/export` | `soc2:export` |
| Billing | `/api/v1/billing/*` | `team:billing` for changes |

For permission names and which roles hold them, see [Roles and permissions](/reference/permissions).


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