Skip to main content
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.
FormMeaningExample
path=valueBody field with a string valueparent[page_id]=abc123
path:=jsonBody field parsed as JSONarchived:=true
name==valueQuery parameterpage_size==100
Header:ValueRequest headerAccept: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

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

​
Next steps

https://mintcdn.com/notion-demo/yKfkO8UsVZTLLPNp/icons/nds/arrowTrayUp.svg?fit=max&auto=format&n=yKfkO8UsVZTLLPNp&q=85&s=3b991e18c85512f06c2d7214acf94f12

File uploads

Upload local files or import external files into Notion.
https://mintcdn.com/notion-demo/7WdlNb9IZkRhGCcR/icons/nds/curlyBraces.svg?fit=max&auto=format&n=7WdlNb9IZkRhGCcR&q=85&s=46f7a8b4a34544f9b03002e4ecc35ad5

API reference

Browse Notion API endpoints and schemas.