Skip to main content
Endpoint · GET /ai-employees
Read-only endpoint: it returns information and changes nothing. It is not sent inside the actions array — you call it directly.
Returns the business’s runnable and active AI employees, in alphabetical order and paginated by cursor. This is where the exact name required by the actions that take an AI employee comes from: the API identifies them by name, not by id, so this catalog is how you find out which names exist before assembling an action. Each item carries its type:
  • operative — can be assigned to the conversation and also run.
  • json — can only be run one-off. Assigning it with assign_ai_employee fails with AI_EMPLOYEE_NOT_FOUND.
The catalog omits inactive and deleted AI employees. Parameters All of them are query params and none is required: with no parameters it returns the first page of the full catalog.
  • search — case-insensitive substring of the name (1 to 100 characters). The asterisk * works as a wildcard and matches any sequence of characters; % and _ are matched literally.
  • cursor — opaque cursor returned by the previous page in next_cursor. Omit it to request the first page. Do not reuse a cursor across different endpoints: even though the format is identical, each endpoint interprets it over its own data set.
  • limit — AI employees per page. Default 20, maximum 100.
To walk the whole catalog, repeat the call passing the next_cursor from the previous response until has_more is false.

​
Response

  • items — array of { name, type }.
  • next_cursor — cursor for the next page; null when has_more is false.
  • has_more — whether there are more results after this page.

​
Example

This is a read: the GET neither assigns nor runs anything, it only returns the available names so you can use them later in an action.
Errors
  • 400 — invalid query params (INVALID_REQUEST) or corrupt cursor (INVALID_CURSOR).
  • 401 — missing, malformed or invalid token (INVALID_API_TOKEN).
  • 403 — the path slug does not match the token’s business (TOKEN_BUSINESS_MISMATCH).
  • 429 — rate limit exceeded (RATE_LIMIT_EXCEEDED).
  • 500 — unexpected server error (UNKNOWN_ERROR).
See the detail in Errors. The name returned by this endpoint is the one that goes in the ai_employee field of the actions that take an AI employee: Assign and unassign AI employee, Run AI employee and AI employee assistance. Remember that persistent assignment only accepts employees of type operative.