### JavaScript SDK Example

Source: https://developers.notion.com/reference/intro

Example of making an API request using the Notion JavaScript SDK. Ensure the SDK is installed before use.

```javascript
import { Client } from "@notionhq/client";

const notion = new Client({ auth: "YOUR_API_KEY" });

async function main() {
  const response = await notion.pages.list({
    // other query options
  });
  console.log(response);
}

main();
```

--------------------------------

### Example Verification Property Values

Source: https://developers.notion.com/reference/page-property-values

Examples of how the 'verification' property might appear in a GET page request response, illustrating different verification states.

```APIDOC
### Example `verification` page property values as returned in a GET page request

#### Unverified
```json
{
  "Verification": {
    "id": "fpVq",
    "type": "verification",
    "verification": {
      "state": "unverified",
      "verified_by": null,
      "date": null
    }
  }
}
```

#### Verified with no expiration date set
```json
{
  "Verification": {
    "id": "fpVq",
    "type": "verification",
    "verification": {
      "state": "verified",
      "verified_by": {
        "object": "user",
        "id": "01e46064-d5fb-4444-8ecc-ad47d076f804",
        "name": "User Name",
        "avatar_url": null,
        "type": "person",
        "person": {}
      },
      "date": {
        "start": "2023-08-01T04:00:00.000Z",
        "end": null,
        "time_zone": null
      }
    }
  }
}
```

#### Verified with 90-day expiration date
```json
{
  "Verification": {
    "id": "fpVq",
    "type": "verification",
    "verification": {
      "state": "verified",
      "verified_by": {
        "object": "user",
        "id": "01e46064-d5fb-4444-8ecc-ad47d076f804"
      },
      "date": {
        "start": "2023-08-01T04:00:00.000Z",
        "end": "2023-10-30T04:00:00.000Z",
        "time_zone": null
      }
    }
  }
}
```
```

--------------------------------

### Example: Setting an Icon

Source: https://developers.notion.com/reference/page-property-values

Examples of how to structure the 'icon' object in a request body to set an icon for a page.

```APIDOC
## Example: Setting an Icon

### Emoji Icon
```json
{
  "icon": { "type": "emoji", "emoji": "🥑" }
}
```

### Native Icon
```json
{
  "icon": {
    "type": "icon",
    "icon": { "name": "pizza", "color": "blue" }
  }
}
```

### Custom Emoji (by ID)
```json
{
  "icon": {
    "type": "custom_emoji",
    "custom_emoji": { "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b" }
  }
}
```

### File Upload Icon
```json
{
  "icon": {
    "type": "file_upload",
    "file_upload": { "id": "43833259-72ae-404e-8441-b6577f3159b4" }
  }
}
```
```

--------------------------------

### Select Page Property Value Example

Source: https://developers.notion.com/reference/page-property-values

Example of a select page property value as returned in a GET page request. Includes the option's ID, name, and color.

```json
{
  "Department": {
    "id": "Yc%3FJ",
    "type": "select",
    "select": {
      "id": "ou@_",
      "name": "jQuery",
      "color": "purple"
    }
  }
}
```

--------------------------------

### Example url property value in GET request

Source: https://developers.notion.com/reference/page-property-values

This JSON illustrates the format of a 'url' property as returned in a GET page request. The 'Website' key is the name of the URL property.

```json
{
  "Website": {
    "id": "bB%3D%5B",
    "type": "url",
    "url": "https://developers.notion.com/"
  }
}
```

--------------------------------

### cURL Example

Source: https://developers.notion.com/reference/intro

Example of making an API request using cURL. This is useful for quick testing or when an SDK is not available.

```bash
curl --request GET 'https://api.notion.com/v1/pages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Notion-Version: 2022-06-28'
```

--------------------------------

### Example Icon Responses

Source: https://developers.notion.com/reference/page-property-values

Examples of how the 'icon' object is returned in API responses for different types.

```APIDOC
## Example Icon Responses

### Emoji Icon
```json
{
  "icon": {
    "type": "emoji",
    "emoji": "😀"
  }
}
```

### Native Icon
```json
{
  "icon": {
    "type": "icon",
    "icon": {
      "name": "pizza",
      "color": "blue"
    }
  }
}
```

### Custom Emoji
```json
{
  "icon": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b",
      "name": "bufo",
      "url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/865e85fc-7442-44d3-b323-9b03a2111720/3c6796979c50f4aa.png"
    }
  }
}
```

### Notion-hosted File Icon
```json
{
  "icon": {
    "type": "file",
    "file": {
      "url": "https://local-files-secure.s3.us-west-2.amazonaws.com/...",
      "expiry_time": "2024-12-03T19:44:56.932Z"
    }
  }
}
```
```

