Notion AI Summary API¶

The Notion AI Summary API triggers Notion's built-in AI to generate summaries for database properties that have AI autofill configured. It uses Notion's internal (unofficial) API to discover AI properties, run inference, and save results back to the page.

Authentication¶

Only the API key is required. All Notion credentials are resolved server-side from Secret Manager.

curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v2/notion/database/<database_id>/ai-summary-auto" \
  -H "X-API-Key: your-mmk-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "page_ids": ["page-uuid-1"] }'

Headers¶

Header	Required	Description
`X-API-Key` or `Authorization: Bearer`	Yes	Magic Meal Kits API key
`X-Notion-Token`	No	Notion session token (`token_v2`). Auto-resolved from Secret Manager if missing
`X-Notion-User-ID`	No	Notion user ID. Auto-resolved from Secret Manager if missing
`X-Notion-Space-ID`	No	Notion workspace (space) ID. Auto-resolved from Secret Manager if missing
`X-Notion-Official-Token`	No	Official Notion API token. Auto-resolved from Secret Manager if missing. When available, Step 3 (save summary) uses the official API (`PATCH /v1/pages`) instead of the unofficial `saveTransactionsFanout` API

Note: If you provide any X-Notion-* headers explicitly, they take priority over Secret Manager values. This allows MCP/browser clients to pass credentials directly while API clients can omit them entirely.

License Requirement¶

All AI Summary endpoints require a Pro license (license.RequirePro()).

Array Input Formats¶

All array fields (page_ids, property_ids) accept two formats:

Format 1: Simple string array (standard)

{ "page_ids": ["uuid-1", "uuid-2"] }

Format 2: Object array (Make.com friendly)

{ "page_ids": [{"page_id": "uuid-1"}, {"page_id": "uuid-2"}] }

Both formats are fully supported and can be used interchangeably. The object array format is particularly useful for Make.com scenarios where arrays are naturally represented as collections.

Endpoints¶

Auto AI Summary (Recommended)¶

Auto-discovers all AI-configured properties in the database, then triggers AI summary for each discovered property across all provided pages.

POST `/api/v2/notion/database/:database_id/ai-summary-auto`¶

URL Parameters:

Parameter	Type	Required	Description
database_id	String	Yes	Notion database ID or URL

Request Body:

{
  "page_ids": ["page-uuid-1", "page-uuid-2"],
  "page_id": "database-page-uuid",
  "property_ids": ["property-id-1"]
}

Field	Type	Required	Description
page_ids	String[] or Object[]	Yes	Array of page IDs to process (max 10 per call)
page_id	String	No	Page ID for `loadPageChunk`. Use when the database is inline — provide the parent page ID
property_ids	String[] or Object[]	No	Filter to specific AI property IDs. If omitted, all discovered AI properties are processed

Example Request:

curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v2/notion/database/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ai-summary-auto" \
  -H "X-API-Key: your-mmk-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "page_ids": [
      "11111111-2222-3333-4444-555555555555",
      "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    ]
  }'

Example Response (200 OK — all succeeded):

{
  "success": true,
  "total": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "page_id": "11111111-2222-3333-4444-555555555555",
      "success": true,
      "summary": "This page discusses project milestones and quarterly goals...",
      "property_id": "B\\i_"
    },
    {
      "page_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "success": true,
      "summary": "A comprehensive analysis of customer feedback from Q4...",
      "property_id": "B\\i_"
    }
  ]
}

Example Response (207 Multi-Status — partial success):

{
  "success": false,
  "total": 4,
  "successful": 2,
  "failed": 2,
  "results": [
    {
      "page_id": "11111111-2222-3333-4444-555555555555",
      "success": true,
      "summary": "Generated summary text...",
      "property_id": "B\\i_"
    },
    {
      "page_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "success": false,
      "error": "step 2 (getCompletionForProperty) failed: timeout",
      "property_id": "B\\i_"
    }
  ]
}

Note: When a database has multiple AI properties, results are flattened — each page+property combination is a separate result entry.

Manual AI Summary¶

Triggers AI summary for a specific property and workflow. Use this when you already know the property_id and workflow_id.

POST `/api/v2/notion/database/:database_id/ai-summary`¶

URL Parameters:

Parameter	Type	Required	Description
database_id	String	Yes	Notion database ID or URL

Request Body:

{
  "page_ids": ["page-uuid-1", "page-uuid-2"],
  "property_id": "B\\i_",
  "workflow_id": "optional-workflow-id"
}

Field	Type	Required	Description
page_ids	String[] or Object[]	Yes	Array of page IDs to process
property_id	String	Yes	The AI property ID (URL-encoded values like `B%5Ci_` are auto-decoded)
workflow_id	String	No	Notion AI workflow ID. If omitted, the default is used

Example Request:

curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v2/notion/database/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ai-summary" \
  -H "X-API-Key: your-mmk-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "page_ids": ["11111111-2222-3333-4444-555555555555"],
    "property_id": "B%5Ci_",
    "workflow_id": "wf-abc123"
  }'

