Docs

Developers / API

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: 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.
  • 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.
  • Request IDs: every response has an X-Request-ID header. Find the call under the same ID in the 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.

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.

ParameterInTypeRequiredDescription
limitqueryintegerNoMaximum number of items to return per page
offsetqueryintegerNoNumber of items to skip before starting to return results
statusquerystringNoFilter by ticket status. Can be a single status or comma-separated list. Example: status=open or status=open,in_progress
dept_idquerystring (uuid)NoFilter by department UUID
requestor_emailquerystring (email)NoFilter by requestor's email address
assignee_emailquerystring (email)NoFilter by assignee's email address
created_afterquerystring (date-time)NoFilter tickets created after this timestamp (ISO 8601 format)
created_beforequerystring (date-time)NoFilter tickets created before this timestamp (ISO 8601 format)
modified_afterquerystring (date-time)NoFilter tickets modified after this timestamp (ISO 8601 format)
modified_beforequerystring (date-time)NoFilter tickets modified before this timestamp (ISO 8601 format)
orderingquerycreated, -created, modified, -modifiedNoField to sort results by. Prefix with - for descending order. Example: ordering=-created for newest first.
include_deletedquerybooleanNoInclude 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.

ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoOptional 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

FieldTypeRequiredDescription
titlestringNoOptional title (will be auto-generated if not provided)
request_textstringYesDetailed description of the request or issue (required)
requestor_emailstring (email)YesEmail address of the person requesting help (required)
requestor_namestringNoDisplay name of the requestor (optional)
dept_idstring (uuid)NoUUID of the department to assign the ticket to (will be auto-assigned if not provided)
runbook_idstring (uuid)NoStable 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_emailstring (email)NoEmail address of the user to assign the ticket to (optional)
notify_via_dmbooleanNoIf 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.
escalatebooleanNoIf 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").

ParameterInTypeRequiredDescription
ticket_idpathstringYesThe 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:

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

ParameterInTypeRequiredDescription
ticket_idpathstringYesThe ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration.
Idempotency-KeyheaderstringNoOptional 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

FieldTypeRequiredDescription
titlestringNoUpdated title
statusopen, in_progress, waiting_for_response, waiting_for_support, waiting_for_approval, paused, resolved, closedNoCurrent status of the ticket
assignee_emailstring (email)NoEmail 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.

ParameterInTypeRequiredDescription
ticket_idpathstringYesThe 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.

ParameterInTypeRequiredDescription
ticket_idpathstringYesThe ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration.
limitqueryintegerNoMaximum number of items to return per page
offsetqueryintegerNoNumber of items to skip before starting to return results
include_internalquerybooleanNoInclude 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.

ParameterInTypeRequiredDescription
ticket_idpathstringYesThe ticket identifier in PREFIX-NUMBER format (e.g., "IT-123", "HR-456"). The prefix is determined by the department configuration.
Idempotency-KeyheaderstringNoOptional 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

FieldTypeRequiredDescription
contentstringYesThe comment text
is_internalbooleanNoWhether this is an internal note (not visible to requestor)
author_emailstring (email)NoEmail address of the comment author. If not provided, the comment will be attributed to the API integration.
author_namestringNoDisplay 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.

ParameterInTypeRequiredDescription
limitqueryintegerNoMaximum number of items to return per page
offsetqueryintegerNoNumber 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.

ParameterInTypeRequiredDescription
ticket_idpathstringYesThe 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.

ParameterInTypeRequiredDescription
limitqueryintegerNoMaximum number of items to return per page
offsetqueryintegerNoNumber of items to skip before starting to return results
searchquerystringNoSubstring matched against title, conditions, and content (case-insensitive).
enabledquerybooleanNoFilter to enabled (true) or disabled (false) runbooks.
match_typequerysemantic, department, systemNoFilter by match type.
dept_idquerystring (uuid)NoFilter by department UUID
orderingquerytitle, -title, created, -created, dept__name, -dept__nameNoField 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

FieldTypeRequiredDescription
titlestringYesRunbook title.
contentstringYesInstructions the agent will follow.
conditionsstringNoWhen the runbook should match (free-text criteria). Ignored when match_type=department.
enabledbooleanNoWhether the runbook is active.
match_typesemantic, department, systemNoHow 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_idstring (uuid)NoUUID of the department to scope this runbook to. Required when match_type=department.
tool_idsarray of stringNoTool 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.

ParameterInTypeRequiredDescription
runbook_idpathstring (uuid)YesThe 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.

ParameterInTypeRequiredDescription
runbook_idpathstring (uuid)YesThe runbook's UUID.
confirm_enablequerybooleanNoWhen set to true, bypasses the 409 conflict raised when enabling a duplicated runbook whose department and conditions still match the source runbook.

Request body

FieldTypeRequiredDescription
titlestringNo
contentstringNo
conditionsstringNo
enabledbooleanNo
match_typesemantic, department, systemNo
dept_idstring (uuid)No
tool_idsarray of stringNo

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.

ParameterInTypeRequiredDescription
runbook_idpathstring (uuid)YesThe 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.

ParameterInTypeRequiredDescription
runbook_idpathstring (uuid)YesThe 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.

ParameterInTypeRequiredDescription
runbook_idpathstring (uuid)YesThe 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.

ParameterInTypeRequiredDescription
limitqueryintegerNoMaximum number of items to return per page
offsetqueryintegerNoNumber of items to skip before starting to return results
eventquerystringNoFilter by exact event key (e.g. org_runbook_updated).
created_afterquerystring (date-time)NoFilter 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_beforequerystring (date-time)NoFilter to events created before this timestamp (ISO 8601 format).
orderingquerycreated, -createdNoSort order by creation time. Use created for oldest-first (recommended for incremental polling) or -created for newest-first.
include_changesquerybooleanNoInclude 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