> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frayme.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The partner-facing Case API — authentication, scopes, and a map of every endpoint.

The **Case API** is how partner systems interact with Frayme: submit cases, poll
for decisions, act on paused workflow nodes, and deliver external callbacks.

<Info>
  Today, API keys, the workflow IDs you may submit cases to, and webhook
  configuration (URL, signing secret) are all provisioned for you by the Frayme
  team. In the future, both will be self-served from the Frayme portal.
</Info>

For a narrative walkthrough of a full integration — from first submission to
handling decisions — start with the [Integration guide](/integration/guide).
This section is the field-level reference for each endpoint.

## Base URL

Every path below is relative to your environment's base URL:

| Environment | Base URL                            |
| ----------- | ----------------------------------- |
| Production  | `https://core.us.api.frayme.io`     |
| Staging     | `https://core.us.api.stg.frayme.io` |

## Authentication

All Case API calls require a tenant-scoped API key, sent on every request in the
`X-API-Key` header:

```http theme={null}
X-API-Key: <your-api-key>
```

No other authentication mechanism is supported on the partner endpoints. Your
tenant is derived from the key — do not send `tenantId` in a request body; it is
ignored.

## Scopes

Each key carries one or more scopes. Every endpoint lists the scope it requires.

| Scope            | Grants                                                             |
| ---------------- | ------------------------------------------------------------------ |
| `cases:write`    | Submit new cases (`POST /cases`)                                   |
| `cases:read`     | Read a case, list its paused nodes, and list its durable actions   |
| `cases:callback` | Deliver an external callback, or invoke a pending / durable action |

## Idempotency

`POST /cases` accepts an optional `idempotencyKey`. If you resubmit with a key
that already exists, the existing case is returned with `200 OK` instead of a
new case being created (`201 Created`). Durable and pending actions are **not**
idempotent — each invocation is an independent vendor call.

## Endpoints

Each endpoint has its own page under **Cases API** in the sidebar.

| Action                       | Method and path                                    | Scope            |
| ---------------------------- | -------------------------------------------------- | ---------------- |
| Submit a case                | `POST /cases`                                      | `cases:write`    |
| Get a case                   | `GET /cases/{caseId}`                              | `cases:read`     |
| List paused nodes            | `GET /cases/{caseId}/pending`                      | `cases:read`     |
| Invoke a pending action      | `POST /pending/{handle}/actions/{actionId}`        | `cases:callback` |
| List durable actions         | `GET /cases/{caseId}/actions`                      | `cases:read`     |
| Invoke a durable action      | `POST /cases/{caseId}/actions/{brokerId}/{action}` | `cases:callback` |
| Deliver an external callback | `POST /cases/{caseId}/callbacks/{callbackRef}`     | `cases:callback` |

<Note>
  These pages are **reference only** — there is no interactive request runner,
  since calling the API requires a provisioned key against your own tenant. Copy
  the request examples and run them against your Frayme-provided base URL.
</Note>

Decisions are also pushed to you asynchronously. See [Webhooks](/api-reference/webhooks)
for the events, payload shapes, and signature verification.