> ## Documentation Index > Fetch the complete documentation index at: https://developers.notion.com/llms.txt > Use this file to discover all available pages before exploring further. # List Agents This is an internal/undocumented endpoint. It is not part of the public API and may change without notice. Do not rely on this endpoint for production connections. ## OpenAPI ````yaml openapi-undocumented.json GET /v1/agents openapi: 3.1.0 info: title: Notion API (Undocumented) version: 1.0.0 description: >- Internal/undocumented Notion API endpoints. These endpoints are not part of the public API and may change without notice. Do not rely on these for production integrations. termsOfService: >- https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac x-noIndex: true servers: - url: https://api.notion.com security: - bearerAuth: [] tags: - name: Internal description: Internal/undocumented endpoints x-hidden: true paths: /v1/agents: get: tags: - Internal summary: List agents operationId: list-agents parameters: - name: name in: query schema: type: string description: Filter agents by name (case-insensitive substring match). - name: agent_type in: query schema: type: array items: type: string enum: - notion_ai - custom_agent - autofill_custom_agent - external description: >- One of: `notion_ai`, `custom_agent`, `autofill_custom_agent`, `external` maxItems: 100 minItems: 1 description: Filter agents by one or more agent types. - name: agent_ids in: query schema: type: array items: oneOf: - $ref: '#/components/schemas/idRequest' - type: string enum: - notion_ai - 33333333-3333-3333-3333-333333333333 description: 'One of: `notion_ai`, `33333333-3333-3333-3333-333333333333`' maxItems: 100 minItems: 1 description: >- Filter agents by one or more agent IDs. Use `notion_ai` for Notion Agent (personal agent). - name: created_by in: query schema: type: array items: oneOf: - $ref: '#/components/schemas/idRequest' - type: string const: me description: Always `me` maxItems: 100 minItems: 1 description: >- Filter agents by one or more creator IDs. Use "me" for the user associated with the API token. - name: start_cursor in: query schema: type: string description: >- If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results. - name: page_size in: query schema: type: integer minimum: 1 maximum: 100 description: >- The number of items from the full list desired in the response. Maximum: 100 - name: verbose in: query schema: type: boolean description: >- Whether to include inline instructions for each agent. Defaults to false. - $ref: '#/components/parameters/notionVersion' responses: '200': description: '' content: application/json: schema: type: object properties: object: type: string const: list description: Always `list` type: type: string const: agent description: Always `agent` results: type: array items: type: object properties: object: type: string const: agent description: Always `agent` id: anyOf: - $ref: '#/components/schemas/idResponse' - type: string const: notion_ai description: Always `notion_ai` agent_type: type: string enum: - notion_ai - custom_agent - autofill_custom_agent - external description: >- Agent kind: the Notion AI personal agent, a custom agent, a database autofill custom agent, or an external agent. name: type: string description: oneOf: - type: string - type: 'null' instructions_page_id: oneOf: - $ref: '#/components/schemas/idResponse' - type: 'null' icon: oneOf: - $ref: '#/components/schemas/pageIconResponse' - type: object properties: type: type: string const: custom_agent_avatar description: >- Type of icon. In this case, a custom agent avatar. custom_agent_avatar: type: object properties: static_url: type: string description: >- The URL of the static custom agent avatar. animated_url: type: string description: >- The URL of the animated custom agent avatar. additionalProperties: false required: - static_url - animated_url description: >- The static and animated URLs for the agent avatar. additionalProperties: false required: - type - custom_agent_avatar - type: 'null' version: oneOf: - type: object properties: id: $ref: '#/components/schemas/idResponse' description: The ID of the published artifact. number: type: number description: The version number. published_at: type: string description: >- The ISO 8601 timestamp when this version was published. additionalProperties: false required: - id - number - published_at - type: 'null' agent_version: oneOf: - type: object properties: id: $ref: '#/components/schemas/idResponse' description: The ID of the published artifact. number: type: number description: The version number. published_at: type: string description: >- The ISO 8601 timestamp when this version was published. additionalProperties: false required: - id - number - published_at - type: 'null' model: oneOf: - type: object properties: mode: type: string const: auto description: Always `auto` additionalProperties: false required: - mode - type: object properties: mode: type: string const: pinned description: Always `pinned` id: oneOf: - type: string - type: 'null' description: >- The public model this agent maps to (e.g. "claude-sonnet-5"), or null for a pre-release / early-access model. additionalProperties: false required: - mode - id description: >- The model the agent runs on: auto (Notion selects) or a pinned model. connections: type: array items: oneOf: - type: object properties: type: type: string const: notion description: Always `notion` name: type: string account: type: 'null' permissions: type: array items: type: object properties: target: oneOf: - type: object properties: type: type: string const: page description: Always `page` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: database_property description: Always `database_property` data_source_id: type: string property_id: type: string additionalProperties: false required: - type - data_source_id - property_id - type: object properties: type: type: string const: agent description: Always `agent` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: workspace description: Always `workspace` additionalProperties: false required: - type - type: object properties: type: type: string const: owner_private_pages description: Always `owner_private_pages` additionalProperties: false required: - type - type: object properties: type: type: string const: web_search description: Always `web_search` allowed_domains: oneOf: - type: array items: type: string maxItems: 100 - type: 'null' description: >- Domains web search is restricted to, or null when unrestricted. additionalProperties: false required: - type - allowed_domains - type: object properties: type: type: string const: notion_help_docs_search description: Always `notion_help_docs_search` additionalProperties: false required: - type scopes: type: array items: type: string maxItems: 100 description: >- Content roles ("reader" | "comment_only" | "read_and_write" | "editor") for scoped targets, or search verbs ("allow" | "disallow") for the search targets. additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions - type: object properties: type: type: string const: slack description: Always `slack` name: type: string account: oneOf: - type: object properties: type: type: string const: slack_workspace description: Always `slack_workspace` team_id: type: string additionalProperties: false required: - type - team_id - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The linked Slack workspace, null when none is linked, or "hidden" when the caller lacks edit access to the agent. permissions: type: array items: type: object properties: target: oneOf: - type: object properties: type: type: string const: slack_channel description: Always `slack_channel` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: slack_all_public_channels description: Always `slack_all_public_channels` additionalProperties: false required: - type - type: object properties: type: type: string const: slack_all_channels description: Always `slack_all_channels` additionalProperties: false required: - type scopes: type: array items: type: string maxItems: 100 description: >- Slack verbs granted on this target ("read" | "write" | "reply_in_thread" | "react"). additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions - type: object properties: type: type: string const: discord description: Always `discord` name: type: string account: oneOf: - type: object properties: type: type: string const: discord_server description: Always `discord_server` id: type: string additionalProperties: false required: - type - id - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The linked Discord server, null when none is linked, or "hidden" when the caller lacks edit access to the agent. permissions: type: array items: type: object properties: target: oneOf: - type: object properties: type: type: string const: discord_channel description: Always `discord_channel` id: type: string additionalProperties: false required: - type - id - type: object properties: type: type: string const: discord_all_channels description: Always `discord_all_channels` additionalProperties: false required: - type scopes: type: array items: type: string maxItems: 100 description: >- Discord verbs granted on this target ("read" | "write" | "reply_in_thread" | "react"). additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions - type: object properties: type: type: string const: mcp_server description: Always `mcp_server` name: type: string account: oneOf: - type: object properties: type: type: string const: mcp_server description: Always `mcp_server` server_host: type: string description: >- The MCP server host (never the full URL, which can carry credentials or private path components). additionalProperties: false required: - type - server_host - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent. enabled_tools: oneOf: - type: array items: type: object properties: name: type: string title: oneOf: - type: string - type: 'null' additionalProperties: false required: - name - title maxItems: 100 - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The tools the agent may call, null when all tools are enabled (including any the server adds later), or "hidden" when the caller lacks edit access to the agent. run_tools_automatically: type: object properties: read: type: boolean description: >- Whether read tool calls run without a confirmation step. write: type: boolean description: >- Whether write tool calls run without a confirmation step. additionalProperties: false required: - read - write description: >- Whether read / write tool calls run without a confirmation step. additionalProperties: false required: - type - name - account - enabled_tools - run_tools_automatically - type: object properties: type: type: string const: custom_mcp_server description: Always `custom_mcp_server` name: type: string account: oneOf: - type: object properties: type: type: string const: mcp_server description: Always `mcp_server` server_host: type: string description: >- The MCP server host (never the full URL, which can carry credentials or private path components). additionalProperties: false required: - type - server_host - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The MCP server host, null when none is linked, or "hidden" when the caller lacks edit access to the agent. enabled_tools: oneOf: - type: array items: type: object properties: name: type: string title: oneOf: - type: string - type: 'null' additionalProperties: false required: - name - title maxItems: 100 - type: string const: hidden description: Always `hidden` - type: 'null' description: >- The tools the agent may call, null when all tools are enabled (including any the server adds later), or "hidden" when the caller lacks edit access to the agent. run_tools_automatically: type: object properties: read: type: boolean description: >- Whether read tool calls run without a confirmation step. write: type: boolean description: >- Whether write tool calls run without a confirmation step. additionalProperties: false required: - read - write description: >- Whether read / write tool calls run without a confirmation step. additionalProperties: false required: - type - name - account - enabled_tools - run_tools_automatically - type: object properties: type: type: string enum: - asana - box - calendar - computer - confluence - cursor - files - fs - github - gmail - google_calendar - google_drive - google_drive_oauth - gtm - helpdocs - images - jira - linear - mail - marketplace - memory - microsoft_teams - microsoft_teams_oauth - outlook - salesforce - search - security - sharepoint - skills - system - test - web - webhooks - worker - workers description: >- The connector's machine name (e.g. "github", "google_drive"). name: type: string account: oneOf: - type: string - type: 'null' description: >- The provider-side account identifier, null when none is linked, or "hidden" when the caller lacks edit access to the agent. permissions: type: array items: type: object properties: target: type: object properties: type: type: string id: type: string additionalProperties: false required: - type - id scopes: type: array items: type: string maxItems: 100 description: The scopes granted on this target. additionalProperties: false required: - target - scopes maxItems: 100 additionalProperties: false required: - type - name - account - permissions maxItems: 100 description: >- Non-Notion integrations the agent is connected to, using the same account and permission shape as get agent. status: type: string enum: - active - disabled - deleted description: >- Agent status. Disabled agents remain listed; deleted agents are currently excluded from list responses. created_by: oneOf: - type: object properties: object: type: string const: user description: Always `user` type: type: string const: user description: Always `user` id: $ref: '#/components/schemas/idResponse' description: The ID of the user that created this agent. additionalProperties: false required: - object - type - id - type: 'null' created_time: oneOf: - type: string format: date-time - type: 'null' description: >- Date and time when this agent was created, or null for the personal agent. last_edited_time: oneOf: - type: string format: date-time - type: 'null' description: >- Date and time when this agent was last edited, or null for the personal agent. last_run_time: oneOf: - type: string format: date-time pattern: ^\d{4}-\d{2}-\d{2}T - type: string const: hidden description: Always `hidden` - type: 'null' description: >- Date and time when this agent was last invoked, null when no invocation is available, or "hidden" when the caller lacks edit access to the agent. last_run_at: oneOf: - type: string format: date-time pattern: ^\d{4}-\d{2}-\d{2}T - type: string const: hidden description: Always `hidden` - type: 'null' description: >- Date and time when this agent was last invoked, null when no invocation is available, or "hidden" when the caller lacks edit access to the agent. instructions: oneOf: - type: string - type: 'null' description: >- The agent's inline instructions when verbose=true, or null when its instructions are stored on a page. additionalProperties: false required: - object - id - agent_type - name - description - instructions_page_id - icon - version - agent_version - model - connections - status - created_by - created_time - last_edited_time - last_run_time - last_run_at maxItems: 100 has_more: type: boolean next_cursor: oneOf: - title: Cursor type: string - type: 'null' additionalProperties: false required: - object - type - results - has_more - next_cursor '400': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_400' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_401' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_403' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_404' '406': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_406' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_409' '429': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_429' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_500' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_503' '504': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_504' '529': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_529' deprecated: true components: schemas: idRequest: type: string idResponse: type: string format: uuid pageIconResponse: oneOf: - $ref: '#/components/schemas/emojiPageIconResponse' - $ref: '#/components/schemas/filePageIconResponse' - $ref: '#/components/schemas/externalPageIconResponse' - $ref: '#/components/schemas/customEmojiPageIconResponse' - $ref: '#/components/schemas/iconPageIconResponse' error_api_400: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - invalid_json - invalid_request_url - invalid_request - missing_version - invalid_beta - validation_error - invalid_credit_limit status: const: 400 required: - code - status additionalProperties: false error_api_401: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - unauthorized status: const: 401 required: - code - status additionalProperties: false error_api_403: oneOf: - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - restricted_resource - status_change_not_allowed status: const: 403 required: - code - status additionalProperties: false - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: workspace_credits_exhausted status: const: 403 additional_data: type: object properties: tool_error_code: const: workspace_credits_exhausted tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - open_workspace_credit_settings description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: agent_credit_limit_reached status: const: 403 additional_data: type: object properties: tool_error_code: const: agent_credit_limit_reached tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - none - open_agent_settings - request_agent_limit_increase - request_pending description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data error_api_404: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - object_not_found - directory_not_found status: const: 404 required: - code - status additionalProperties: false error_api_406: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - row_limit_exceeded status: const: 406 required: - code - status additionalProperties: false error_api_409: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - conflict_error - idempotency_key_reused - agent_deleted status: const: 409 required: - code - status additionalProperties: false error_api_429: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - rate_limited status: const: 429 required: - code - status additionalProperties: false error_api_500: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - internal_server_error status: const: 500 required: - code - status additionalProperties: false error_api_503: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_unavailable status: const: 503 required: - code - status additionalProperties: false error_api_504: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - gateway_timeout status: const: 504 required: - code - status additionalProperties: false error_api_529: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_overload status: const: 529 required: - code - status additionalProperties: false emojiPageIconResponse: type: object properties: type: type: string const: emoji description: Type of icon. In this case, an emoji. emoji: $ref: '#/components/schemas/emojiRequest' description: The emoji character used as the icon. additionalProperties: false required: - type - emoji title: Emoji filePageIconResponse: type: object properties: type: type: string const: file description: Type of icon. In this case, a file. file: $ref: '#/components/schemas/internalFileResponse' description: The file URL for the icon. additionalProperties: false required: - type - file title: File externalPageIconResponse: type: object properties: type: type: string const: external description: Type of icon. In this case, an external URL. external: type: object properties: url: type: string description: The URL of the external file or resource. additionalProperties: false required: - url description: The external URL for the icon. additionalProperties: false required: - type - external title: External customEmojiPageIconResponse: type: object properties: type: type: string const: custom_emoji description: Type of icon. In this case, a custom emoji. custom_emoji: $ref: '#/components/schemas/customEmojiResponse' description: The custom emoji details for the icon. additionalProperties: false required: - type - custom_emoji title: Custom Emoji iconPageIconResponse: type: object properties: type: type: string const: icon description: Type of icon. In this case, a Notion native icon. icon: $ref: '#/components/schemas/noticonIconResponse' description: The Notion native icon, specified by name and color. additionalProperties: false required: - type - icon title: Icon publicApiCommonErrorResponse: type: object properties: object: const: error message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - message emojiRequest: type: string example: 😀 internalFileResponse: type: object properties: url: type: string description: The URL of the file. expiry_time: type: string format: date-time description: The time when the URL will expire. additionalProperties: false required: - url - expiry_time customEmojiResponse: type: object properties: id: $ref: '#/components/schemas/idResponse' description: The ID of the custom emoji. name: type: string description: The name of the custom emoji. url: type: string description: The URL of the custom emoji. additionalProperties: false required: - id - name - url noticonIconResponse: type: object properties: name: $ref: '#/components/schemas/noticonName' description: >- The name of the Notion icon (e.g. pizza, meeting, home). See the Notion icon picker for valid names. color: $ref: '#/components/schemas/noticonColor' description: >- The color variant of the icon. Valid values: gray, lightgray, brown, yellow, orange, green, blue, purple, pink, red. additionalProperties: false required: - name - color noticonName: type: string examples: - pizza - meeting - home - star - robot noticonColor: type: string enum: - gray - lightgray - brown - yellow - orange - green - blue - purple - pink - red description: >- One of: `gray`, `lightgray`, `brown`, `yellow`, `orange`, `green`, `blue`, `purple`, `pink`, `red` parameters: notionVersion: name: Notion-Version in: header required: true schema: enum: - '2026-03-11' description: >- The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`. securitySchemes: bearerAuth: type: http scheme: bearer ````