--------------------------------

### Example Created By User Object

Source: https://developers.notion.com/reference/page-property-values

This JSON object represents the 'created_by' property as returned in a GET page request. The 'created_by' field cannot be updated.

```json
{
  "created_by": {
    "object": "user",
    "id": "c2f20311-9e54-4d11-8c79-7398424ae41e"
  }
}
```

--------------------------------

### Apply sorting to Notion SDK for JavaScript query

Source: https://developers.notion.com/reference/sort-data-source-entries

This JavaScript example demonstrates how to apply a sort to a Notion data source query using the Notion SDK. Ensure you have the SDK installed and your API key configured.

```javascript
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });
// replace with your own data source ID
const dataSourceId = 'd9824bdc-8445-4327-be8b-5b47500af6ce';

const sortedRows = async () => {
  const response = await notion.dataSources.query({
    database_id: databaseId,
    sorts: [
      {
        "property": "Name",
        "direction": "ascending"
      }
    ],
  });
  return response;
}
```

--------------------------------

### Notion-hosted File Object Example

Source: https://developers.notion.com/reference/file-object

Represents a file uploaded manually in the Notion UI. The URL is temporary and valid for one hour; re-fetch the file object to get an updated URL if it expires.

```json
{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/...",
    "expiry_time": "2025-04-24T22:49:22.765Z"
  }
}
```

--------------------------------

### Multi-select Property Value Example

Source: https://developers.notion.com/reference/property-item-object

An example of a multi-select property value object, showing an array of selected options with their IDs, names, and colors.

```json
{
  "Tags": {
    "object": "property_item",
    "id": "z%7D%5C%3C",
    "type": "multi_select",
    "multi_select": [
      {
        "id": "91e6959e-7690-4f55-b8dd-d3da9debac45",
        "name": "A",
        "color": "orange"
      },
      {
        "id": "2f998e2d-7b1c-485b-ba6b-5e6a815ec8f5",
        "name": "B",
        "color": "purple"
      }
    ]
  }
}
```

--------------------------------

### Get Number property value

Source: https://developers.notion.com/reference/page-property-values

This is an example of a Number property value as returned in a GET page request.

```json
{
  "Number of subscribers": {
    "id": "WPj%5E",
    "type": "number",
    "number": 42
  }
}
```

--------------------------------

### Get Phone number property value

Source: https://developers.notion.com/reference/page-property-values

This is an example of a Phone number property value as returned in a GET page request.

```json
{
  "Contact phone number": {
    "id": "%5DKhQ",
    "type": "phone_number",
    "phone_number": "415-202-4776"
  }
}
```

--------------------------------

### Example Icon Object

Source: https://developers.notion.com/reference/emoji-and-icon

Represents a native Notion icon with a specified name and color.

```json
{
  "type": "icon",
  "icon": {
    "name": "pizza",
    "color": "blue"
  }
}
```

--------------------------------

### Get People property value

Source: https://developers.notion.com/reference/page-property-values

This is an example of a People property value as returned in a GET page request. It includes user details.

```json
{
  "Stakeholders": {
    "id": "%7BLUX",
    "type": "people",
    "people": [
      {
        "object": "user",
        "id": "c2f20311-9e54-4d11-8c79-7398424ae41e",
        "name": "Kimberlee Johnson",
        "avatar_url": null,
        "type": "person",
        "person": {
          "email": "[email protected]"
        }
      }
    ]
  }
}
```

--------------------------------

### Paginate through query results from a data source

Source: https://developers.notion.com/reference/intro

This example demonstrates how to paginate through query results from a data source using a POST request. It shows how to include the `start_cursor` in the request body.

