List agents
Returns the workspace’s agents, newest first (created_at descending). Soft-deleted agents are
never returned.
Pagination is keyset on (created_at, id): to fetch the next page, pass meta.nextCursor back
unchanged as cursor. The cursor is opaque and encodes the position of the last agent, so agents
created at the same instant are never skipped or repeated between pages; order ties on
created_at are broken by id, descending. meta.nextCursor is null when the page is shorter
than limit. A legacy cursor (the ISO-8601 created_at of the last agent, the format used until
2026-09-15) is still accepted and returns agents created strictly before it. See
Pagination.
List items carry a projection of the agent: chat_system_prompt, tool_profile, base_prompt_version, workflow,
tool_surface_version, high_risk, paused_by, paused_reason, action_limits and
deleted_at are only returned by GET /api/agents/{agentId}.
Consistency. Each page is cached for up to 120 seconds per workspace and query. Creates, updates and deletes made through this API clear the cache immediately; changes made by background processes (provider provisioning, tool-surface sync, pausing) can take up to 120 seconds to show.
Access
- Required scope:
read. Any workspace role can call it. - Rate limit: General API — 120 (Starter), 200 (Growth), 300 (Business) or 600 (Enterprise) requests/min per workspace. See Rate limits.
- Plan: Available on every plan.
Authentication
Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the
dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once,
at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.
Operations restricted to admins or owners reject keys without the full scope with 403, and say so in
their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret —
that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds.
See Authentication.
Query parameters
Maximum agents to return, 1-200. Defaults to 50. A value outside the range or not an integer is
rejected with 400 (not clamped).
The opaque meta.nextCursor of the previous page; pass it back exactly as received. Returns the
agents that follow that position. A legacy ISO-8601 timestamp is still accepted and returns
agents created strictly before it. Any other value is rejected with 400 VALIDATION_FAILED.
Case-insensitive substring match on the agent name. Trimmed; 1-200 characters after trimming
(a whitespace-only value is rejected with 400). % and _ match literally.
Response
A page of agents (list projection).