Endpoints

Call these through the okoro proxy at https://okoro.ai/p/notion

Action	Method	Min scope
Create page	`POST`	`read`
Update page	`PATCH`	`update`
Read page	`GET`	`read`
Create database	`POST`	`read`
Update database	`PATCH`	`update`
Query database	`POST`	`read`
Read database	`GET`	`read`
Update block	`PATCH`	`update`
Delete block	`DELETE`	`delete`
List blocks	`GET`	`read`
Read block	`GET`	`read`
Append blocks	`POST`	`read`
Read user	`GET`	`read`
List users	`GET`	`read`
Search	`POST`	`read`
Create comment	`POST`	`read`
Read comments	`GET`	`read`

Examples

Every request requires a short-lived operation token scoped to a single action.

1. Get an operation token

Exchange your service token for a short-lived operation token scoped to a single action.

TOKEN=$(curl -sX POST "https://okoro.ai/t/tokens" \
  -H "Authorization: Bearer $OKORO_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider": "notion", "scope": "read", "intent": "describe what you are doing"}' \
  | jq -r '.token')

2. Call the API

Use the operation token as a Bearer token. The proxy forwards the request to Notion and logs the action.

Create page

curl -X POST "https://okoro.ai/p/notion/v1/pages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Update page

curl -X PATCH "https://okoro.ai/p/notion/v1/pages/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Read page

curl -X GET "https://okoro.ai/p/notion/v1/pages/{id}" \
  -H "Authorization: Bearer $TOKEN"

Create database

curl -X POST "https://okoro.ai/p/notion/v1/databases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Update database

curl -X PATCH "https://okoro.ai/p/notion/v1/databases/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Query database

curl -X POST "https://okoro.ai/p/notion/v1/databases/{id}/query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Read database

curl -X GET "https://okoro.ai/p/notion/v1/databases/{id}" \
  -H "Authorization: Bearer $TOKEN"

Update block

curl -X PATCH "https://okoro.ai/p/notion/v1/blocks/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete block

curl -X DELETE "https://okoro.ai/p/notion/v1/blocks/{id}" \
  -H "Authorization: Bearer $TOKEN"

List blocks

curl -X GET "https://okoro.ai/p/notion/v1/blocks/{id}/children" \
  -H "Authorization: Bearer $TOKEN"

Read block

curl -X GET "https://okoro.ai/p/notion/v1/blocks/{id}" \
  -H "Authorization: Bearer $TOKEN"

Append blocks

curl -X POST "https://okoro.ai/p/notion/v1/blocks/{id}/children" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Read user

curl -X GET "https://okoro.ai/p/notion/v1/users/{id}" \
  -H "Authorization: Bearer $TOKEN"

List users

curl -X GET "https://okoro.ai/p/notion/v1/users" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "https://okoro.ai/p/notion/v1/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Create comment

curl -X POST "https://okoro.ai/p/notion/v1/comments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Read comments

curl -X GET "https://okoro.ai/p/notion/v1/comments" \
  -H "Authorization: Bearer $TOKEN"

Scopes

Your service token must be configured with at least the required scope level.

read

GET POST

/v1/pages/* /v1/databases/* /v1/databases/*/query /v1/blocks/* /v1/users /v1/users/* /v1/search /v1/comments

write

GET POST

/v1/pages /v1/databases /v1/blocks /v1/comments

update

GET POST PATCH

/v1/pages/* /v1/databases/* /v1/blocks/*

delete

GET POST PATCH DELETE

/v1/blocks/* /v1/pages/*

all

GET POST PATCH DELETE

/v1/**