# Build on Risotto. Keep IT's approvals.

Risotto has a public API, signed webhooks, an MCP server and script tools that run your TypeScript inside Risotto. Each one works under the same scopes, approvals and audit log as the AI agent, so what you build is something your security team can sign off on.

[Read the docs](/docs/dashboard/settings/developers/api-keys) · [Book a demo](/demo)

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

```json Webhooks
{
  "id": "evt_01H9XZ...",
  "type": "ticket.escalated",
  "created_at": "2026-07-15T17:09:41Z",
  "data": {
    "ticket_id": "TCK-1234",
    "title": "Access request for GitHub",
    "status": "waiting_for_support",
    "source": "slack",
    "requestor": {
      "email": "jordan@example.com",
      "name": "Jordan Lee"
    },
    "escalated_at": "2026-07-15T17:09:40Z",
    "reason": "Needs admin access no access rule covers."
  }
}
```

```typescript Script tool
export const input = z.object({ email: z.string() });

export const domains = { "sentry.io": "read" };

const MEMBERS =
  "https://sentry.io/api/0/organizations/acme/members/";

export default async function run({ email }) {
  const response = await http.get(MEMBERS, {
    query: { query: `email:${email}` },
    auth: { type: "bearer", token: env.SENTRY_AUTH_TOKEN },
  });
  // ...
}
```

```json MCP
{
  "mcpServers": {
    "risotto": {
      "transport": {
        "type": "http",
        "url": "https://api.tryrisotto.com/o/<org_id>/mcp"
      }
    }
  }
}
```

## Pick your way in

Risotto has four places to start, depending on which way the work flows.

| | Public API | Webhooks | Script tools | MCP server |
|---|---|---|---|---|
| Use it to | Read and change Risotto from your own code | Hear when something happens in Risotto, or start Risotto from another system | Run a fixed sequence across your systems, from inside Risotto | Work with Risotto from Claude, Cursor or your own agent |
| Signs in with | An API key with the scopes you pick | A signing secret out, an auth token in | Risotto's credential vault; your code never holds a key | Each person's own Risotto sign-in (OAuth) |
| Set up by | Org Admins and Managers | Org Admins and Managers (out), Org Admins (in) | Org Admins and Managers | Anyone in the org, within their role |
| Start here | [API keys](/docs/dashboard/settings/developers/api-keys) | [Webhooks](/docs/integrations/webhooks) | [Script tools](/docs/integrations/tools/script-tools) | [MCP server](/docs/integrations/mcp-server) |

## Call Risotto from anything that speaks HTTP

Risotto's public API lets your scripts and services create and update tickets, add comments, manage runbooks and departments, and read the audit log. Give each job its own key with only the scopes it needs: the Jira Automation rule that opens tickets gets `tickets:write`, and the nightly warehouse sync gets `tickets:read`.

- **Scoped keys.** Pick scopes for tickets, knowledge, runbooks, tools, triggers, access rules, settings, the audit log and more. Risotto stores only a hash and shows the key once.
- **A limit per key.** 1,000 requests an hour each, with `X-RateLimit-*` headers, so one busy job never slows another.
- **Errors that say what's missing.** A 403 names the scope the key needs, and the request log shows the call under its `X-Request-ID`.
- **Your SIEM, incrementally.** The audit-events API takes `created_after` and `created_before`, so each pull gets only what's new.

[API reference](/docs/api-reference) · [API keys and scopes](/docs/dashboard/settings/developers/api-keys)

```bash Create a ticket
curl -X POST "https://api.tryrisotto.com/v1/tickets" \
  -H "Authorization: Bearer $RISOTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New laptop for Sam",
    "request_text": "Sam starts Monday, needs a MacBook.",
    "requestor_email": "sam@example.com"
  }'
```

```json 403 without tickets:write
{
  "error": {
    "code": "authorization_error",
    "message": "This action requires one of the following scopes: tickets:write"
  }
}
```

## Hear from Risotto the moment something changes

Risotto sends a signed `POST` to your endpoint when a ticket is created, escalated or closed, a public comment lands, or an access request completes. Page on-call when an exec's ticket escalates, mirror closures into your warehouse, or post access outcomes to the security channel.

