{"openapi":"3.1.0","info":{"title":"Notion (BYOK) API","version":"0.1.0","description":"Notion (BYOK) lets an AI assistant read your own Notion data through the Notion API with a key you supply (integration token (internal integration secret)). Read-only: 11 tools (get_bot_user, list_users, get_user, search, get_page, get_database, get_data_source, query_data_source, list_block_children, get_block, list_comments). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-notion.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-notion/docs"},"termsOfService":"https://connectorbay.com/byok-notion/terms"},"servers":[{"url":"https://byok-notion.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-notion/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_bot_user":{"post":{"operationId":"get_bot_user","summary":"Show the Notion integration the token belongs to: its name, workspace name and the user who owns it. Use for \"Which Noti","description":"Show the Notion integration the token belongs to: its name, workspace name and the user who owns it. Use for \"Which Notion workspace is my integration token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_bot_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_users":{"post":{"operationId":"list_users","summary":"List the people and bots in the Notion workspace (guests excluded) with name, type and email if the integration may see ","description":"List the people and bots in the Notion workspace (guests excluded) with name, type and email if the integration may see emails. Needs the user-information capability; one page per call. Use for \"Who is in my Notion workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return per page (1 to 100).","title":"Page Size"},"start_cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Start Cursor"}},"title":"list_usersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_user":{"post":{"operationId":"get_user","summary":"Get one Notion user or bot by ID with name, type and email (needs the user-information capability). Use for \"Who is the ","description":"Get one Notion user or bot by ID with name, type and email (needs the user-information capability). Use for \"Who is the Notion user e79a0b74-3aba-4149-9f74-0bb5791a6ee6\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"ID of the user or bot (a UUID).","maxLength":200,"title":"User Id","type":"string"}},"required":["user_id"],"title":"get_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search":{"post":{"operationId":"search","summary":"Search the pages or data sources shared with the integration by title. Returns one page of results, most recently edited","description":"Search the pages or data sources shared with the integration by title. Returns one page of results, most recently edited first by default. Use for \"Find my Notion pages about the quarterly plan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Text to match against titles; leave empty to list everything shared with the integration.","title":"Query"},"object_type":{"anyOf":[{"enum":["page","data_source"],"type":"string"},{"type":"null"}],"default":"page","description":"What to find: page or data_source (a database table).","title":"Object Type"},"direction":{"anyOf":[{"enum":["descending","ascending"],"type":"string"},{"type":"null"}],"default":"descending","description":"Sort order by last edited time: descending (newest first) or ascending.","title":"Direction"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return per page (1 to 100).","title":"Page Size"},"start_cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Start Cursor"}},"title":"searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_page":{"post":{"operationId":"get_page","summary":"Get one Notion page's properties (title, status, dates and so on), parent, URL and edit times. Page text is read with li","description":"Get one Notion page's properties (title, status, dates and so on), parent, URL and edit times. Page text is read with list_block_children. Use for \"Show the properties of my Notion page 59833787-2cf9-4fdf-8782-e53db20768a5\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_id":{"description":"ID of the page (a UUID such as '59833787-2cf9-4fdf-8782-e53db20768a5', with or without dashes).","maxLength":200,"title":"Page Id","type":"string"}},"required":["page_id"],"title":"get_pageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_database":{"post":{"operationId":"get_database","summary":"Get a Notion database container: its title, URL and the list of data sources (id and name) inside it, whose IDs the othe","description":"Get a Notion database container: its title, URL and the list of data sources (id and name) inside it, whose IDs the other tools need. Use for \"Which data sources are inside my Notion database\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"database_id":{"description":"ID of the database (a UUID), from the database URL.","maxLength":200,"title":"Database Id","type":"string"}},"required":["database_id"],"title":"get_databaseArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_data_source":{"post":{"operationId":"get_data_source","summary":"Get a Notion data source's schema: its title and every property (column) with name, id and type, for example select opti","description":"Get a Notion data source's schema: its title and every property (column) with name, id and type, for example select options. Use for \"What columns does my Notion tasks data source have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"data_source_id":{"description":"ID of the data source (the table inside a database), a UUID; get it from get_database or search.","maxLength":200,"title":"Data Source Id","type":"string"}},"required":["data_source_id"],"title":"get_data_sourceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/query_data_source":{"post":{"operationId":"query_data_source","summary":"List the rows (pages) of a Notion data source, most recently edited first by default, with all their property values. On","description":"List the rows (pages) of a Notion data source, most recently edited first by default, with all their property values. One page of results per call. Use for \"List the latest rows of my Notion tasks data source\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"data_source_id":{"description":"ID of the data source (the table inside a database), a UUID; get it from get_database or search.","maxLength":200,"title":"Data Source Id","type":"string"},"direction":{"anyOf":[{"enum":["descending","ascending"],"type":"string"},{"type":"null"}],"default":"descending","description":"Sort order by last edited time: descending (newest first) or ascending.","title":"Direction"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return per page (1 to 100).","title":"Page Size"},"start_cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Start Cursor"}},"required":["data_source_id"],"title":"query_data_sourceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_block_children":{"post":{"operationId":"list_block_children","summary":"List the first-level content blocks of a Notion page or block (paragraphs, headings, to-dos, list items) with their rich","description":"List the first-level content blocks of a Notion page or block (paragraphs, headings, to-dos, list items) with their rich text. Blocks with has_children true need another call with their own ID. Use for \"Read the content of my Notion page 59833787-2cf9-4fdf-8782-e53db20768a5\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"block_id":{"description":"ID of the block or page (a UUID); a page ID lists the page's top-level content.","maxLength":200,"title":"Block Id","type":"string"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return per page (1 to 100).","title":"Page Size"},"start_cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Start Cursor"}},"required":["block_id"],"title":"list_block_childrenArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_block":{"post":{"operationId":"get_block","summary":"Get one Notion block by ID: its type, text content and whether it has child blocks. Use for \"What is in Notion block c02","description":"Get one Notion block by ID: its type, text content and whether it has child blocks. Use for \"What is in Notion block c02fc1d3-db8b-45c5-a222-27595b15aea7\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"block_id":{"description":"ID of the block (a UUID).","maxLength":200,"title":"Block Id","type":"string"}},"required":["block_id"],"title":"get_blockArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_comments":{"post":{"operationId":"list_comments","summary":"List the open comments on a Notion page or block with author, time, discussion thread and text. Needs the read-comments ","description":"List the open comments on a Notion page or block with author, time, discussion thread and text. Needs the read-comments capability. Use for \"What comments are on my Notion page 59833787-2cf9-4fdf-8782-e53db20768a5\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"block_id":{"description":"ID of the page or block whose comments to list (a UUID).","maxLength":200,"title":"Block Id","type":"string"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return per page (1 to 100).","title":"Page Size"},"start_cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Start Cursor"}},"required":["block_id"],"title":"list_commentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}