# REST API reference
> Every REST operation by area, with its permission, fields and examples, plus authentication, errors, rate limits and pagination.
Audience: Developers and integration builders
Kind: Reference
Canonical: https://shuffl.ai/docs/api-reference
## Authentication
The base URL is https://shuffl.ai/api/v1. Send a workspace API key in the Authorization header as a bearer token, over HTTPS, on every request.
A key belongs to one workspace and acts as the person who created it, with their current role. Each operation also needs its own permission on the key.
GET /api/v1/team and GET /api/v1/permissions work with any valid key, so start with them to check the key and see what it can do.
### Other credentials
- A company key (shuffl_company_), sent the same way, calls only the Company settings operations under /api/v1/company. A workspace key can’t call those.
- In the SDK, new Shuffl takes a company key and calls shuffl.company. In the CLI, use shuffl login --company or SHUFFL_COMPANY_KEY.
- MCP OAuth tokens work only with the MCP server.
HTTP:
```sh
curl https://shuffl.ai/api/v1/team \
-H "Authorization: Bearer $SHUFFL_API_KEY"
```
- [Create a workspace key](https://shuffl.ai/docs/sdk#credentials)
- [Company keys](https://shuffl.ai/docs/api-permissions#company-keys)
- [Company settings API](https://shuffl.ai/docs/api-reference/company)
- [@shuffl/sdk on npm](https://www.npmjs.com/package/@shuffl/sdk)
- [@shuffl/cli on npm](https://www.npmjs.com/package/@shuffl/cli)
## Requests and responses
Most operations are POST requests with a JSON body under /api/v1/manage. A few reads are GET requests with query parameters, and a few program and run operations take an id in the path.
Each operation’s page shows its method, path and fields. Responses are JSON and never cached.
Call the API from a server, a script or the CLI. Cross-origin browser requests aren’t allowed.
### Writes
- Writes take a requestKey and return {receipt, result}.
- Send a new key for each thing you mean to do, and the same key only to retry it. A retry returns the first receipt with result null.
- Sensitive writes also need confirm set to the operation name. Their pages say so.
- [OpenAPI document](https://shuffl.ai/api/v1/openapi.json)
- [How management writes work](https://shuffl.ai/docs/sdk#writes)
## Errors
A failed request returns an HTTP error status and a JSON body with code, status and message. Branch on code, not on message: the message is for people and can change. Some errors add a data object with details.
Don’t retry 400, 401, 403 or 404 without changing something. After a network failure or a 500, retry with the same input and request key, or read the resource first to see whether the write happened.
### Error codes
- `BAD_REQUEST` (400): the input does not match the operation’s schema. The message names the field.
- `UNAUTHORIZED` (401): the key is missing, expired, revoked or from another deployment. The response carries `WWW-Authenticate: Bearer`.
- `FORBIDDEN` (403): the key lacks this operation’s permission, or the key’s owner can’t do this in the app.
- `NOT_FOUND` (404): the resource or operation doesn’t exist in this workspace, or you can’t see it.
- `CONFLICT` (409): the expectedRevision is out of date, or a request key was reused with different input.
- `PRECONDITION_FAILED` (412): the workspace isn’t ready for this yet, such as a program with no channel.
- `TOO_MANY_REQUESTS` (429): the key is over its rate limit. Wait for `Retry-After`.
- `INTERNAL_SERVER_ERROR` (500): something failed on Shuffl’s side. Retry later with the same request key.
Error response:
```json
{
"defined": false,
"code": "FORBIDDEN",
"status": 403,
"message": "API access is unavailable."
}
```
## Rate limits
Each API key can make 120 requests a minute, shared between HTTP and MCP. The window starts with the first request. An MCP OAuth connection gets 60 a minute, and each company key gets 120.
Over the limit, the API answers 429 with code TOO_MANY_REQUESTS and a Retry-After header in seconds. Wait that long before the next request. Spread scheduled jobs out rather than retrying in a loop.
## Pagination
Paginated lists take limit (1 to 100, 25 by default) and cursor, and return items and nextCursor. Pass nextCursor back as cursor until it is null.
Every other list returns all its results in one response.
### Paginated operations
- groups.automationRuns
- identities.slackAccounts
- knowledge.connections.browse
- knowledge.sources.list
- programs.list
- users.list
- users.managerHistory
- company.members.list
HTTP:
```sh
curl "https://shuffl.ai/api/v1/users?limit=100" \
-H "Authorization: Bearer $SHUFFL_API_KEY"
# { "items": [...], "nextCursor": "..." }
curl "https://shuffl.ai/api/v1/users?limit=100&cursor=" \
-H "Authorization: Bearer $SHUFFL_API_KEY"
```
- [Export people](https://shuffl.ai/docs/sdk-cookbook#export-people)
## Webhooks
Shuffl can call your server when something changes, so you don’t have to poll the list operations.
Add an endpoint in Settings → API keys and webhooks → Webhooks or with webhooks.create. Shuffl sends a signed request for each event it subscribes to.
- [Set up webhooks](https://shuffl.ai/docs/webhooks)
## Operations by area
418 operations in 43 areas. Each page is generated from the OpenAPI document and lists every operation’s method, path, permission, request and response fields, with an HTTP, SDK and CLI example.
- [API keys (3)](https://shuffl.ai/docs/api-reference/credentials)
- [Badges (15)](https://shuffl.ai/docs/api-reference/badges)
- [Celebrations (16)](https://shuffl.ai/docs/api-reference/celebrations)
- [Command receipts (1)](https://shuffl.ai/docs/api-reference/commands)
- [Communities (18)](https://shuffl.ai/docs/api-reference/communities)
- [Company settings (9)](https://shuffl.ai/docs/api-reference/company)
- [Connections programs (14)](https://shuffl.ai/docs/api-reference/programs)
- [Connections rounds (9)](https://shuffl.ai/docs/api-reference/runs)
- [Departments (1)](https://shuffl.ai/docs/api-reference/units)
- [Directory sync (8)](https://shuffl.ai/docs/api-reference/sync)
- [Employee access (5)](https://shuffl.ai/docs/api-reference/access)
- [Exports (1)](https://shuffl.ai/docs/api-reference/exports)
- [Get started (7)](https://shuffl.ai/docs/api-reference/get-started)
- [Groups (28)](https://shuffl.ai/docs/api-reference/groups)
- [Home (5)](https://shuffl.ai/docs/api-reference/home)
- [HR digest and nudges (8)](https://shuffl.ai/docs/api-reference/digest)
- [HR requests (15)](https://shuffl.ai/docs/api-reference/hr)
- [Integrations (1)](https://shuffl.ai/docs/api-reference/integrations)
- [Invitations (6)](https://shuffl.ai/docs/api-reference/invitations)
- [Knowledge (36)](https://shuffl.ai/docs/api-reference/knowledge)
- [Linked accounts (6)](https://shuffl.ai/docs/api-reference/identities)
- [Manager context (1)](https://shuffl.ai/docs/api-reference/manager)
- [Mello conversations (5)](https://shuffl.ai/docs/api-reference/assistant)
- [Mentorship (21)](https://shuffl.ai/docs/api-reference/mentorship)
- [Network (6)](https://shuffl.ai/docs/api-reference/network)
- [Notifications (2)](https://shuffl.ai/docs/api-reference/notifications)
- [Operations and audit (4)](https://shuffl.ai/docs/api-reference/operations)
- [People (19)](https://shuffl.ai/docs/api-reference/users)
- [Permissions (1)](https://shuffl.ai/docs/api-reference/permissions)
- [Playbooks (37)](https://shuffl.ai/docs/api-reference/playbooks)
- [Praise (13)](https://shuffl.ai/docs/api-reference/praise)
- [Profiles (10)](https://shuffl.ai/docs/api-reference/profiles)
- [Pulse (24)](https://shuffl.ai/docs/api-reference/pulse)
- [Reminders (4)](https://shuffl.ai/docs/api-reference/reminders)
- [Reports and insights (12)](https://shuffl.ai/docs/api-reference/reports)
- [Requests Mello filed (1)](https://shuffl.ai/docs/api-reference/actions)
- [Shuffl support (6)](https://shuffl.ai/docs/api-reference/support)
- [Slack channels (1)](https://shuffl.ai/docs/api-reference/channels)
- [Time off (1)](https://shuffl.ai/docs/api-reference/time-off)
- [Webhooks (12)](https://shuffl.ai/docs/api-reference/webhooks)
- [What Mello can do (5)](https://shuffl.ai/docs/api-reference/capabilities)
- [Workspace (18)](https://shuffl.ai/docs/api-reference/teams)
- [Workspace launch (3)](https://shuffl.ai/docs/api-reference/team)
## Related guides
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [SDK and CLI recipes](https://shuffl.ai/docs/sdk-cookbook)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
Agent documentation index: https://shuffl.ai/llms.txt