| Event | When it fires |
|---|---|
| `ticket.created` | A ticket is created from any request source |
| `ticket.escalated` | A ticket is escalated to a person |
| `comment.added` | A public comment is added; internal notes don't fire it |
| `ticket.closed` | A ticket reaches a final status, with how it closed |
| `access.requests.completed` | An access request resolves, granted or denied per app |

If your endpoint is down, Risotto tries 8 times over about a day, logs every attempt and lets you resend any of them. An endpoint that fails for 3 days straight is switched off, and your admins hear about it.

[Webhooks](/docs/integrations/webhooks)

```typescript Verify a delivery
import crypto from "node:crypto";

// Check that a delivery came from Risotto.
function isFromRisotto(headers, rawBody, secret) {
  const signed = [
    headers["webhook-id"],
    headers["webhook-timestamp"],
    rawBody,
  ].join(".");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("base64");
  const header = headers["webhook-signature"] ?? "";
  const received = header.split(",")[1] ?? "";
  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return (
    a.length === b.length && crypto.timingSafeEqual(a, b)
  );
}
```

```json ticket.closed
{
  "id": "evt_01H9Y4...",
  "type": "ticket.closed",
  "created_at": "2026-07-15T18:02:10Z",
  "data": {
    "ticket_id": "TCK-1234",
    "title": "Access request for GitHub",
    "status": "resolved",
    "source": "slack",
    "tags": ["Auto-Solved"],
    "resolved_at": "2026-07-15T18:02:08Z",
    "closure_state": "resolved"
  }
}
```

## Start Risotto from any system that can send a webhook

A Risotto automation can start on a webhook, so a monitoring alert, an HR tool or a form can set the agent to work. The JSON you send becomes the automation's event data, for its instructions and its tools to use. Each automation has its own URL and auth token.

[Automations](/product/automations) · [Webhook triggers](/docs/dashboard/automations#webhook-trigger)

```bash Start an automation
curl -X POST "$AUTOMATION_WEBHOOK_URL" \
  -H "$AUTOMATION_AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "alert": "disk_full",
    "host": "build-07",
    "owner": "sam@example.com"
  }'
```

## Your TypeScript, running inside Risotto

A Risotto script tool is TypeScript that chains your connected tools and any HTTPS API into one action that runs the same way every time. Publish it, and the AI agent can call it from a runbook, an automation can run it on an Okta or HR event, and an access rule can grant and remove access with it in an app with no SCIM. Write it in Script Studio, with autocomplete for every connected tool, or describe the job and let the Assistant write it.

- **Only the hosts you list.** `domains` names each host and whether the script may write to it. Anything else is refused before it leaves.
- **Keys stay in the vault.** `env.SENTRY_AUTH_TOKEN` is filled in as the request leaves Risotto. The sandbox has no network, no files and no credentials.
- **Risotto's own data, built in.** `risotto.*` reads people and tickets and comments on the ticket.

Every publish is a version, an approval covers only the version the approver saw, and every run keeps its step trace for 90 days.

[Script tools](/product/script-tools) · [Script tool templates](/library)

```typescript sentry-member-check.ts
export const input = z.object({ email: z.string() });

// Read-only: a write to sentry.io is refused.
export const domains = { "sentry.io": "read" };

const MEMBERS =
  "https://sentry.io/api/0/organizations/acme/members/";

type Input = z.infer<typeof input>;

export default async function run({ email }: Input) {
  const response = await http.get(MEMBERS, {
    query: { query: `email:${email}` },
    auth: { type: "bearer", token: env.SENTRY_AUTH_TOKEN },
  });
  if (response.status_code !== 200) {
    fail(`Sentry returned ${response.status_code}.`);
  }
  const found =
    Array.isArray(response.body) && response.body.length > 0;
  const result = found
    ? `${email} is in Sentry.`
    : `${email} isn't in Sentry.`;

  const ticket = await risotto.get_ticket();
  if (ticket !== null) {
    await risotto.add_ticket_comment({ comment: result });
  }
  return result;
}
```

## Point Claude Code at your service desk

Risotto's MCP server lets Claude, Claude Code, Cursor and your own agents search and update tickets, see exactly what the AI agent did on one, draft runbook changes, run tools and read the audit log. Each person connects with their own Risotto sign-in and gets only the tools their role allows, so a member's Cursor can update tickets but can't change settings. A scheduled job that can't sign in can send an API key, and it sees only the tools that key's scopes allow.

Changes come back as drafts: ask for a runbook edit and it arrives with tracked changes, and the live runbook stays as it is until someone approves it in the dashboard. It works the other way too: connect your own MCP servers to Risotto, and their tools join your runbooks, automations and script tools.

[MCP server and API](/product/mcp) · [Connect a client](/docs/integrations/mcp-server)

```text Claude Code
> Why did Risotto close IT-482 without granting Figma access?

  risotto · get_ticket("IT-482")
  risotto · get_ticket_agent_activity("IT-482")

