> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/makenotion/notion-sdk-js/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get up and running with the Notion SDK in minutes

<Note>
  Before you begin, make sure you've followed Notion's [Getting Started Guide](https://developers.notion.com/docs/getting-started) to create an integration and obtain an API token.
</Note>

## Installation

First, install the Notion SDK:

```bash theme={null}
npm install @notionhq/client
```

## Initialize the Client

Import and initialize a client using your **integration token**:

<CodeGroup>
  ```javascript CommonJS theme={null}
  const { Client } = require("@notionhq/client")

  const notion = new Client({
    auth: process.env.NOTION_TOKEN,
  })
  ```

  ```javascript ES Modules theme={null}
  import { Client } from "@notionhq/client"

  const notion = new Client({
    auth: process.env.NOTION_TOKEN,
  })
  ```

  ```typescript TypeScript theme={null}
  import { Client } from "@notionhq/client"

  const notion = new Client({
    auth: process.env.NOTION_TOKEN,
  })
  ```
</CodeGroup>

<Warning>
  Never hardcode your API token directly in your code. Always use environment variables or a secure configuration management system.
</Warning>

## Make Your First API Call

Once initialized, you can make requests to any Notion API endpoint. Here's an example that lists all users in your workspace:

```javascript theme={null}
;(async () => {
  const listUsersResponse = await notion.users.list({})
  console.log(listUsersResponse)
})()
```

### Example Response

Each method returns a `Promise` that resolves with the API response:

```json theme={null}
{
  "results": [
    {
      "object": "user",
      "id": "d40e767c-d7af-4b18-a86d-55c61f1e39a4",
      "type": "person",
      "person": {
        "email": "avo@example.org"
      },
      "name": "Avocado Lovelace",
      "avatar_url": "https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg"
    }
  ]
}
```

## Query a Data Source

Here's a more advanced example that queries a data source with filters:

```javascript theme={null}
const myPage = await notion.dataSources.query({
  data_source_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  filter: {
    property: "Landmark",
    rich_text: {
      contains: "Bridge",
    },
  },
})
```

<Tip>
  Endpoint parameters are grouped into a single object. You don't need to remember which parameters go in the path, query, or body.
</Tip>

## Complete Example

Here's a complete working example that creates a new page in a database:

<Steps>
  <Step title="Set up your environment">
    Create a `.env` file in your project root:

    ```bash theme={null}
    NOTION_TOKEN=secret_your_integration_token_here
    DATABASE_ID=your_database_id_here
    ```
  </Step>

  <Step title="Create your script">
    Create a file called `create-page.js`:

    ```javascript theme={null}
    const { Client } = require("@notionhq/client")

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

    async function createPage() {
      try {
        const response = await notion.pages.create({
          parent: {
            database_id: process.env.DATABASE_ID,
          },
          properties: {
            Name: {
              title: [
                {
                  text: {
                    content: "My New Page",
                  },
                },
              ],
            },
          },
        })
        
        console.log("Page created successfully!")
        console.log("Page ID:", response.id)
      } catch (error) {
        console.error("Error creating page:", error.message)
      }
    }

    createPage()
    ```
  </Step>

  <Step title="Run your script">
    Execute the script:

    ```bash theme={null}
    node create-page.js
    ```
  </Step>
</Steps>

## Error Handling

Always wrap your API calls in try-catch blocks to handle errors gracefully:

```javascript theme={null}
const { Client, APIErrorCode } = require("@notionhq/client")

try {
  const notion = new Client({ auth: process.env.NOTION_TOKEN })
  const myPage = await notion.dataSources.query({
    data_source_id: dataSourceId,
    filter: {
      property: "Landmark",
      rich_text: {
        contains: "Bridge",
      },
    },
  })
} catch (error) {
  if (error.code === APIErrorCode.ObjectNotFound) {
    // Handle by asking the user to select a different data source
    console.error("Data source not found")
  } else {
    // Other error handling code
    console.error(error)
  }
}
```

<Info>
  The SDK provides typed error codes through the `APIErrorCode` enum, making it easy to handle specific error scenarios.
</Info>

## Available Endpoints

The client provides access to all Notion API endpoints through intuitive namespaces:

* `notion.blocks` - Block CRUD operations
* `notion.databases` - Database CRUD operations
* `notion.dataSources` - Data source operations and querying
* `notion.pages` - Page CRUD operations
* `notion.users` - User listing and retrieval
* `notion.comments` - Comment CRUD operations
* `notion.fileUploads` - File upload lifecycle management
* `notion.search()` - Search across workspace

<Note>
  For a complete list of available methods and parameters, see the [API Reference](https://developers.notion.com/reference).
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about authentication options including OAuth
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/error-handling">
    Master error handling with typed error codes
  </Card>

  <Card title="TypeScript Support" icon="code" href="/typescript">
    Leverage full TypeScript support and type guards
  </Card>

  <Card title="Examples" icon="book" href="https://github.com/makenotion/notion-cookbook/tree/main/examples">
    Explore more examples in the Notion Cookbook
  </Card>
</CardGroup>