Example Response:

{
  "success": true,
  "total": 1,
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "page_id": "11111111-2222-3333-4444-555555555555",
      "success": true,
      "summary": "Generated summary text..."
    }
  ]
}

How It Works¶

The AI summary flow has 3 steps, executed sequentially for each page:

┌──────────────────────────────────────────────────────────────────┐
│  Auto endpoint only: loadPageChunk → discover AI properties      │
│  (properties with ai_inference config + migrated_workflow_id)    │
└──────────────────────────┬───────────────────────────────────────┘
                           │
              For each page × property:
                           │
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│  Step 1: publishAiSession                                        │
│  POST /api/v3/publishAiSession (Notion internal API)             │
│  Creates an AI session with block pointer + inference config     │
│  Typically completes in < 1 second                               │
└──────────────────────────┬───────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│  Step 2: getCompletionForProperty                                │
│  POST /api/v3/getCompletionForProperty (Notion internal API)     │
│  Returns NDJSON stream of tokens                                 │
│  Parses lines with type="success" and concatenates completion    │
│  ⚠️  This step can take 30–120 seconds                           │
└──────────────────────────┬───────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│  Step 3: saveSummary                                             │
│  If official token available (header or Secret Manager):         │
│    → PATCH /v1/pages/{page_id} (official Notion API)             │
│  Else:                                                           │
│    → POST /api/v3/saveTransactionsFanout (unofficial API)        │
│  Writes generated summary back to the page property              │
└──────────────────────────────────────────────────────────────────┘

AI Property Discovery (Auto endpoint only)¶

The auto endpoint calls Notion's loadPageChunk API on the database to inspect the collection schema. It looks for properties that have ai_inference configuration:

{
  "schema": {
    "B\\i_": {
      "name": "AI Summary",
      "type": "text",
      "ai_inference": {
        "type": "summarize",
        "is_migrated": true,
        "migrated_workflow_id": "wf-abc123"
      }
    }
  }
}

Only properties with ai_inference present are discovered and processed.

Response Structure¶

Both endpoints share the same response format:

{
  "success": true,
  "total": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "page_id": "uuid",
      "success": true,
      "summary": "Generated text...",
      "property_id": "prop_id"
    }
  ]
}

Field	Type	Description
success	Boolean	`true` if all operations succeeded
total	Integer	Total number of page×property operations
successful	Integer	Number of successful operations
failed	Integer	Number of failed operations
results	AISummaryResult[]	Per-page-property results

AISummaryResult¶

Field	Type	Description
page_id	String	The page that was processed
success	Boolean	Whether this specific operation succeeded
summary	String	The generated AI summary text (on success)
error	String	Error description (on failure)
property_id	String	The AI property ID (present in auto endpoint results)

HTTP Status Codes¶

Status	Meaning
200	All operations succeeded
207	Partial success — some operations failed, some succeeded
400	All operations failed, or invalid request

Limits and Considerations¶

Max 10 pages per call (auto endpoint)
Step 2 can take 30–120 seconds per page — plan for long timeouts
Sequential processing — pages are processed one at a time, not in parallel
Notion AI must be enabled — the database must have AI properties configured in Notion
Inline databases — if the database is inline (embedded in a page), provide the page_id of the parent page so loadPageChunk can find the collection schema

Error Handling¶

Errors follow the standard format:

{
  "error": "Missing required Notion credentials (not found in headers or Secret Manager)",
  "required": ["X-Notion-Token", "X-Notion-User-ID"]
}

Common errors:

Error	Cause
`Missing required Notion credentials`	Token/UserID not in headers and not in Secret Manager
`X-Notion-Space-ID is required`	Space ID not found in headers or Secret Manager
`Maximum 10 pages per call`	Too many page_ids in request
`Failed to detect AI properties`	loadPageChunk failed — check page_id or credentials
`step 1 (publishAiSession) failed`	Notion session creation failed
`step 2 (getCompletionForProperty) failed`	AI inference timed out or returned error
`step 2 returned empty summary`	Notion AI returned no content
`step 3 (saveSummary) failed`	Failed to write summary back to the page

Use Cases¶

Trigger AI Summary After Bulk Insert¶

After inserting records via the Bulk Operations API, trigger AI summaries for the newly created pages:

# 1. Bulk insert records
curl -X POST ".../api/v1/notion/bulk-insert" \
  -H "X-API-Key: key" \
  -d '{"database_id": "db-id", "records": [...]}'

# 2. Get page_ids from the bulk insert response, then trigger AI summary
curl -X POST ".../api/v2/notion/database/db-id/ai-summary-auto" \
  -H "X-API-Key: key" \
  -d '{"page_ids": ["page-id-1", "page-id-2"]}'

Make.com Integration¶

Use the AI Summary Auto endpoint as an action step in a Make.com scenario:

A trigger module detects new database items
Collect the page IDs
Call the AI Summary Auto endpoint via HTTP module
All AI properties are automatically populated