API Reference
API Reference
A technical guide to querying, retrieving, and updating pages, databases, blocks, users and more.
Endpoints
All API requests should be made to https://api.plumoai.com
GET
/v1/pages/{page_id}Retrieve a page
curl https://api.plumoai.com/v1/pages/PAGE_ID \
-H "Authorization: Bearer YOUR_API_KEY"POST
/v1/pagesCreate a page
curl -X POST https://api.plumoai.com/v1/pages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"parent": { "database_id": "DATABASE_ID" },
"properties": {
"Title": {
"title": [{ "text": { "content": "New Page" } }]
}
}
}'PATCH
/v1/pages/{page_id}Update a page
curl -X PATCH https://api.plumoai.com/v1/pages/PAGE_ID \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"properties": {
"Title": {
"title": [{ "text": { "content": "Updated Title" } }]
}
}
}'Authentication
All API requests require authentication using an API key.
Include your API key in the Authorization header of every request:
Authorization: Bearer YOUR_API_KEYGet your API key from app.plumoai.com/settings/api
Response Format
Success Response
{
"object": "page",
"id": "abc-123",
"created_time": "2025-01-01T00:00:00.000Z",
"last_edited_time": "2025-01-01T00:00:00.000Z",
"properties": {
"Title": {
"title": [
{
"text": {
"content": "Example Page"
}
}
]
}
}
}Error Response
{
"object": "error",
"status": 401,
"code": "unauthorized",
"message": "API token is invalid."
}Rate Limits
API rate limits help ensure fair usage and system stability.
Free tier: 100 requests per minute
Pro tier: 1,000 requests per minute
Enterprise: Custom limits
Rate limit information is included in response headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200