Table of Contents

Overview

The Notion Ricette API serves as a bridge between GPT and the Notion API, providing RESTful endpoints for database operations. This API simplifies interaction with Notion databases and pages.

Base URL: http://localhost:5000/api

Authentication

This API uses the Notion Integration Token for authentication. The token is configured server-side via the NOTION_INTEGRATION_SECRET environment variable.

Required Environment Variables
  • NOTION_INTEGRATION_SECRET - Your Notion integration token
  • SESSION_SECRET - Flask session secret (optional)

Endpoints

Health Check

GET /api/health

Check the API health and configuration status.

Response:
{
  "status": "healthy",
  "service": "notion-ricette-api",
  "notion_configured": true
}

Database Operations

GET /api/databases/{database_id}

Retrieve database schema and metadata.

Parameters:
  • database_id (path) - Notion database ID
POST /api/databases/{database_id}/query

Query database with filters, sorting, and pagination.

Request Body:
{
  "filter": {
    "property": "Status",
    "select": {
      "equals": "Published"
    }
  },
  "sorts": [
    {
      "property": "Created",
      "direction": "descending"
    }
  ],
  "page_size": 50
}

Page Operations

POST /api/databases/{database_id}/pages

Create a new page in the database.

Request Body:
{
  "properties": {
    "Title": {
      "title": [
        {
          "text": {
            "content": "New Recipe"
          }
        }
      ]
    },
    "Status": {
      "select": {
        "name": "Draft"
      }
    }
  }
}
GET /api/pages/{page_id}

Retrieve page information and properties.

Parameters:
  • page_id (path) - Notion page ID
PATCH /api/pages/{page_id}

Update page properties.

Request Body:
{
  "properties": {
    "Status": {
      "select": {
        "name": "Published"
      }
    }
  }
}
DELETE /api/pages/{page_id}

Archive (delete) a page.

Examples

Creating a Recipe
curl -X POST http://localhost:5000/api/databases/YOUR_DATABASE_ID/pages \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "Name": {
        "title": [{"text": {"content": "Pasta Carbonara"}}]
      },
      "Difficulty": {
        "select": {"name": "Medium"}
      },
      "Prep Time": {
        "number": 30
      }
    }
  }'
Querying Recipes by Difficulty
curl -X POST http://localhost:5000/api/databases/YOUR_DATABASE_ID/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Difficulty",
      "select": {
        "equals": "Easy"
      }
    }
  }'

Error Handling

The API returns structured error responses with appropriate HTTP status codes.

Error Response Format
{
  "error": {
    "message": "Database not found",
    "code": "object_not_found",
    "details": {}
  }
}
Common HTTP Status Codes:
  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Internal Server Error