The agent matched the request to your Figma access runbook,
since Jordan Lee asked for an Editor seat. That runbook needs
manager approval, and Morgan Blake declined it at 10:14 AM.
Risotto told Jordan in Slack, then closed the ticket without
granting access.
```

## The same rules for code as for people

Risotto applies one permission model to everything you build on it.

- **One set of scopes.** API keys and MCP connections are gated by the same scopes.
- **A role caps every MCP connection.** When someone's role changes, their Claude follows it.
- **Keys shown once, stored as a hash.** Revoke one without touching the others.
- **Writes wait for approval.** Script tools and imported MCP tools ask first, until you change that.
- **Secrets in the vault.** Write-only, and never in code, chat or a run trace.
- **Everything is logged.** The request log holds every API and MCP call; the audit log holds every change.

[Security and trust](/security)

## What teams build

Risotto's four ways in combine. A few jobs teams wire up first:

- [Page on-call when an exec's ticket escalates](/docs/integrations/webhooks): a `ticket.escalated` webhook calls your paging service. Webhooks.
- [Open Risotto tickets from Jira Automation](/docs/dashboard/settings/developers/api-keys): a rule calls `POST /v1/tickets` with a `tickets:write` key. API.
- [Stream configuration changes to your SIEM](/docs/api-reference): pull the audit-events API every few minutes. API.
- [Grant and remove access in an app with no SCIM](/library/script-tools/sentry-org-access): a script tool on an access rule runs after approval and again when access ends. Script tools.
- [Turn a monitoring alert into a fixed ticket](/docs/dashboard/automations#webhook-trigger): the alert starts an automation, and the agent runs a script tool and logs it. Webhooks and script tools.
- [Triage the morning queue from Claude Code](/docs/integrations/mcp-server): "Which open tickets mention the VPN this week?" MCP.

## Frequently asked questions

### Does Risotto have a public API?

Yes. Risotto's REST API at `api.tryrisotto.com/v1` covers tickets, comments, departments, runbooks and audit events, with API keys scoped to each job. [API reference](/docs/api-reference)

### Does Risotto have webhooks?

Yes. Risotto sends signed webhooks when a ticket is created, escalated or closed, a public comment is added, or an access request completes. Inbound, any system that can send a `POST` can start a Risotto automation. [Webhooks](/docs/integrations/webhooks)

### How do I verify a Risotto webhook?

Compute an HMAC-SHA256 of `{Webhook-Id}.{Webhook-Timestamp}.{body}` with your endpoint's signing secret, base64-encode it and compare it with the `Webhook-Signature` header in constant time. Check that the timestamp is recent to stop replays. [Verifying signatures](/docs/integrations/webhooks#verifying-signatures)

### Can I write code that runs inside Risotto?

Yes. Risotto script tools are TypeScript that runs in a fresh sandbox with no network and no credentials; calls go through Risotto, only to the hosts and tools your code declares. Write them yourself or have the Assistant write them. [Script tools](/product/script-tools)

### Can I connect Claude Code or Cursor to Risotto?

Yes. Paste your org's MCP server URL into Claude Code, Claude Desktop, Cursor or any MCP client that supports OAuth, and sign in to Risotto. You get the tools your role allows. [MCP server](/docs/integrations/mcp-server)

### Is there a rate limit on the Risotto API?

Yes. Each Risotto API key can make 1,000 requests an hour, and every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Each key has its own limit. [Rate limits](/docs/dashboard/settings/developers/api-keys#rate-limits)

## Build something IT will approve

[Read the docs](/docs/dashboard/settings/developers/api-keys) · [Book a demo](/demo)

Source: https://www.tryrisotto.com/developers
