Skip to main content
POST
TypeScript SDK
Use filters, sorting, and cursor pagination to find accessible agents. For a personal access token, results also include the personal agent, with id and agent_type set to notion_ai. Filter on agent_type to include or leave it out.
AccessA personal access token returns the agents its user can read, plus that user’s personal agent. A connection returns only Custom Agents explicitly shared with it. No matching agents returns an empty results array.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Body

application/json
query
string

Search agent names and descriptions using a case-insensitive substring match.

filter
object

Filter agents by public properties, optionally combined with and/or.

sorts
object[]

Ordered sort precedence. Defaults to created_time descending.

Required array length: 1 - 2 elements
start_cursor
string

Opaque continuation cursor from the previous page.

page_size
integer

Number of agents to return. Maximum: 100.

Required range: 1 <= x <= 100
verbose
boolean

Whether to include inline instructions for each agent. Defaults to false.

include_deleted
boolean

Whether to include soft-deleted agents. Defaults to false.

Response

object
string
required

Always list

Allowed value: "list"
type
string
required

Always agent

Allowed value: "agent"
results
object[]
required
Maximum array length: 100
has_more
boolean
required
next_cursor
string | null
required