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, for code generators and API clients.
Basics
- Base URL:
https://api.tryrisotto.com/v1 - Authentication: an API key in the
Authorization: Bearerheader, or inX-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-RemainingandX-RateLimit-Reset. See Rate limits. - Pagination: list endpoints take
limitandoffset, and returncount,nextandpreviouswith the results. - Errors: JSON with an
errorobject that holds acode, amessageanddetails. A403(authorization_error) names the scope the key is missing. See Errors. - Request IDs: every response has an
X-Request-IDheader. Find the call under the same ID in the request log. - Retries:
POST /ticketstakes anIdempotency-Keyheader, so a retry doesn't create a second ticket.
Risotto can also send events to your systems. See 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
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
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
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:
opencan transition to:in_progress,paused,resolved,closedin_progresscan transition to:paused,resolved,closed,waiting_for_response,waiting_for_supportwaiting_for_responsecan transition to:open,in_progress,resolved,closedwaiting_for_supportcan transition to:in_progress,resolved,closedwaiting_for_approvalcan transition to:resolved,closedpausedcan transition to:open,in_progress,resolved,closedresolvedcan transition to:open(reopen),closedclosedcannot 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
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
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
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
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
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
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
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
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
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
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
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
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
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
curl "https://api.tryrisotto.com/v1/audit-events" \
-H "Authorization: Bearer $RISOTTO_API_KEY"Something wrong or missing? Report an issue · View as Markdown