---
title: "Agents API"
description: "A private user list for marketing and CRM."
canonical: https://docs.notifiable.sh/api/agents
source: https://docs.notifiable.sh/api/agents.md
---

# Agents API

These routes use the JSON envelope. Scalar lists them under Agents at `/docs/api` in a local environment. The OpenAPI document is `/docs/api.json`.

## GET /api/agents/users

- **Auth:** `Authorization: Bearer` with `AGENTS_API_TOKEN`. A dashboard session is not accepted. When the token is unset, every call is rejected.
- **Name:** `api.agents.users.index`
- **Request:** optional `page` (integer, minimum 1, default 1) and `per_page` (integer, 1 to 100, default 50).
- **Response:** `200` `USERS_LISTED`. Message: "The users were listed." `data.users` is newest first. Each user has `id`, `first_name`, `last_name`, `email`, `role`, `discovery_source`, and `lifecycle_stage`. `role` is the job they gave at registration. `discovery_source` is where they heard about Notifiable, or null. `lifecycle_stage` is `Signup`, `Activated User`, `Engaged User`, `Customer`, `Power User`, `Churned`, or `Closed`. It follows workspaces that person owns. `workspaces` lists each membership, oldest first. Each workspace has `id`, `name`, `slug`, `role` (`owner`, `admin`, `developer`, or `viewer`), `apps_count`, and `subscription`. `apps_count` is the number of apps in that workspace. A deleted app is not counted. `subscription` is null when the workspace has none. Otherwise it has `plan`, `status`, and `billing_interval`. `data.page`, `data.per_page`, and `data.total` describe the page.
- **Errors:**
  - `401` `INVALID_AGENT_TOKEN`, type `authentication_error`, when the bearer token is missing, wrong, or the token is not configured.
  - `422` `VALIDATION_FAILED`, type `validation_error`, when `page` or `per_page` is invalid.
  - `429` `RATE_LIMIT_EXCEEDED`, type `rate_limit_exceeded`, when the caller exceeds 60 requests per minute from one IP.
  - `500` `SERVER_ERROR`, type `server_error`, when the request fails unexpectedly. The body does not include the exception text.