Skip to main content
POST
/
sandbox
/
notion
/
{sandbox_id}
/
initialize
Initialize notion sandbox with data
curl --request POST \
  --url https://api.klavis.ai/sandbox/notion/{sandbox_id}/initialize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "databases": [
    {
      "name": "Product Roadmap",
      "summary": "Track product features and releases",
      "display_icon": "🚀",
      "sources": [
        {
          "label": "Features",
          "summary": "Feature tracking table",
          "fields": {
            "Name": {
              "type": "title"
            },
            "Status": {
              "type": "select",
              "options": [
                "Planning",
                "In Progress",
                "Done"
              ]
            },
            "Priority": {
              "type": "select",
              "options": [
                "High",
                "Medium",
                "Low"
              ]
            },
            "Assignee": {
              "type": "people"
            }
          },
          "pages": [
            {
              "name": "User Authentication",
              "attributes": {
                "Status": "Done",
                "Priority": "High"
              },
              "content_blocks": [
                {
                  "block_type": "paragraph",
                  "content": "Implement secure user authentication with OAuth2 support"
                },
                {
                  "block_type": "heading_2",
                  "content": "Requirements"
                },
                {
                  "block_type": "bulleted_list_item",
                  "content": "Support email/password login"
                },
                {
                  "block_type": "bulleted_list_item",
                  "content": "Implement JWT tokens"
                },
                {
                  "block_type": "bulleted_list_item",
                  "content": "Add OAuth2 providers (Google, GitHub)"
                }
              ],
              "comments": [
                {
                  "content": "Should we support social login from day one?"
                },
                {
                  "content": "Yes, let's add Google and GitHub OAuth"
                }
              ]
            },
            {
              "name": "Real-time Notifications",
              "attributes": {
                "Status": "In Progress",
                "Priority": "High"
              },
              "content_blocks": [
                {
                  "block_type": "paragraph",
                  "content": "Build real-time notification system using WebSockets"
                },
                {
                  "block_type": "to_do",
                  "content": "Set up WebSocket server"
                },
                {
                  "block_type": "to_do",
                  "content": "Create notification service"
                },
                {
                  "block_type": "to_do",
                  "content": "Design notification UI components"
                }
              ],
              "comments": []
            },
            {
              "name": "Dark Mode Support",
              "attributes": {
                "Status": "Planning",
                "Priority": "Medium"
              },
              "content_blocks": [
                {
                  "block_type": "paragraph",
                  "content": "Add dark mode theme toggle"
                },
                {
                  "block_type": "callout",
                  "content": "💡 Consider using CSS variables for easy theme switching"
                }
              ],
              "comments": [
                {
                  "content": "Users have been requesting this feature frequently"
                }
              ]
            }
          ]
        },
        {
          "label": "Releases",
          "summary": "Release planning and tracking",
          "fields": {
            "Name": {
              "type": "title"
            },
            "Release Date": {
              "type": "date"
            },
            "Status": {
              "type": "select",
              "options": [
                "Planned",
                "In Development",
                "Released"
              ]
            }
          },
          "pages": [
            {
              "name": "v1.0 - MVP Release",
              "attributes": {
                "Release Date": "2024-03-15",
                "Status": "In Development"
              },
              "content_blocks": [
                {
                  "block_type": "heading_2",
                  "content": "Release Goals"
                },
                {
                  "block_type": "paragraph",
                  "content": "First production-ready version with core functionality"
                },
                {
                  "block_type": "numbered_list_item",
                  "content": "User authentication and authorization"
                },
                {
                  "block_type": "numbered_list_item",
                  "content": "Real-time notifications"
                },
                {
                  "block_type": "numbered_list_item",
                  "content": "Core API endpoints"
                }
              ],
              "comments": []
            },
            {
              "name": "v1.1 - Enhanced UX",
              "attributes": {
                "Release Date": "2024-04-30",
                "Status": "Planned"
              },
              "content_blocks": [
                {
                  "block_type": "paragraph",
                  "content": "Focus on user experience improvements"
                }
              ],
              "comments": []
            }
          ]
        }
      ]
    },
    {
      "name": "Team Tasks",
      "summary": "Daily task management for the team",
      "display_icon": "✅",
      "sources": [
        {
          "label": "Tasks",
          "summary": "Task tracking",
          "fields": {
            "Task": {
              "type": "title"
            },
            "Status": {
              "type": "status"
            },
            "Assignee": {
              "type": "people"
            },
            "Due Date": {
              "type": "date"
            },
            "Priority": {
              "type": "select",
              "options": [
                "High",
                "Medium",
                "Low"
              ]
            }
          },
          "pages": [
            {
              "name": "Review pull request #123",
              "attributes": {
                "Status": "In Progress",
                "Priority": "High",
                "Due Date": "2024-02-10"
              },
              "content_blocks": [
                {
                  "block_type": "paragraph",
                  "content": "Review authentication implementation PR"
                },
                {
                  "block_type": "code",
                  "content": "// Check for proper error handling and security best practices"
                }
              ],
              "comments": [
                {
                  "content": "Found a potential security issue in token validation"
                },
                {
                  "content": "Fixed in latest commit"
                }
              ]
            },
            {
              "name": "Update deployment documentation",
              "attributes": {
                "Status": "Todo",
                "Priority": "Medium",
                "Due Date": "2024-02-15"
              },
              "content_blocks": [
                {
                  "block_type": "paragraph",
                  "content": "Add new deployment steps for Docker setup"
                }
              ],
              "comments": []
            },
            {
              "name": "Fix responsive layout on mobile",
              "attributes": {
                "Status": "Done",
                "Priority": "High",
                "Due Date": "2024-02-08"
              },
              "content_blocks": [
                {
                  "block_type": "paragraph",
                  "content": "Navigation menu was broken on screens < 768px"
                },
                {
                  "block_type": "heading_3",
                  "content": "Solution"
                },
                {
                  "block_type": "paragraph",
                  "content": "Implemented hamburger menu for mobile devices"
                }
              ],
              "comments": [
                {
                  "content": "Tested on iPhone and Android devices, looks good!"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "pages": [
    {
      "name": "Team Meeting Notes - Feb 2024",
      "content_blocks": [
        {
          "block_type": "heading_1",
          "content": "Weekly Sync - February 5, 2024"
        },
        {
          "block_type": "paragraph",
          "content": "Attendees: Alice, Bob, Charlie, Diana"
        },
        {
          "block_type": "heading_2",
          "content": "Discussion Points"
        },
        {
          "block_type": "bulleted_list_item",
          "content": "Sprint retrospective review"
        },
        {
          "block_type": "bulleted_list_item",
          "content": "Q1 roadmap planning"
        },
        {
          "block_type": "bulleted_list_item",
          "content": "New hire onboarding process"
        },
        {
          "block_type": "heading_2",
          "content": "Action Items"
        },
        {
          "block_type": "to_do",
          "content": "Alice: Schedule 1-on-1s with new team members"
        },
        {
          "block_type": "to_do",
          "content": "Bob: Update API documentation"
        },
        {
          "block_type": "to_do",
          "content": "Charlie: Review security audit findings"
        }
      ],
      "comments": [
        {
          "content": "Great meeting! Let's make sure we follow up on action items by Friday"
        },
        {
          "content": "Added calendar invites for the 1-on-1s"
        }
      ]
    },
    {
      "name": "Engineering Wiki Home",
      "content_blocks": [
        {
          "block_type": "heading_1",
          "content": "Welcome to Engineering Wiki"
        },
        {
          "block_type": "paragraph",
          "content": "This wiki contains all technical documentation, guides, and best practices for our engineering team."
        },
        {
          "block_type": "heading_2",
          "content": "Quick Links"
        },
        {
          "block_type": "bulleted_list_item",
          "content": "Getting Started Guide"
        },
        {
          "block_type": "bulleted_list_item",
          "content": "API Documentation"
        },
        {
          "block_type": "bulleted_list_item",
          "content": "Architecture Overview"
        },
        {
          "block_type": "bulleted_list_item",
          "content": "Deployment Procedures"
        },
        {
          "block_type": "heading_2",
          "content": "Code of Conduct"
        },
        {
          "block_type": "quote",
          "content": "Write code that is clear, maintainable, and well-tested. When in doubt, prioritize readability over cleverness."
        }
      ],
      "comments": []
    },
    {
      "name": "API Design Guidelines",
      "content_blocks": [
        {
          "block_type": "heading_1",
          "content": "REST API Design Guidelines"
        },
        {
          "block_type": "paragraph",
          "content": "Follow these guidelines when designing new API endpoints"
        },
        {
          "block_type": "heading_2",
          "content": "General Principles"
        },
        {
          "block_type": "numbered_list_item",
          "content": "Use RESTful conventions (GET, POST, PUT, DELETE)"
        },
        {
          "block_type": "numbered_list_item",
          "content": "Use plural nouns for resource names"
        },
        {
          "block_type": "numbered_list_item",
          "content": "Version your APIs (e.g., /v1/users)"
        },
        {
          "block_type": "numbered_list_item",
          "content": "Use HTTP status codes correctly"
        },
        {
          "block_type": "heading_2",
          "content": "Example"
        },
        {
          "block_type": "code",
          "content": "GET /v1/users - List all users\nGET /v1/users/:id - Get specific user\nPOST /v1/users - Create new user\nPUT /v1/users/:id - Update user\nDELETE /v1/users/:id - Delete user"
        },
        {
          "block_type": "callout",
          "content": "⚠️ Always validate input data and sanitize user-provided content"
        }
      ],
      "comments": [
        {
          "content": "Should we use GraphQL for more complex queries?"
        },
        {
          "content": "Let's discuss in next architecture meeting"
        }
      ]
    }
  ]
}
EOF
{
  "sandbox_id": "<string>",
  "status": "idle",
  "message": "<string>",
  "records_created": {}
}

Authorizations

Authorization
string
header
required

Your Klavis AI API key.

Path Parameters

sandbox_id
string
required

The unique sandbox identifier

Query Parameters

init_default_data
boolean
default:false

If true, use default test data for initialization

Body

application/json

Complete Notion sandbox data structure.

Hierarchical structure for initialization:

  • Databases contain Data Sources
  • Data Sources contain Pages (with properties matching the schema)
  • Standalone Pages exist at top level (not in databases)
  • Pages contain Blocks (content) and Comments

Relational structure:

  • Pages refer to Data Sources (via parent_source)
  • Data Sources are nested in Databases
databases
NotionDatabase · object[] | null

List of databases with their data sources and pages

pages
NotionPage · object[] | null

List of standalone pages (not in databases)

Response

Successful Response

Response model for sandbox initialization

sandbox_id
string
required

Sandbox identifier

status
enum<string>
required

Current status

Available options:
idle,
occupied
message
string
required

Initialization result message

records_created
Records Created · object

Count of records created per object type