# API reference

Every endpoint of the Risotto public API: tickets, comments, departments, runbooks and audit events, with the scope each one needs

The Risotto public API lets your scripts and services work with tickets, comments, departments, runbooks and the audit log. This page lists every endpoint, the scope its API key needs, its parameters and its request body. The same spec, as OpenAPI 3.1, is at [/docs/openapi.yaml](https://www.tryrisotto.com/docs/openapi.yaml), for code generators and API clients.

## Basics

- **Base URL:** `https://api.tryrisotto.com/v1`
- **Authentication:** an [API key](https://www.tryrisotto.com/docs/dashboard/settings/developers/api-keys) in the `Authorization: Bearer` header, or in `X-API-Key`. Each endpoint below names the scope the key needs.
- **Rate limits:** 1,000 requests an hour for each key, unless Risotto set a different limit for your organization. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. See [Rate limits](https://www.tryrisotto.com/docs/dashboard/settings/developers/api-keys#rate-limits).
- **Pagination:** list endpoints take `limit` and `offset`, and return `count`, `next` and `previous` with the results.
- **Errors:** JSON with an `error` object that holds a `code`, a `message` and `details`. A `403` (`authorization_error`) names the scope the key is missing. See [Errors](https://www.tryrisotto.com/docs/dashboard/settings/developers/api-keys#errors).
- **Request IDs:** every response has an `X-Request-ID` header. Find the call under the same ID in the [request log](https://www.tryrisotto.com/docs/dashboard/settings/developers/request-log).
- **Retries:** `POST /tickets` takes an `Idempotency-Key` header, so a retry doesn't create a second ticket.

Risotto can also send events to your systems. See [Webhooks](https://www.tryrisotto.com/docs/integrations/webhooks).

## Tickets

### List tickets

`GET /v1/tickets` · needs `tickets:read`

Retrieve a paginated list of tickets for your organization.
Results can be filtered by status, department, requestor, assignee, and date ranges.

| Parameter         | In    | Type                                           | Required | Description                                                                                                                  |
| ----------------- | ----- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `limit`           | query | integer                                        | No       | Maximum number of items to return per page                                                                                   |
| `offset`          | query | integer                                        | No       | Number of items to skip before starting to return results                                                                    |
| `status`          | query | string                                         | No       | Filter by ticket status. Can be a single status or comma-separated list. Example: `status=open` or `status=open,in_progress` |
| `dept_id`         | query | string (uuid)                                  | No       | Filter by department UUID                                                                                                    |
| `requestor_email` | query | string (email)                                 | No       | Filter by requestor's email address                                                                                          |
| `assignee_email`  | query | string (email)                                 | No       | Filter by assignee's email address                                                                                           |
| `created_after`   | query | string (date-time)                             | No       | Filter tickets created after this timestamp (ISO 8601 format)                                                                |
| `created_before`  | query | string (date-time)                             | No       | Filter tickets created before this timestamp (ISO 8601 format)                                                               |
| `modified_after`  | query | string (date-time)                             | No       | Filter tickets modified after this timestamp (ISO 8601 format)                                                               |
| `modified_before` | query | string (date-time)                             | No       | Filter tickets modified before this timestamp (ISO 8601 format)                                                              |
| `ordering`        | query | `created`, `-created`, `modified`, `-modified` | No       | Field to sort results by. Prefix with `-` for descending order. Example: `ordering=-created` for newest first.               |
| `include_deleted` | query | boolean                                        | No       | Include deleted tickets in results.                                                                                          |

**Responses:** `200` Successful response with paginated list of tickets · `400` Invalid request parameters or body · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/tickets" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### Create a ticket

`POST /v1/tickets` · needs `tickets:write`

Create a new ticket in your organization. The requestor is identified by
their email address and is created automatically if they don't already
exist.

The response contains the full ticket, including its comments and, when
your workspace is connected to an external ticketing system (such as
Jira), the linked `external_ticket_id` and `external_ticket_url`. These
reference fields are usually returned right away, but can be `null` if
your workspace isn't set up to create an external ticket for this
request, or if the external system couldn't be reached in time. When
they're `null`, fetch the ticket again with `GET /tickets/{ticket_id}`
to retrieve them once they become available.

| Parameter         | In     | Type   | Required | Description                                                                                                                                                                                                                                             |
| ----------------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | header | string | No       | Optional idempotency key for safe retries of write operations. If provided, the server caches the response and returns it for subsequent requests with the same key and API key within 24 hours. Must be at most 255 characters. UUIDs are recommended. |

**Request body**

| Field             | Type           | Required | Description                                                                                                                                                                                                          |
| ----------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`           | string         | No       | Optional title (will be auto-generated if not provided)                                                                                                                                                              |
| `request_text`    | string         | Yes      | Detailed description of the request or issue (required)                                                                                                                                                              |
| `requestor_email` | string (email) | Yes      | Email address of the person requesting help (required)                                                                                                                                                               |
| `requestor_name`  | string         | No       | Display name of the requestor (optional)                                                                                                                                                                             |
| `dept_id`         | string (uuid)  | No       | UUID of the department to assign the ticket to (will be auto-assigned if not provided)                                                                                                                               |
| `runbook_id`      | string (uuid)  | No       | Stable UUID of a runbook to force-match. When provided, only this runbook is attached and normal runbook matching is skipped. Returns 422 if the runbook does not belong to your organization.                       |
| `assignee_email`  | string (email) | No       | Email address of the user to assign the ticket to (optional)                                                                                                                                                         |
| `notify_via_dm`   | boolean        | No       | If true, send the requestor a Slack DM to continue the request over DM. Requires the requestor's email to map to a linked Slack identity; otherwise the ticket is created without a DM.                              |
| `escalate`        | boolean        | No       | If true, create the ticket already escalated to human support: it is tagged "Escalated", moves to `waiting_for_support`, and the AI agent is disabled so it never responds. Cannot be combined with `notify_via_dm`. |

**Responses:** `201` Ticket created successfully · `400` Invalid request parameters or body · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `409` A request with this idempotency key is currently being processed · `422` Request was well-formed but contains semantic errors · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X POST "https://api.tryrisotto.com/v1/tickets" \
  -H "Authorization: Bearer $RISOTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

### Get a ticket

`GET /v1/tickets/{ticket_id}` · needs `tickets:read`

Retrieve details of a specific ticket by its ticket ID (e.g., "IT-123").

| Parameter   | In   | Type   | Required | Description                                                                                                                         |
| ----------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id` | path | string | Yes      | The ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration. |

**Responses:** `200` Successful response with ticket details · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/tickets/<ticket_id>" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### Update a ticket

`PATCH /v1/tickets/{ticket_id}` · needs `tickets:write`

Update an existing ticket. Only provided fields will be updated.

**Status Transitions**:

- `open` can transition to: `in_progress`, `paused`, `resolved`, `closed`
- `in_progress` can transition to: `paused`, `resolved`, `closed`, `waiting_for_response`, `waiting_for_support`
- `waiting_for_response` can transition to: `open`, `in_progress`, `resolved`, `closed`
- `waiting_for_support` can transition to: `in_progress`, `resolved`, `closed`
- `waiting_for_approval` can transition to: `resolved`, `closed`
- `paused` can transition to: `open`, `in_progress`, `resolved`, `closed`
- `resolved` can transition to: `open` (reopen), `closed`
- `closed` cannot transition to any other status via API

`waiting_for_approval` reflects an inflight approval flow. It is set
only by internal approval processes and cannot be set via the API. A
ticket holding it may only be closed out (`resolved` or `closed`,
which ends the approval); any other move is reserved for the
approval flow.

| Parameter         | In     | Type   | Required | Description                                                                                                                                                                                                                                             |
| ----------------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id`       | path   | string | Yes      | The ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration.                                                                                                                     |
| `Idempotency-Key` | header | string | No       | Optional idempotency key for safe retries of write operations. If provided, the server caches the response and returns it for subsequent requests with the same key and API key within 24 hours. Must be at most 255 characters. UUIDs are recommended. |

**Request body**

| Field            | Type                                                                                                                         | Required | Description                                                                 |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `title`          | string                                                                                                                       | No       | Updated title                                                               |
| `status`         | `open`, `in_progress`, `waiting_for_response`, `waiting_for_support`, `waiting_for_approval`, `paused`, `resolved`, `closed` | No       | Current status of the ticket                                                |
| `assignee_email` | string (email)                                                                                                               | No       | Email address of the user to assign the ticket to. Set to null to unassign. |

**Responses:** `200` Ticket updated successfully · `400` Invalid request parameters or body · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `409` A request with this idempotency key is currently being processed · `422` Request was well-formed but contains semantic errors · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X PATCH "https://api.tryrisotto.com/v1/tickets/<ticket_id>" \
  -H "Authorization: Bearer $RISOTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

### Delete a ticket

`DELETE /v1/tickets/{ticket_id}` · needs `tickets:delete`

Delete a ticket. Deleted tickets are excluded from list results by default.

| Parameter   | In   | Type   | Required | Description                                                                                                                         |
| ----------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id` | path | string | Yes      | The ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration. |

**Responses:** `204` Ticket deleted successfully · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X DELETE "https://api.tryrisotto.com/v1/tickets/<ticket_id>" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

## Comments

### List ticket comments

`GET /v1/tickets/{ticket_id}/comments` · needs `tickets:read`

Retrieve a paginated list of comments for a specific ticket.
Internal comments are excluded by default unless `include_internal=true` is specified.

| Parameter          | In    | Type    | Required | Description                                                                                                                         |
| ------------------ | ----- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id`        | path  | string  | Yes      | The ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration. |
| `limit`            | query | integer | No       | Maximum number of items to return per page                                                                                          |
| `offset`           | query | integer | No       | Number of items to skip before starting to return results                                                                           |
| `include_internal` | query | boolean | No       | Include internal comments in the response                                                                                           |

**Responses:** `200` Successful response with paginated list of comments · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/tickets/<ticket_id>/comments" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### Add a comment

`POST /v1/tickets/{ticket_id}/comments` · needs `tickets:write`

Add a new comment to a ticket.

| Parameter         | In     | Type   | Required | Description                                                                                                                                                                                                                                             |
| ----------------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id`       | path   | string | Yes      | The ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration.                                                                                                                     |
| `Idempotency-Key` | header | string | No       | Optional idempotency key for safe retries of write operations. If provided, the server caches the response and returns it for subsequent requests with the same key and API key within 24 hours. Must be at most 255 characters. UUIDs are recommended. |

**Request body**

| Field          | Type           | Required | Description                                                                                                  |
| -------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `content`      | string         | Yes      | The comment text                                                                                             |
| `is_internal`  | boolean        | No       | Whether this is an internal note (not visible to requestor)                                                  |
| `author_email` | string (email) | No       | Email address of the comment author. If not provided, the comment will be attributed to the API integration. |
| `author_name`  | string         | No       | Display name of the comment author. Used when creating a new user identity.                                  |

**Responses:** `201` Comment created successfully · `400` Invalid request parameters or body · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `409` A request with this idempotency key is currently being processed · `422` Request was well-formed but contains semantic errors · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X POST "https://api.tryrisotto.com/v1/tickets/<ticket_id>/comments" \
  -H "Authorization: Bearer $RISOTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

## Departments

### List departments

`GET /v1/departments` · needs `tickets:read`

Retrieve a paginated list of departments for your organization.
Results are ordered alphabetically by name.

| Parameter | In    | Type    | Required | Description                                               |
| --------- | ----- | ------- | -------- | --------------------------------------------------------- |
| `limit`   | query | integer | No       | Maximum number of items to return per page                |
| `offset`  | query | integer | No       | Number of items to skip before starting to return results |

**Responses:** `200` Successful response with paginated list of departments · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/departments" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

## Runbooks

### List a ticket's runbook history

`GET /v1/tickets/{ticket_id}/runbooks` · needs `runbooks:read`

Return the runbook history for a ticket — every runbook that was
matched against this ticket, in creation order. `applied_at` is
null for rows the agent matched but did not act on, and populated
with a timestamp + `reason` for rows the agent followed.

| Parameter   | In   | Type   | Required | Description                                                                                                                         |
| ----------- | ---- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id` | path | string | Yes      | The ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration. |

**Responses:** `200` Successful response with the ticket's runbook history · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/tickets/<ticket_id>/runbooks" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### List runbooks

`GET /v1/runbooks` · needs `runbooks:read`

Retrieve a paginated list of runbooks for your organization, with
filtering and ordering.

| Parameter    | In    | Type                                                                  | Required | Description                                                                        |
| ------------ | ----- | --------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `limit`      | query | integer                                                               | No       | Maximum number of items to return per page                                         |
| `offset`     | query | integer                                                               | No       | Number of items to skip before starting to return results                          |
| `search`     | query | string                                                                | No       | Substring matched against `title`, `conditions`, and `content` (case-insensitive). |
| `enabled`    | query | boolean                                                               | No       | Filter to enabled (`true`) or disabled (`false`) runbooks.                         |
| `match_type` | query | `semantic`, `department`, `system`                                    | No       | Filter by match type.                                                              |
| `dept_id`    | query | string (uuid)                                                         | No       | Filter by department UUID                                                          |
| `ordering`   | query | `title`, `-title`, `created`, `-created`, `dept__name`, `-dept__name` | No       | Field to sort runbooks by. Prefix with `-` for descending order.                   |

**Responses:** `200` Successful response with paginated list of runbooks · `400` Invalid request parameters or body · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/runbooks" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### Create a runbook

`POST /v1/runbooks` · needs `runbooks:write`

Create a new runbook. Triggers indexing when `enabled=true` and
`match_type="semantic"`. Department-matched runbooks require
`dept_id` and conflict with any other enabled department-matched
runbook on the same department.

**Request body**

| Field        | Type                               | Required | Description                                                                                                                                                          |
| ------------ | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`      | string                             | Yes      | Runbook title.                                                                                                                                                       |
| `content`    | string                             | Yes      | Instructions the agent will follow.                                                                                                                                  |
| `conditions` | string                             | No       | When the runbook should match (free-text criteria). Ignored when `match_type=department`.                                                                            |
| `enabled`    | boolean                            | No       | Whether the runbook is active.                                                                                                                                       |
| `match_type` | `semantic`, `department`, `system` | No       | How this runbook matches incoming tickets. `department` requires `dept_id`. `system` takes no matching criteria: a system attaches it by naming it via `runbook_id`. |
| `dept_id`    | string (uuid)                      | No       | UUID of the department to scope this runbook to. Required when `match_type=department`.                                                                              |
| `tool_ids`   | array of string                    | No       | Tool references the runbook may invoke. Mix of OrgTool UUIDs and `core_*` tool names.                                                                                |

**Responses:** `201` Runbook created successfully · `400` Invalid request parameters or body · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X POST "https://api.tryrisotto.com/v1/runbooks" \
  -H "Authorization: Bearer $RISOTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

### Get a runbook

`GET /v1/runbooks/{runbook_id}` · needs `runbooks:read`

Retrieve a runbook's current version by UUID.

| Parameter    | In   | Type          | Required | Description         |
| ------------ | ---- | ------------- | -------- | ------------------- |
| `runbook_id` | path | string (uuid) | Yes      | The runbook's UUID. |

**Responses:** `200` Successful response with runbook details · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/runbooks/<runbook_id>" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### Update a runbook

`PATCH /v1/runbooks/{runbook_id}` · needs `runbooks:write`

Partial update. Only provided fields are changed. Pass
`?confirm_enable=true` to bypass the 409 returned when enabling
a duplicated runbook whose department + conditions still match
the source.

| Parameter        | In    | Type          | Required | Description                                                                                                                                             |
| ---------------- | ----- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runbook_id`     | path  | string (uuid) | Yes      | The runbook's UUID.                                                                                                                                     |
| `confirm_enable` | query | boolean       | No       | When set to `true`, bypasses the 409 conflict raised when enabling a duplicated runbook whose department and conditions still match the source runbook. |

**Request body**

| Field        | Type                               | Required | Description |
| ------------ | ---------------------------------- | -------- | ----------- |
| `title`      | string                             | No       |             |
| `content`    | string                             | No       |             |
| `conditions` | string                             | No       |             |
| `enabled`    | boolean                            | No       |             |
| `match_type` | `semantic`, `department`, `system` | No       |             |
| `dept_id`    | string (uuid)                      | No       |             |
| `tool_ids`   | array of string                    | No       |             |

**Responses:** `200` Runbook updated successfully · `400` Invalid request parameters or body · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `409` Enabling a duplicated runbook whose department + conditions still match the source. Resubmit with `?confirm_enable=true` to override. · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X PATCH "https://api.tryrisotto.com/v1/runbooks/<runbook_id>" \
  -H "Authorization: Bearer $RISOTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

### Delete a runbook

`DELETE /v1/runbooks/{runbook_id}` · needs `runbooks:write`

Soft-delete a runbook. The version history remains available via
the `versions` sub-resource.

| Parameter    | In   | Type          | Required | Description         |
| ------------ | ---- | ------------- | -------- | ------------------- |
| `runbook_id` | path | string (uuid) | Yes      | The runbook's UUID. |

**Responses:** `204` Runbook deleted successfully · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X DELETE "https://api.tryrisotto.com/v1/runbooks/<runbook_id>" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### List runbook revisions

`GET /v1/runbooks/{runbook_id}/versions` · needs `runbooks:read`

Return every version of a runbook, newest first. Includes
soft-deleted prior versions so callers can inspect the audit
trail.

| Parameter    | In   | Type          | Required | Description         |
| ------------ | ---- | ------------- | -------- | ------------------- |
| `runbook_id` | path | string (uuid) | Yes      | The runbook's UUID. |

**Responses:** `200` Successful response with the runbook's version history · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/runbooks/<runbook_id>/versions" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

### Duplicate a runbook

`POST /v1/runbooks/{runbook_id}/duplicate` · needs `runbooks:write`

Create a copy of an existing runbook. The copy starts disabled
with a ` (Copy)`-suffixed title and `duplicated_from_runbook_id`
set to the source's `runbook_id`.

| Parameter    | In   | Type          | Required | Description         |
| ------------ | ---- | ------------- | -------- | ------------------- |
| `runbook_id` | path | string (uuid) | Yes      | The runbook's UUID. |

**Responses:** `201` Runbook duplicated successfully · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `404` Requested resource not found · `429` Rate limit exceeded · `500` Internal server error

```bash
curl -X POST "https://api.tryrisotto.com/v1/runbooks/<runbook_id>/duplicate" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

## Audit events

### List audit-log events

`GET /v1/audit-events` · needs `audit:read`

Retrieve a paginated list of organization configuration-change audit
events. Designed for streaming the Risotto audit trail into a SIEM
(such as Panther): poll with `created_after=<last_seen>` plus
`ordering=created` to fetch new events incrementally. `created_after`
is inclusive (at-least-once delivery, so no event is ever dropped at a
timestamp boundary) — dedupe by event `id` when advancing the window.
Results carry a stable `id` tiebreaker so pagination is deterministic
even when events share a timestamp.

Each event includes the acting user and a short `summary` of what
changed. Pass `include_changes=true` to also receive the full
field-level before/after diff in `changes`.

| Parameter         | In    | Type                  | Required | Description                                                                                                                                                                                                                                              |
| ----------------- | ----- | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`           | query | integer               | No       | Maximum number of items to return per page                                                                                                                                                                                                               |
| `offset`          | query | integer               | No       | Number of items to skip before starting to return results                                                                                                                                                                                                |
| `event`           | query | string                | No       | Filter by exact event key (e.g. `org_runbook_updated`).                                                                                                                                                                                                  |
| `created_after`   | query | string (date-time)    | No       | Filter to events created at or after this timestamp (ISO 8601, inclusive). The inclusive bound means events sharing the boundary timestamp are never dropped, making incremental polling at-least-once — dedupe by event `id` when advancing the window. |
| `created_before`  | query | string (date-time)    | No       | Filter to events created before this timestamp (ISO 8601 format).                                                                                                                                                                                        |
| `ordering`        | query | `created`, `-created` | No       | Sort order by creation time. Use `created` for oldest-first (recommended for incremental polling) or `-created` for newest-first.                                                                                                                        |
| `include_changes` | query | boolean               | No       | Include the full field-level before/after diff for each event. Defaults to false to keep the payload lightweight.                                                                                                                                        |

**Responses:** `200` Successful response with paginated list of audit events · `401` Missing or invalid API key · `403` API key lacks required scope for this operation · `429` Rate limit exceeded · `500` Internal server error

```bash
curl "https://api.tryrisotto.com/v1/audit-events" \
  -H "Authorization: Bearer $RISOTTO_API_KEY"
```

Source: https://www.tryrisotto.com/docs/api-reference
