@spec create(term(), map(), keyword()) :: {:ok, term()} | {:error, term()}

Create a data source

Source Context

Resources

• Create a data source

Code Samples

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.dataSources.create({
parent: {
  database_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
title: [{ text: { content: "My Data Source" } }],
properties: {
  Name: { title: {} },
  Status: {
    select: {
      options: [
        { name: "To Do", color: "red" },
        { name: "Done", color: "green" }
      ]
    }
  }
}
})

@spec list_templates(term(), map(), keyword()) :: {:ok, term()} | {:error, term()}

List data source templates

Source Context

Resources

• List data source templates

Code Samples

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.dataSources.listTemplates({
data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
})

@spec query(term(), map(), keyword()) :: {:ok, term()} | {:error, term()}

Query a data source

Source Context

Warnings

Formula and rollup limitations

• If a formula depends on a page property that is a relation, and that relation has more than 25 references, only 25 will be evaluated as part of the formula.
• Rollups and formulas that depend on multiple layers of relations may not return correct results.
• Notion recommends individually retrieving each page property item to get the most accurate result.

Notes

Databases, data sources, and wikis

Wiki data sources can contain either pages or databases as children. In all other cases, the children can only be pages. For wikis, instead of directly returning any database results, this API returns all data sources that are children of that database. Surfacing the data source instead of the direct database child helps make it easier to craft your next API request (for example, retrieving the data source or listing its children.) Another tip for wikis is to use the result_type filter of "page" or "data_source" if you're only looking for query results that are one of those two types instead of both.

Permissions

Before an integration can query a data source, its parent database must be shared with the integration. Attempting to query a data source in a database that has not been shared will return an HTTP response with a 404 status code. To share a database with an integration, click the ••• menu at the top right of a database page, scroll to Add connections, and use the search bar to find and select the integration from the dropdown list.

Integration capabilities

This endpoint requires an integration to have read content capabilities. Attempting to call this API without read content capabilities will return an HTTP response with a 403 status code. For more information on integration capabilities, see the capabilities guide.

To display the page titles of related pages rather than just the ID:

1. Add a rollup property to the data source which uses a formula to get the related page's title. This works well if you have access to update the data source's schema.
2. Otherwise, retrieve the individual related pages using each page ID.

Overview

Gets a list of pages contained in the data source, filtered and ordered according to the filter conditions and sort criteria provided in the request. The response may contain fewer than page_size of results. If the response includes a next_cursor value, refer to the pagination reference for details about how to use a cursor to iterate through the list.

Filtering

Filters are similar to the filters provided in the Notion UI where the set of filters and filter groups chained by "And" in the UI is equivalent to having each filter in the array of the compound "and" filter. Similar a set of filters chained by "Or" in the UI would be represented as filters in the array of the "or" compound filter. Filters operate on data source properties and can be combined. If no filter is provided, all the pages in the data source will be returned with pagination.

json Filter object expandable theme={null} { "and": [ { "property": "Done", "checkbox": { "equals": true } }, { "or": [ { "property": "Tags", "contains": "A" }, { "property": "Tags", "contains": "B" } ] } ] } In addition to chained filters, data sources can be queried with single filters. json JSON theme={null} { "property": "Done", "checkbox": { "equals": true } }

Sorting

Sorts are similar to the sorts provided in the Notion UI. Sorts operate on database properties or page timestamps and can be combined. The order of the sorts in the request matter, with earlier sorts taking precedence over later ones. Notion doesn't guarantee any particular sort order when no sort parameters are provided.

Recommendations for performance

Use the filter_properties query parameter to filter only the properties of the data source schema you need from the response items. For example: bash theme={null} https://api.notion.com/v1/data_sources/[DATA_SOURCE_ID]/query?filter_properties[]=title Multiple filter properties can be provided by chaining the filter_properties query param. For example: bash theme={null} https://api.notion.com/v1/data_sources/[DATA_SOURCE_ID]/query?filter_properties[]=title&filter_properties[]=status This parameter accepts property IDs or property names. Property IDs can be determined with the Retrieve a data source endpoint. If you are using the Notion JavaScript SDK, the filter_properties endpoint expects an array of strings. For example: typescript TypeScript theme={null} notion.dataSources.query({ data_source_id: id, filter_properties: ["title", "status"] }) Using filter_properties can make a significant improvement to the speed of the API and size of the JSON objects in the results, especially for databases with lots of properties, some of which might be rollups, relations, or formulas. If you need additional properties from each returned page, you can make subsequent calls to the Retrieve page property item or Retrieve a page APIs. If you're still running into long query times with this API, other tips include: For more information, visit our help center article on optimizing database load times.

Using more specific filter conditions to reduce the result set, e.g. a more specific title query or a shorter time window. Dividing large data sources (ones with more than several dozen thousand pages) into multiple; e.g. splitting a "tasks" database into "Tasks" and "Bugs". Pruning data source schemas to remove any complex formulas, rollups, two-way relations, or other properties that are no longer in use. Setting up integration webhooks to reduce the need for polling this API by instead automatically notifying your system of incremental workspace events.

### Other important details and tips

### Errors

Returns a 404 HTTP response if the data source doesn't exist, or if the integration doesn't have access to the data source. Returns a 400 or a 429 HTTP response if the request exceeds the request limits. Returns a 503 HTTP response if the data source query is temporarily unavailable due to backend datastore timeouts. The response body includes an additional_data object with retry guidance: json 503 response example theme={null} { "object": "error", "status": 503, "code": "service_unavailable", "message": "Public API data source query is temporarily unavailable due to backend datastore timeouts. Retry with exponential backoff; if retries continue to fail, reduce page_size or narrow filters/sorts.", "additional_data": { "endpoint_name": "public_queryDataSource", "notion_error_name": "PgPoolWaitConnectionTimeout", "retry_guidance": [ "Use exponential backoff with jitter", "Reduce page_size", "Narrow query filters/sorts" ] } }

Resources

• pages
• pagination reference
• Wiki
• database
• data sources
• Filters
• filters provided in the Notion UI
• Sorts
• sorts provided in the Notion UI
• Retrieve a data source
• Notion JavaScript SDK
• Retrieve page property item
• Retrieve a page
• integration webhooks
• help center article on optimizing database load times
• capabilities guide
• update
• retrieve the individual related pages
• retrieving each page property item
• request limits
• Error codes section
• Query a data source

Code Samples

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.dataSources.query({
data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce",
filter: {
  property: "Status",
  select: { equals: "Done" }
},
sorts: [
  {
    property: "Created",
    direction: "descending"
  }
]
})

@spec retrieve(term(), map(), keyword()) :: {:ok, term()} | {:error, term()}

Retrieve a data source

Source Context

Warnings

The Notion API does not support retrieving linked data sources

To fetch the information in a linked data source, share the original source database with your Notion integration.

Notes

Data source relations must be shared with your integration

To retrieve data source properties from database relations, the related database must be shared with your integration in addition to the database being retrieved. If the related database is not shared, properties based on relations will not be included in the API response.

Finding a data source ID

Navigate to the database URL in your Notion workspace. The ID is the string of characters in the URL that is between the slash following the workspace name (if applicable) and the question mark. The ID is a 32 characters alphanumeric string.

Then, use the Retrieve a database API to get a list of data_sources for that database. There is often only one data source, but when there are multiple, you may have the ID or name of the one you want to retrieve in mind (or you can retrieve each of them). Use that data source ID with this endpoint to get its properties. To get a data source ID from the Notion app directly, the settings menu for a database includes a "Copy data source ID" button under "Manage data sources":

Refer to the Build your first integration guide for more details.

Additional resources

• How to share a database with your integration
• Working with databases guide

Errors

ErrorsEach Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Resources

• Retrieve a database
• Build your first integration guide
• Error codes section
• How to share a database with your integration
• Working with databases guide
• database relations
• linked data source
• Retrieve a data source

Code Samples

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.dataSources.retrieve({
data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
})

@spec update(term(), map(), keyword()) :: {:ok, term()} | {:error, term()}

Update a data source

Source Context

Warnings

The following data source properties cannot be updated via the API:

• formula
• status
• Synced content
• place

Notes

Data source relations must be shared with your integration

To update a data source relation property, the related database must also be shared with your integration.

How data sources property type changes work

All properties in pages are stored as rich text. Notion will convert that rich text based on the types defined in a data source's schema. When a type is changed using the API, the data will continue to be available, it is just presented differently. For example, a multi select property value is represented as a comma-separated list of strings (eg. "1, 2, 3") and a people property value is represented as a comma-separated list of IDs. These are compatible and the type can be converted. Note: Not all type changes work. In some cases data will no longer be returned, such as people type → file type.

Interacting with data source rows

This endpoint cannot be used to update data source rows. To update the properties of a data source row — rather than a column — use the Update page endpoint. To add a new row to a database, use the Create a page endpoint.

Recommended data source schema size limit

Developers are encouraged to keep their data source schema size to a maximum of 50KB. To stay within this schema size limit, the number of properties (or columns) added to a data source should be managed. Data source schema updates that are too large will be blocked by the REST API to help developers keep their data source queries performant. When a schema update is blocked, the error response includes a validation_error code with a message identifying the largest property by name, ID, and byte size to help you reduce your schema size.

Errors

Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Resources

• Update page
• Create a page
• Error codes section
• Synced content
• relation
• Update a data source

Code Samples

TypeScript SDK

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.dataSources.update({
data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce",
title: [{ text: { content: "Updated Data Source Name" } }]
})