Skip to content
shuffl
Get started

Searches the public product guides only. Nothing from a workspace is read, and questions are not saved.

Reference

REST API reference

Every REST operation by area, with its permission, fields and examples, plus authentication, errors, rate limits and pagination.

For Developers and integration builders

On this page

App links open your signed-in workspace. Check the selected workspace before making changes.

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
curl https://shuffl.ai/api/v1/team \
  -H "Authorization: Bearer $SHUFFL_API_KEY"

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.

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
{
  "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
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=<nextCursor>" \
  -H "Authorization: Bearer $SHUFFL_API_KEY"

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.

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.

Was this guide helpful?