```APIDOC
## POST /v1/data_sources/<data_source_id>/query

### Description
Sends a paginated request to query data sources, including a `start_cursor` to retrieve subsequent pages of results.

### Method
POST

### Endpoint
/v1/data_sources/<data_source_id>/query

### Parameters
#### Query Parameters
* `page_size` (number) - Optional - The number of items from the full list to include in the response. Defaults to 100. Maximum is 100.
* `start_cursor` (string) - Optional - A `next_cursor` value returned in a previous response. Defaults to `undefined`, which returns results from the beginning of the list.

#### Request Body
* `start_cursor` (string) - Optional - A `next_cursor` value returned in a previous response. Treat this as an opaque value.

### Request Example
```json
{
  "start_cursor": "33e19cb9-751f-4993-b74d-234d67d0d534"
}
```

### Response
#### Success Response (200)
* `next_cursor` (string) - A cursor to retrieve the next page of results. Only available when `has_more` is `true`.
* `has_more` (boolean) - Indicates if there are more pages of results.

#### Response Example
```json
{
  "next_cursor": "some-next-cursor-value",
  "has_more": true
}
```
```

--------------------------------

### Initialize Notion Client

Source: https://developers.notion.com/reference/create-a-token

Initializes the Notion client using the TypeScript SDK. This is a common setup step for interacting with the Notion API.

```typescript
import { Client } from "@notionhq/client"

const notion = new Client()
```

--------------------------------

### Query Data Source

Source: https://developers.notion.com/reference/query-a-data-source

This example demonstrates how to query a data source, applying filters and sorting to the results.

```APIDOC
## POST /v1/data_sources/{data_source_id}/query

### Description
Retrieves a list of pages or data source objects from a data source.

### Method
POST

### Endpoint
/v1/data_sources/{data_source_id}/query

### Parameters
#### Path Parameters
- **data_source_id** (string) - Required - The ID of the data source to query.

#### Request Body
- **filter** (object) - Optional - Filter criteria for the query. See [Filters](https://developers.notion.com/reference/filter).
- **sorts** (array) - Optional - Sorting criteria for the query. See [Sorts](https://developers.notion.com/reference/sort-object).
- **query** (string) - Optional - A query to search across the data source.
- **filter_by_external_database** (object) - Optional - Filter criteria for external databases.
- **page_size** (integer) - Optional - The number of results to return per page.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

### Response
#### Success Response (200)
- **object** (string) - The type of object, e.g. "list".
- **next_cursor** (string) - A cursor for fetching the next page of results.
- **has_more** (boolean) - Whether there are more results available.
- **results** (array) - An array of page or data source objects.
- **request_status** (object) - The status of the request.
  - **type** (string) - The type of status, e.g. "complete" or "incomplete".
  - **incomplete_reason** (string) - The reason for the incomplete status, if applicable.

#### Response Example
```json
{
  "object": "list",
  "next_cursor": "gAAAAAB...",
  "has_more": true,
  "results": [
    {
      "object": "page",
      "id": "d9824bdc-8445-4327-be8b-5b47500af6ce",
      "created_time": "2021-05-18T13:30:00.000Z",
      "last_edited_time": "2021-05-18T13:30:00.000Z",
      "parent": {
        "type": "page_id",
        "page_id": "f702511b-7340-433f-820a-000000000000"
      },
      "archived": false,
      "properties": {},
      "url": "https://www.notion.so/d9824bdc84454327be8b5b47500af6ce"
    }
  ],
  "request_status": {
    "type": "complete"
  }
}
```
```

--------------------------------

### Get Files Property Value

Source: https://developers.notion.com/reference/page-property-values

This is an example of a 'files' page property value as returned in a GET page request. It includes file name, type, and external URL.

```json
{
  "Blueprint": {
    "id": "tJPS",
    "type": "files",
    "files": [
      {
        "name": "Project blueprint",
        "type": "external",
        "external": {
          "url": "https://www.figma.com/file/g7eazMtXnqON4i280CcMhk/project-alpha-blueprint?node-id=0%3A1&t=nXseWIETQIgv31YH-1"
        }
      }
    ]
  }
}
```

--------------------------------

### Sample X-Notion-Signature Header

Source: https://developers.notion.com/reference/webhooks

This is an example of the X-Notion-Signature header that Notion includes with webhook events.

```json
{
  "X-Notion-Signature": "sha256=461e8cbcba8a75c3edd866f0e71280f5a85cbf21eff040ebd10fe266df38a735"
}
```

--------------------------------

### Retrieve a View with Filters

Source: https://developers.notion.com/reference/retrieve-a-view

This example demonstrates how to retrieve a view from a database, applying compound filters using OR logic on property and timestamp conditions.

