{"openapi":"3.0.0","info":{"description":"Productivity and note-taking","version":[{"name":"v1","value":"v1"}]},"servers":[{"description":"Productivity and note-taking","url":"https://api.apirails.com/notion"}],"paths":{"/v1/pages/{page_id}":{"patch":{"tags":["Pages"],"parameters":[{"name":"page_id","in":"path","description":"Identifier for a Notion page.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/patch-page","api_endpoint":"https://api.notion.com/v1/pages/{page_id}"},"summary":"Update page properties including cover and icon","description":"This API only updates the page properties, icon and cover.\n\nThe properties can only be update if the page belongs to database.\n\nArchieve or unarchive the page using `archived:true` or `archived:false`\n\nTo update page **content**, use the blocks object endpoints.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"archived":{"type":"boolean","description":"Whether the page is archived (deleted). Set to true to archive a page. Set to false to un-archive (restore) a page.","enum":[true,false]},"cover":{"type":"object","description":"Page cover for the new page","properties":{"type":{"type":"string","description":"Type of cover image source","enum":["external","file"]},"external":{"type":"object","description":"External file details for cover image"},"file":{"type":"object","description":"Notion hosted file details for cover image"}}},"icon":{"type":"object","description":"Page icon for the new page","properties":{"type":{"type":"string","description":"Type of icon source","enum":["emoji","external"]},"emoji":{"type":"string","description":"Emoji for the icon"},"external":{"type":"object","description":"External file details for icon"}}},"properties":{"type":"object","description":"Property values of this page. The keys are the names or IDs of the property and the values are property values","properties":{}}}},"example":{"archived":"","cover":{},"icon":{},"properties":{}}}}}},"get":{"tags":["Pages"],"parameters":[{"name":"page_id","in":"path","description":"Identifier for a Notion page","required":true,"schema":{"type":"string","example":""}},{"name":"filter_properties","in":"query","description":"Limit response to specific page property values","schema":{"type":"string","example":"","items":{"type":"string","enum":["?filter_properties=iAk8&filter_properties=b7dh."]}}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/retrieve-a-page","api_endpoint":"https://api.notion.com/v1/pages/{page_id}"},"summary":"Retrieve a page properties and other information","description":"This API retrieve the page properties and other information. \n\nIf the page belongs to database, it will return all the properties linked to the parent database.\n\nIf the page belongs to other page, only title property will be returned.\n\nTo retrieve the page content use blocks API, where `block_id` will be the `page_id`","security":[{"bearerAuth":[]}]}},"/v1/pages/{page_id}/properties/{property_id}":{"get":{"tags":["Pages"],"parameters":[{"name":"page_id","in":"path","description":"Identifier for a Notion page","required":true,"schema":{"type":"string","example":""}},{"name":"property_id","in":"path","description":"Identifier for a page property","required":true,"schema":{"type":"string","example":""}},{"name":"page_size","in":"query","description":"Default page size: 100 property items","schema":{"type":"number","example":""}},{"name":"start_cursor","in":"query","description":"For paginated properties.","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/retrieve-a-page-property","api_endpoint":"https://api.notion.com/v1/pages/{page_id}/properties/{property_id}"},"summary":"Retrieve a page property item","description":"Retrieve a page property item","security":[{"bearerAuth":[]}]}},"/v1/blocks/{block_id}":{"get":{"tags":["Blocks"],"parameters":[{"name":"block_id","in":"path","description":"Identifier for a Notion block","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/retrieve-a-block","api_endpoint":"https://api.notion.com/v1/blocks/{block_id}"},"summary":"Retrieve a block","description":"Retrieve a block","security":[{"bearerAuth":[]}]},"patch":{"tags":["Blocks"],"parameters":[{"name":"block_id","in":"path","description":"Identifier for a Notion block","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/update-a-block","api_endpoint":"https://api.notion.com/v1/blocks/{block_id}"},"summary":"Update a block","description":"Update a block","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"archived":{"type":"boolean","description":"Set to true to delete a block. Set to false to restore a block.","enum":[true,false]}}},"example":{"archived":""}}}}},"delete":{"tags":["Blocks"],"parameters":[{"name":"block_id","in":"path","description":"Identifier for a Notion block","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/delete-a-block","api_endpoint":"https://api.notion.com/v1/blocks/{block_id}"},"summary":"Delete a block","description":"Delete a block","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/pages":{"post":{"tags":["Pages"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/post-page","api_endpoint":"https://api.notion.com/v1/pages"},"summary":"Create a new page inside page or a database","description":"Create new page inside a page or a database.\n\n**Note**: Notion API doesn't allow creating a root level page inside a workspace. Page can only be created inside another page or database.\n\n### Create a page where parent is also a page:\n\nWhen a new page is created inside a page, only `title` property is required.\n\n### Create a page where parent is a database:\n\nWhereas when a new page is created inside a database, page properties are interited from the database properties.\n\nWhile creating a new page, other fields like `icon`, `cover` or `children` can also be used.\n\n`icon` field is used for setting icon in a page, either we can set emoji or add our own image.\n\n`cover` field is used for setting cover in page. \n\n`children` field is used for adding content inside the page, represented using array of block objects.\n\n___\n\nThis API can take 10 different variation of payload for creating a page.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"children":{"type":"array","description":"Page content for the new page as an array of block objects","items":{"type":"object","properties":{}}},"cover":{"type":"object","description":"Page cover for the new page","properties":{"type":{"type":"string","description":"Type of cover image source","enum":["external","file"]},"external":{"type":"object","description":"External file details for cover image"},"file":{"type":"object","description":"Notion hosted file details for cover image"}}},"icon":{"type":"object","description":"Page icon for the new page","properties":{"type":{"type":"string","description":"Type of icon source","enum":["emoji","external"]},"emoji":{"type":"string","description":"Emoji for the icon"},"external":{"type":"object","description":"External file details for icon"}}},"parent":{"type":"object","description":"A database parent or page parent","required":true,"properties":{"database_id":{"type":"string","description":"Identifier for a Notion database"},"page_id":{"type":"string","description":"Identifier for a Notion page"}}},"properties":{"type":"object","description":"Property values of this page. The keys are the names or IDs of the property and the values are property values","required":true,"properties":{}}}},"example":{"children":[],"cover":{"type":"external","external":{"url":""}},"icon":{"type":"emoji || external","emoji":"😻","external":{"url":""}},"parent":{"database_id":"","page_id":""},"properties":{"Name":{"title":[{"text":{"content":"Tuscan Kale"}}]},"title":[{"text":{"content":"A page with an avocado icon","link":null},"type":"text"}]}}}}}}},"/v1/databases/{database_id}":{"get":{"tags":["Database"],"parameters":[{"name":"database_id","in":"path","description":"Identifier for a Notion database.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/retrieve-a-database","api_endpoint":"https://api.notion.com/v1/databases/{database_id}"},"summary":"Retrieve database detail and it's properties","description":"This API only retrieve a database info such as title, description and it's properties (column details), doesn't return the row data.\n\n\nTo retrieve the rows (data) of the database, use the database query api","security":[{"bearerAuth":[]}]},"patch":{"tags":["Database"],"parameters":[{"name":"database_id","in":"path","description":"Identifier for a Notion database.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/update-a-database","api_endpoint":"https://api.notion.com/v1/databases/{database_id}"},"summary":"Update database details","description":"This API is used for updating `title`, `description` and `properties` of the database, new property can be added, existing property can be updated or removed.\n\n\nTo update the row, use the page update API.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"description":{"type":"array","description":"An array of rich text objects that represents the description of the database that is displayed in the Notion UI. If omitted then the database description remains unchanged.","items":{"type":"object","properties":{}}},"properties":{"type":"object","description":"The properties of a database to be changed in the request in the form of a JSON object. If updating an existing property then the keys are the names or IDs of the properties as they appear in Notion and the values are property schema objects. If adding a new property then the key is the name of the new database property and the value is a property schema object.","properties":{}},"title":{"type":"array","description":"An array of rich text objects that represents the title of the database that is displayed in the Notion UI. If omitted then the database title remains unchanged.","items":{"type":"object","properties":{}}}}},"example":{"description":[],"properties":{},"title":[]}}}}}},"/v1/databases/{database_id}/query":{"post":{"tags":["Database"],"parameters":[{"name":"database_id","in":"path","description":"Identifier for a Notion database.","required":true,"schema":{"type":"string","example":""}},{"name":"filter_properties","in":"query","description":"Filter response by specific page property IDs.","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/post-database-query","api_endpoint":"https://api.notion.com/v1/databases/{database_id}/query"},"summary":"Fetch rows of the Notion database using query","description":"This API is used for retrieving the rows (data) of the database, using `database_id` and query filter to match the records.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"filter":{"type":"object","description":"When supplied limits which pages are returned based on the filter conditions.","properties":{}},"page_size":{"type":"number","description":"The number of items from the full list desired in the response. Maximum - 100"},"sorts":{"type":"array","description":"When supplied orders the results based on the provided sort criteria.","items":{"type":"object","properties":{"property":{"type":"string","description":"The name or ID of the property to sort against","required":true},"direction":{"type":"string","description":"The direction to sort","required":true,"enum":["ascending","descending"]}}}},"start_cursor":{"type":"string","description":"When supplied returns a page of results starting after the cursor provided. If not supplied this endpoint will return the first page of results."}}},"example":{"filter":{},"page_size":100,"sorts":[],"start_cursor":""}}}}}},"/v1/databases":{"post":{"tags":["Database"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/create-a-database","api_endpoint":"https://api.notion.com/v1/databases"},"summary":"Create new database","description":"This API is used for creating new database, parent is always a page and has `page_id`.\n\nTo create the database `properties` is required,\n\nAPI also support `title`, `description`, `icon`, `cover`\n","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"parent":{"type":"object","description":"A page parent","required":true,"properties":{"page_id":{"type":"string","description":"Identifier for a Notion page","required":true}}},"properties":{"type":"object","description":"Property schema of database. The keys are the names of properties as they appear in Notion and the values are property schema objects.","required":true,"properties":{}},"title":{"type":"array","description":"Title of database as it appears in Notion. An array of rich text objects.","items":{"type":"object","properties":{}}}}},"example":{"parent":{"type":"page_id","page_id":""},"properties":{"Description":{"rich_text":{}},"Name":{"title":{}}},"title":[{"text":{"content":"Title here","link":null},"type":"text"}]}}}}}},"/v1/blocks/{block_id}/children":{"get":{"tags":["Blocks"],"parameters":[{"name":"block_id","in":"path","description":"Identifier for a Notion block","required":true,"schema":{"type":"string","example":""}},{"name":"page_size","in":"query","description":"Limit response to maximum 100 items","schema":{"type":"number","example":""}},{"name":"start_cursor","in":"query","description":"Supply cursor for next page when available.","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/get-block-children","api_endpoint":"https://api.notion.com/v1/blocks/{block_id}/children"},"summary":"Retrieve block children","description":"Retrieve block children","security":[{"bearerAuth":[]}]},"patch":{"tags":["Blocks"],"parameters":[{"name":"block_id","in":"path","description":"Identifier for a Notion block","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/patch-block-children","api_endpoint":"https://api.notion.com/v1/blocks/{block_id}/children"},"summary":"Append block children","description":"Append block children","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"after":{"type":"string","description":"The ID of the existing block that the new block should be appended after"},"children":{"type":"array","description":"Child content to append to a container block as an array of block objects","required":true,"items":{"type":"object","properties":{}}}}},"example":{"after":"","children":[]}}}}}},"/v1/comments":{"get":{"tags":["Comments"],"parameters":[{"name":"block_id","in":"query","description":"Identifier for a Notion block or page","required":true,"schema":{"type":"string","example":""}},{"name":"page_size","in":"query","description":"Limit response to maximum of 100 items","schema":{"type":"number","example":""}},{"name":"start_cursor","in":"query","description":"Return subsequent page results after provided cursor","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/retrieve-a-comment","api_endpoint":"https://api.notion.com/v1/comments"},"summary":"Retrieve comments","description":"Retrieve comments","security":[{"bearerAuth":[]}]},"post":{"tags":["Comments"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/create-a-comment","api_endpoint":"https://api.notion.com/v1/comments"},"summary":"Create comment","description":"Create comment","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"discussion_id":{"type":"string","description":"A UUID identifier for a discussion thread. Either this or a parent object is required (not both)"},"parent":{"type":"object","description":"A page parent. Either this or a discussion_id is required (not both)","properties":{"page_id":{"type":"string","description":"Identifier for a Notion page","required":true}}},"rich_text":{"type":"object","description":"A rich text object","required":true,"properties":{}}}},"example":{"discussion_id":"","parent":{},"rich_text":{}}}}}}},"/v1/search":{"post":{"tags":["Search"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/post-search","api_endpoint":"https://api.notion.com/v1/search"},"summary":"Search","description":"Search","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"filter":{"type":"object","description":"When supplied filters the results based on the provided criteria.","properties":{"value":{"type":"string","description":"The value of the filter","required":true,"enum":["page","database"]},"property":{"type":"string","description":"The property to filter by","required":true,"enum":["object"]}}},"page_size":{"type":"number","description":"The number of items from the full list desired in the response. Maximum - 100."},"query":{"type":"string","description":"When supplied limits which pages are returned by comparing the query to the page title."},"sort":{"type":"object","description":"When supplied sorts the results based on the provided criteria. Limitation","enum":["Currently only a single sort is allowed and is limited to last_edited_time. The default sort is by last_edited_time descending."],"properties":{"direction":{"type":"string","description":"The direction to sort","required":true,"enum":["ascending","descending"]},"timestamp":{"type":"string","description":"The timestamp to sort by","required":true,"enum":["last_edited_time"]}}},"start_cursor":{"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."}}},"example":{"filter":{},"page_size":"","query":"","sort":{},"start_cursor":""}}}}}},"/v1/users/{user_id}":{"get":{"tags":["Users"],"parameters":[{"name":"user_id","in":"path","description":"Identifier for a Notion user","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/get-user","api_endpoint":"https://api.notion.com/v1/users/{user_id}"},"summary":"Retrieve a user","description":"Retrieve a user","security":[{"bearerAuth":[]}]}},"/v1/users":{"get":{"tags":["Users"],"parameters":[{"name":"page_size","in":"query","description":"Limit response to maximum 100 items","schema":{"type":"number","example":""}},{"name":"start_cursor","in":"query","description":"Supply cursor for next page when available","schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/get-users","api_endpoint":"https://api.notion.com/v1/users"},"summary":"List all users","description":"List all users","security":[{"bearerAuth":[]}]}},"/v1/oauth/token":{"post":{"tags":["Authentication"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/create-a-token","api_endpoint":"https://api.notion.com/v1/oauth/token"},"summary":"Create a token","description":"Access token that a third-party service can use to authenticate with Notion","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"code":{"type":"string","description":"A unique random code that Notion generates to authenticate with your service, generated when a user initiates the OAuth flow","required":true},"grant_type":{"type":"string","description":"A constant string: 'authorization_code'","required":true},"redirect_uri":{"type":"string","description":"The 'redirect_uri' that was provided in the OAuth Domain & URI section of the integration's Authorization settings","required":true}}},"example":{"code":"","grant_type":"","redirect_uri":""}}}}}},"/v1/users/me":{"get":{"tags":["Users"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://developers.notion.com/reference/get-self","api_endpoint":"https://api.notion.com/v1/users/me"},"summary":"Fetch token user","description":"Retrieve your token's bot user","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"bearerAuth":[]}]}