API requests

Make Notion API requests from the terminal.

Use ntn api to make authenticated Notion API requests from your terminal. It is useful when you want to inspect an endpoint, test a request body, script an API call, or debug a response without setting up a separate HTTP client.

ntn api adds the Authorization and Notion-Version headers for you. It uses your CLI authentication by default, or a token from NOTION_API_TOKEN when you set one.

Make a request

Pass a Notion API path after ntn api. The leading slash is optional:

ntn api v1/pages/$PAGE_ID
ntn api /v1/pages/$PAGE_ID

Without request body input, ntn api sends a GET request.

To send a request body, add inline body fields:

ntn api v1/pages \
  parent[page_id]="$PARENT_PAGE_ID" \
  properties[Name][title][0][text][content]="CLI-created page"

When body fields are present, ntn api sends a POST request unless you override the method.

Use -X when the endpoint needs a different method:

ntn api "v1/pages/$PAGE_ID" -X PATCH archived:=true

Build request data inline

Inline inputs after the path can set body fields, query parameters, and request headers.

Form	Meaning	Example
path=value	Body field with a string value	parent[page_id]=abc123
path:=json	Body field parsed as JSON	archived:=true
name==value	Query parameter	page_size==100
Header:Value	Request header	Accept:application/json

Use = when the value should be a string:

ntn api v1/search query=roadmap

Use := when the value should keep its JSON type:

ntn api "v1/pages/$PAGE_ID" -X PATCH \
  archived:=false \
  properties[Priority][number]:=2

Typed values can be booleans, numbers, strings, arrays, objects, or null:

ntn api v1/search \
  filter:='{"property":"object","value":"page"}' \
  page_size:=10

Choose body syntax

For nested objects, use bracket or dot notation:

ntn api v1/pages \
  parent[page_id]="$PARENT_PAGE_ID" \
  properties.Name.title[0].text.content="Meeting notes"

Use explicit array indexes when order matters:

ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \
  children[0][type]=paragraph \
  children[0][paragraph][rich_text][0][text][content]="First paragraph" \
  children[1][type]=heading_2 \
  children[1][heading_2][rich_text][0][text][content]="Next section"

Use [] to append repeated values in input order:

ntn api v1/comments \
  parent[page_id]="$PAGE_ID" \
  rich_text[][text][content]="First comment line" \
  rich_text[][text][content]="Second comment line"

Bracket notation is safest for keys that contain punctuation or spaces:

ntn api "v1/pages/$PAGE_ID" -X PATCH \
  properties[Build version][rich_text][0][text][content]="2026.05.11"

Inline request syntax is inspired by HTTPie and implemented in httpcliparser.

Send JSON from a file or stdin

Use inline inputs for small bodies. Use stdin or --data when the body is easier to write as JSON.

Send a JSON file:

ntn api v1/pages < create-page.json

Pipe generated JSON:

jq -n --arg page_id "$PARENT_PAGE_ID" '{
  parent: { page_id: $page_id },
  properties: {
    title: {
      title: [{ text: { content: "Generated page" } }]
    }
  }
}' | ntn api v1/pages

Pass a JSON string directly:

ntn api v1/search --data '{"query":"roadmap","page_size":10}'

Only use one body source per request: stdin JSON, --data, or inline body fields. You can still combine headers and query parameters with any one body source.

Add query parameters and headers

Use == for query parameters:

ntn api v1/search query==roadmap page_size==10

Use Header:Value for request headers:

ntn api v1/users \
  Accept:application/json \
  X-Trace-Id:cli-test-123

Repeated query parameters and headers are preserved in the order you pass them.

ntn api already sets Authorization and Notion-Version. You usually do not need to pass those headers manually.

Override the API version

By default, ntn api fetches the latest supported Notion-Version.

Use --notion-version for one request:

ntn api v1/users/me --notion-version 2026-03-11

Use NOTION_API_VERSION for a shell session or script:

export NOTION_API_VERSION=2026-03-11
ntn api v1/users/me

Inspect endpoints before calling them

List the public API surface:

ntn api ls

Print it as JSON for scripts:

ntn api ls --json

Show the live endpoint help for a path:

ntn api v1/comments --help

Print the reduced OpenAPI fragment for an endpoint:

ntn api v1/comments --spec -X POST

Print the official markdown reference page for an endpoint:

ntn api v1/comments --docs -X POST

If a path supports multiple methods, pass -X so ntn api knows which operation to inspect.

Debug a request

Run with --verbose to print request and response metadata to stderr:

ntn --verbose api v1/pages/$PAGE_ID

Verbose output includes the final method, URL, request headers, JSON request body, response status, response headers, and response body. The Authorization request header is redacted by default.

--unsafe-verbose is a hidden debugging flag that disables Authorization header redaction in verbose logs. It is dangerous because it can display your bearer token in command output. Only use it in a controlled local environment, and never paste its output into shared logs, tickets, or chat.

Troubleshooting

Problem	What to check
The request used POST unexpectedly	Body input, --data, or stdin JSON makes POST the default. Use -X to override it.
An inline value has the wrong type	Use := for JSON values like true, 10, null, arrays, and objects. Use = only for strings.
A nested body path is hard to read	Prefer bracket notation, especially for property names with spaces or punctuation.
--spec or --docs says the method is ambiguous	Add -X GET, -X POST, -X PATCH, or the method you want to inspect.
The body source conflicts	Use only one of stdin JSON, --data, or inline body fields.
You need to inspect a failing request	Add --verbose and check the final method, URL, status, and x-request-id.

Next steps

File uploads

Upload local files or import external files into Notion.

API reference

Browse Notion API endpoints and schemas.