```APIDOC
## GET /databases/{database_id}/query

### Description
Retrieves a view of a database, allowing for complex filtering based on property values and timestamps.

### Method
GET

### Endpoint
/databases/{database_id}/query

### Parameters
#### Query Parameters
- **filter** (object) - Optional - An object defining the filter conditions for the view.
  - **or** (array) - Required - An array of filter conditions combined with OR logic.
    - **property** (string) - Required - The name or ID of the property to filter on.
    - **timestamp** (string) - Required - The timestamp to filter on. Enum: `created_time`, `last_edited_time`.
    - **or** (array) - Optional - Nested OR logic for deeper filtering.
    - **and** (array) - Optional - Nested AND logic for deeper filtering.

### Request Example
```json
{
  "filter": {
    "or": [
      {
        "property": "Status",
        "equals": "Done"
      },
      {
        "timestamp": "last_edited_time",
        "after": "2023-01-01T12:00:00Z"
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **object** (object) - The retrieved view of the database.

#### Response Example
```json
{
  "object": "list",
  "results": [
    {
      "id": "some-page-id",
      "properties": {
        "Name": {
          "title": [
            {
              "text": {
                "content": "Example Page"
              }
            }
          ]
        },
        "Status": {
          "select": {
            "name": "Done"
          }
        }
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```
```

--------------------------------

### Example unique_id property value in GET request

Source: https://developers.notion.com/reference/page-property-values

This JSON shows the structure of a 'unique_id' property as returned by a GET page request. The 'test-ID' key is the name of the unique ID property.

```json
{
  "test-ID": {
    "id": "tqqd",
    "type": "unique_id",
    "unique_id": {
      "number": 3,
      "prefix": "RL"
    }
  }
}
```

--------------------------------

### Create a Table View

Source: https://developers.notion.com/reference/create-view

Creates a new table view for a specified database. This example demonstrates how to set the database ID, data source ID, view name, and view type.

```APIDOC
## POST /views

### Description
Creates a new view for a database or dashboard.

### Method
POST

### Endpoint
/views

### Parameters
#### Request Body
- **data_source_id** (string) - Required - The ID of the data source this view should be scoped to.
- **name** (string) - Required - The name of the view.
- **type** (string) - Required - The type of view to create. Supported types include table, board, list, calendar, timeline, gallery, form, chart, map, and dashboard.
- **database_id** (string) - Optional - The ID of the database to create a view in. Mutually exclusive with `view_id` and `create_database`.
- **view_id** (string) - Optional - The ID of a dashboard view to add this view to as a widget. Mutually exclusive with `database_id` and `create_database`.
- **filter** (object) - Optional - Filter to apply to the view. Uses the same format as the data source query filter.
- **sorts** (object) - Optional - Sorts to apply to the view. Uses the same format as the data source query sorts.
- **quick_filters** (object) - Optional - Quick filters to pin in the view's filter bar. Keys are property names or IDs. Values are filter conditions.
- **create_database** (object) - Optional - Create a new linked database block on a page and add the view to it. Mutually exclusive with `database_id` and `view_id`.
- **configuration** (object) - Optional - View presentation configuration. The type field must match the view type.
- **position** (string) - Optional - Where to place the new view in the database's view tab bar. Only applicable when `database_id` is provided. Defaults to "end" (append).
- **placement** (string) - Optional - Where to place the new widget in a dashboard view. Only applicable when `view_id` is provided. Defaults to creating a new row at the end.

### Request Example
```json
{
  "database_id": "248104cd-477e-80fd-b757-e945d38000bd",
  "data_source_id": "248104cd-477e-80af-bc30-000bd28de8f9",
  "name": "High priority items",
  "type": "table"
}
```

### Response
#### Success Response (200)
- **object** (string) - The object type name, always "view".
- **id** (string) - The ID of the view.
- **parent** (object) - The parent database of the view.
- **type** (string) - The view type (e.g., table, board, list, calendar, timeline, gallery, form, chart, map, dashboard).
- **name** (string) - The name of the view.
```

--------------------------------

### Example title property value in GET request

Source: https://developers.notion.com/reference/page-property-values

This JSON shows the structure of a 'title' property as returned by a GET page request. Note that titles can contain rich text objects.

```json
{
  "Title": {
    "id": "title",
    "type": "title",
    "title": [
      {
        "type": "text",
        "text": {
          "content": "A better title for the page",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "This is also not done",
        "href": null
      }
    ]
  }
}
```

--------------------------------

### Retrieve Database with TypeScript SDK

Source: https://developers.notion.com/reference/retrieve-database

Example of using the TypeScript SDK to retrieve a database. Ensure your Notion API key is set as an environment variable.

```javascript
import { Client } from "@notionhq/client"

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

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

--------------------------------

### Rich Text Page Property Value Example

Source: https://developers.notion.com/reference/page-property-values

Example of a rich_text page property value as returned in a GET page request. This shows how text can be formatted with annotations like bold.

```json
{
  "Description": {
    "id": "HbZT",
    "type": "rich_text",
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "There is some ",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "There is some ",
        "href": null
      },
      {
        "type": "text",
        "text": {
          "content": "text",
          "link": null
        },
        "annotations": {
          "bold": true,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": "text",
        "href": null
      },
      {
        "type": "text",
        "text": {
          "content": " in this property!",
          "link": null
        },
        "annotations": {
          "bold": false,
          "italic": false,
          "strikethrough": false,
          "underline": false,
          "code": false,
          "color": "default"
        },
        "plain_text": " in this property!",
        "href": null
      }
    ]
  }
}
```

--------------------------------

### Rollup Property Example

Source: https://developers.notion.com/reference/page-property-values

Example of a rollup page property value as returned in a GET page request. For rollup properties with more than 25 references, use the Retrieve a page property endpoint.

```APIDOC
## Rollup Property Example

### Description
Example of a rollup page property value as returned in a GET page request.

### Method
GET

### Endpoint
/v1/pages/{page_id}

### Response
#### Success Response (200)
- **Number of units** (object) - Example rollup property.
  - **id** (string) - Property ID.
  - **type** (string) - Property type, 'rollup'.
  - **rollup** (object) - Rollup details.
    - **type** (string) - Type of rollup calculation (e.g., 'number').
    - **number** (number) - The calculated number value.
    - **function** (string) - The rollup function used (e.g., 'count').

#### Response Example
```json
{
  "Number of units": {
    "id": "hgMz",
    "type": "rollup",
    "rollup": {
      "type": "number",
      "number": 2,
      "function": "count"
    }
  }
}
```

### Notes
- For rollup properties with more than 25 references, use the Retrieve a page property endpoint.
- The API does not support updating `rollup` page property values. Use the Notion UI to change them.
```

--------------------------------

### Create Database

Source: https://developers.notion.com/reference/create-a-database

This section details the structure for creating a new database, including its title and the configuration for its properties.

```APIDOC
## POST /databases

### Description
Creates a new database with a specified title and property configurations.

### Method
POST

### Endpoint
/databases

### Parameters
#### Request Body
- **title** (string) - Required - The title of the database.
- **properties** (object) - Required - An object containing the configurations for each property in the database.

### Request Example
```json
{
  "title": "My New Database",
  "properties": {
    "Name": {
      "title": {}
    },
    "Description": {
      "rich_text": {}
    },
    "Status": {
      "status": {}
    },
    "Assignee": {
      "people": {}
    },
    "Files": {
      "files": {}
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly created database.
- **title** (array) - The title of the database.
- **properties** (object) - The configurations of the properties in the database.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "My New Database"
      }
    }
  ],
  "properties": {
    "Name": {
      "title": {}
    },
    "Description": {
      "rich_text": {}
    },
    "Status": {
      "status": {}
    },
    "Assignee": {
      "people": {}
    },
    "Files": {
      "files": {}
    }
  }
}
```
```

--------------------------------

### Example Multi-select Page Property Value as Returned in GET Request

Source: https://developers.notion.com/reference/page-property-values

Demonstrates the JSON structure for a 'multi_select' property as returned in a GET page request. Each option includes an ID, name, and color.

```json
{
  "Programming language": {
    "id": "QyRn",
    "name": "Programming language",
    "type": "multi_select",
    "multi_select": [
      {
        "id": "tC;=",
        "name": "TypeScript",
        "color": "purple"
      },
      {
        "id": "e4413a91-9f84-4c4a-a13d-5b4b3ef870bb",
        "name": "JavaScript",
        "color": "red"
      },
      {
        "id": "fc44b090-2166-40c8-8c58-88f2d8085ec0",
        "name": "Python",
        "color": "gray"
      }
    ]
  }
}
```

--------------------------------

### Files Property Management

Source: https://developers.notion.com/reference/page-property-values

Examples for creating, updating, and retrieving Files property values.

```APIDOC
## POST/PATCH /pages

### Description
Creates or updates a page property value, including the 'files' property.

### Method
POST/PATCH

### Endpoint
/pages

### Parameters
#### Request Body
- **properties** (object) - Required - An object containing property values to be updated.
  - **Blueprint** (object) - Required - Represents the 'files' property.
    - **files** (array) - Required - An array of file objects.
      - **name** (string) - Required when using 'external' URL - The name of the file.
      - **external** (object) - Required if not a file upload - Contains the external URL.
        - **url** (string) - Required - The URL of the external file.

### Request Example
```json
{
  "properties": {
    "Blueprint": {
      "files": [
        {
          "name": "Project Alpha blueprint",
          "external": {
            "url": "https://www.figma.com/file/g7eazMtXnqON4i280CcMhk/project-alpha-blueprint?node-id=0%3A1&t=nXseWIETQIgv31YH-1"
          }
        }
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **properties** (object) - The updated properties of the page.
  - **Blueprint** (object) - The 'files' property.
    - **id** (string) - The ID of the property.
    - **type** (string) - The type of the property, always "files".
    - **files** (array) - An array of file objects.
      - **name** (string) - The name of the file.
      - **type** (string) - The type of the file, either "external" or "file".
      - **external** (object) - Present if the file type is "external".
        - **url** (string) - The URL of the external file.

#### Response Example
```json
{
  "properties": {
    "Blueprint": {
      "id": "tJPS",
      "type": "files",
      "files": [
        {
          "name": "Project blueprint",
          "type": "external",
          "external": {
            "url": "https://www.figma.com/file/g7eazMtXnqON4i280CcMhk/project-alpha-blueprint?node-id=0%3A1&t=nXseWIETQIgv31YH-1"
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### Example Date Property Value as Returned in GET Request

Source: https://developers.notion.com/reference/page-property-values

This JSON object shows the 'date' page property value as returned in a GET page request. It includes optional 'end' and 'time_zone' fields.

```json
{
  "Due date": {
    "id": "M%3BBw",
    "type": "date",
    "date": {
      "start": "2023-02-07",
      "end": null,
      "time_zone": null
    }
  }
}
```

--------------------------------

### Example Email Property Value as Returned in GET Request

Source: https://developers.notion.com/reference/page-property-values

This JSON object represents the 'email' page property value as returned in a GET page request. The 'email' field contains the email address as a string.

```json
{
  "Email": {
    "id": "y%5C%5E_",
    "type": "email",
    "email": "ada@makenotion.com"
  }
}
```

--------------------------------

### Example Bookmark Block Object

Source: https://developers.notion.com/reference/block

Represents a bookmark block in Notion. It contains a caption for the bookmark and the URL it links to.

```json
{
  "type": "bookmark",
  "bookmark": {
    "caption": [],
    "url": "https://companywebsite.com"
  }
}
```

--------------------------------

### Query with Filter Properties

Source: https://developers.notion.com/reference/query-a-data-source

Example of a GET request to query a data source, filtering only the 'title' property. This reduces response size and improves performance.

```bash
https://api.notion.com/v1/data_sources/[DATA_SOURCE_ID]/query?filter_properties[]=title
```

--------------------------------

### Create a database

Source: https://developers.notion.com/reference/create-database

Creates a new database in the specified parent page or workspace. You can configure the database's title, description, icon, cover, and initial data source.

```APIDOC
## POST /v1/databases

### Description
Creates a new database in the specified parent page or workspace. You can configure the database's title, description, icon, cover, and initial data source.

### Method
POST

### Endpoint
/v1/databases

### Parameters
#### Query Parameters
- **notion_version** (string) - Required - The version of the Notion API to use.

#### Request Body
- **parent** (object) - Required - The parent page or workspace where the database will be created.
  - **type** (string) - Required - The type of parent. Enum: `page_id`, `workspace`.
  - **page_id** (string) - Required if type is `page_id` - The ID of the parent page.
  - **workspace** (boolean) - Required if type is `workspace` - Always `true`.
- **title** (array) - Required - The title of the database. Items are rich text objects.
- **description** (array) - Optional - The description of the database. Items are rich text objects.
- **is_inline** (boolean) - Optional - Whether the database should be displayed inline in the parent page. Defaults to false.
- **initial_data_source** (object) - Optional - Initial data source configuration for the database.
- **icon** (object) - Optional - The icon for the database.
- **cover** (object) - Optional - The cover image for the database.

### Request Example
```json
{
  "parent": {
    "type": "page_id",
    "page_id": "<page_id>"
  },
  "title": [
    {
      "type": "text",
      "text": {
        "content": "My New Database Title"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **partialDatabaseObjectResponse** (object) - A partial database object.
- **databaseObjectResponse** (object) - A full database object.

#### Response Example
```json
{
  "object": "database",
  "id": "<database_id>",
  "parent": {
    "type": "page_id",
    "page_id": "<page_id>"
  },
  "created_time": "2021-05-17T19:20:00.000Z",
  "last_edited_time": "2021-05-17T19:20:00.000Z",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "My New Database Title",
        "link": null
      },
      "annotations": {
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "code": false
      },
      "plain_text": "My New Database Title",
      "href": null
    }
  ],
  "description": [],
  "is_inline": false,
  "permissions": [
    {
      "type": "user_permission",
      "role": "owner"
    }
  ],
  "properties": {},
  "url": "https://www.notion.so/<owner_username>/<database_title_slug>-<database_id>",
  "icon": null,
  "cover": null
}
```
```

--------------------------------

### Create a database

Source: https://developers.notion.com/reference/create-database

Creates a database as a subpage in the specified parent page, or as a private page at the workspace level, with the specified properties schema set on its initial_data_source. Currently, the parent of a new database must be a Notion page (page_id type) or a wiki database.

```APIDOC
## POST /databases

### Description
Creates a database as a subpage in the specified parent page, or as a private page at the workspace level, with the specified `properties` schema set on its `initial_data_source`. Currently, the `parent` of a new database must be a Notion page (`page_id` type) or a [wiki database](https://www.notion.so/help/wikis-and-verified-pages).

Use this endpoint to create a database, its first [data source](/reference/data-source), and its first table view, all in one API call. Then, if you want to add a second data source, use the [Create a data source](/reference/create-a-data-source) API with a version of at least `2025-09-03`, and provide the `database_id` as the `id` returned by the database create response.

For a complete reference on what properties are available, see [Data source properties](/reference/property-object). After creating the database, to update one of its child data sources' properties, use the [Update a data source](/reference/update-a-data-source) API.

<Info>
  **Connection capabilities**

  > This endpoint requires a connection to have insert content capabilities. Attempting to call this API without insert content capabilities will return an HTTP response with a 403 status code. For more information on connection capabilities, see the [capabilities guide](/reference/capabilities).
</Info>

### Errors

> Returns a 404 if the specified parent page does not exist, or if the connection does not have access to the parent page.

> Returns a 400 if the request is incorrectly formatted, or a 429 HTTP response if the request exceeds the [request limits](/reference/request-limits).

*Note: Each Public API endpoint can return several possible error codes. See the [Error codes section](/reference/status-codes#error-codes) of the Status codes documentation for more information.*

### Method
POST

### Endpoint
/databases

### Parameters
#### Request Body
- **parent** (object) - Required - The parent page or database for the new database.
- **initial_data_source** (object) - Required - The initial data source for the database.
- **properties** (object) - Required - The schema for the database properties.
```

--------------------------------

### Retrieve Status Property Value

Source: https://developers.notion.com/reference/page-property-values

This is an example of a Status page property value as returned in a GET page request. It includes the status ID, name, and color.

```json
{
  "Status": {
    "id": "Z%3ClH",
    "type": "status",
    "status": {
      "id": "539f2705-6529-42d8-a215-61a7183a92c0",
      "name": "In progress",
      "color": "blue"
    }
  }
}
```

--------------------------------

### Select Property - Retrieval Example

Source: https://developers.notion.com/reference/page-property-values

This snippet shows the structure of a 'select' page property value as returned in a GET page request, including its ID, name, and color.

```APIDOC
## Select Property - Retrieval

### Description
Example of a select page property value as returned in a GET page request. This includes the option's ID, name, and color.

### Response Example
```json
{
  "Department": {
    "id": "Yc%3FJ",
    "type": "select",
    "select": {
      "id": "ou@_",
      "name": "jQuery",
      "color": "purple"
    }
  }
}
```
```

--------------------------------

### Example Audio Block Object

Source: https://developers.notion.com/reference/block

Represents an audio block in Notion. It includes a file object detailing the audio file's information, supporting external URLs for audio files.

```json
{
  "type": "audio",
  "audio": {
    "type": "external",
    "external": {
      "url": "https://companywebsite.com/files/sample.mp3"
    }
  }
}
```

--------------------------------

### Retrieve Relation Property Value

Source: https://developers.notion.com/reference/page-property-values

This is an example of a relation page property value as returned in a GET page request. It includes the relation IDs and a has_more flag if applicable.

```json
{
  "Related tasks": {
    "id": "hgMz",
    "type": "relation",
    "relation": [
      {
        "id": "dd456007-6c66-4bba-957e-ea501dcda3a6"
      },
      {
        "id": "0c1f7cb2-8090-4f18-924e-d92965055e32"
      }
    ],
    "has_more": false
  }
}
```

--------------------------------

### Example Created Time Property Value

Source: https://developers.notion.com/reference/page-property-values

This JSON object shows the 'Created time' property value as returned in a GET page request. The 'created_time' value cannot be updated.

```json
{
  "Created time": {
    "id": "eB_%7D",
    "type": "created_time",
    "created_time": "2022-10-24T22:54:00.000Z"
  }
}
```

--------------------------------

### Create a file upload

Source: https://developers.notion.com/reference/create-file

Initiates the process of uploading a file to your Notion workspace. The response is a File Upload object with a status of "pending".

```APIDOC
## POST /v1/file_uploads

### Description
Initiates the process of uploading a file to your Notion workspace. The response is a File Upload object with a status of "pending".

### Method
POST

### Endpoint
/v1/file_uploads

### Parameters
#### Query Parameters
- **notion_version** (string) - Required - The version of the Notion API to use.

#### Request Body
- **mode** (string) - Optional - How the file is being sent. Use `multi_part` for files larger than 20MB. Use `external_url` for files that are temporarily hosted publicly elsewhere. Default is `single_part`.
- **filename** (string) - Optional - Name of the file to be created. Required when `mode` is `multi_part`. Otherwise optional, and used to override the filename. Must include an extension, or have one inferred from the `content_type` parameter.
- **content_type** (string) - Optional - MIME type of the file to be created. Recommended when sending the file in multiple parts. Must match the content type of the file that's sent, and the extension of the `filename` parameter if any.
- **number_of_parts** (integer) - Optional - When `mode` is `multi_part`, the number of parts you are uploading. This must match the number of parts as well as the final `part_number` you send.
- **external_url** (string) - Optional - When `mode` is `external_url`, provide the HTTPS URL of a publicly accessible file to import into your workspace.

### Response
#### Success Response (200)
- **fileUploadObjectResponse** (object) - A File Upload object response.

#### Error Response
- **error_api_400** (object) - Bad Request
- **error_api_401** (object) - Unauthorized
- **error_api_403** (object) - Forbidden
- **error_api_404** (object) - Not Found
```

--------------------------------

### List View Configuration

Source: https://developers.notion.com/reference/create-view

Configure a list view with property visibility and display settings.

```APIDOC
## List View Configuration

### Description
Configures a list view, specifying property visibility and display settings.

### Type
`list`

### Parameters
#### Required
- **type** (string) - The view type. Must be "list".

#### Optional
- **properties** (array[viewPropertyConfigRequest] | null) - Property visibility and display configuration. Max items: 100. Pass null to clear.
```

--------------------------------

### Verified Page Verification Status (With Expiration)

Source: https://developers.notion.com/reference/page-property-values

Example JSON response for a page that is 'verified' with a specified expiration date. The 'date' object includes both 'start' and 'end' timestamps.

```json
{
  "Verification": {
    "id": "fpVq",
    "type": "verification",
    "verification": {
      "state": "verified",
      "verified_by": {
        "object": "user",
        "id": "01e46064-d5fb-4444-8ecc-ad47d076f804"
      },
      "date": {
        "start": "2023-08-01T04:00:00.000Z",
        "end": "2023-10-30T04:00:00.000Z",
        "time_zone": null
      }
    }
  }
}
```

--------------------------------

### Example Heading 1 Block Object

Source: https://developers.notion.com/reference/block

Illustrates the JSON structure for a heading_1 block. This is a static heading.

```json
{
  //...other keys excluded
  "type": "heading_1",
  //...other keys excluded
  "heading_1": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "Lacinato kale",
          "link": null
        }
      }
    ],
    "color": "default",
    "is_toggleable": false
  }
}
```

--------------------------------

### Query with Multiple Filter Properties

Source: https://developers.notion.com/reference/query-a-data-source

Example of a GET request to query a data source, filtering for both 'title' and 'status' properties. Multiple properties can be specified by chaining the query parameter.

```bash
https://api.notion.com/v1/data_sources/[DATA_SOURCE_ID]/query?filter_properties[]=title&filter_properties[]=status
```