API Routes

JSON API endpoints for frontend/backend communication.

API routes handle:

• JSON request/response formatting
• HTTP status code management
• Parameter extraction from URLs
• Error response standardization

API routes delegate business logic to controllers and return clean JSON responses.

Purpose: System health check endpoint

Input Data: None

Output Data:

{
  status: "healthy" | "unhealthy",
  timestamp: string,
  // Additional health metrics from controller
}

HTTP Status: Always 200

Purpose: Get Notion page properties (filtered for UI consumption)

Input Data:

// URL Parameters
{
  id: string  // Notion page UUID
}

Processing Flow:

1. Extract page ID from URL parameter
2. Call getDemoProperties(id) controller
3. Return filtered page properties or error

Success Response (200):

{
  id: string,
  properties: {
    // All properties except type: "button"
    [propertyName: string]: {
      type: "title" | "rich_text" | "number" | "select" | "multi_select" | "date" | "checkbox" | "url" | "email" | "phone_number" | "formula" | "relation" | "rollup" | "created_time" | "created_by" | "last_edited_time" | "last_edited_by",
      // Property-specific value structure
    }
  },
  parent: {
    type: "database_id" | "page_id",
    database_id?: string,
    page_id?: string
  },
  created_time: string,
  last_edited_time: string,
  // ... other Notion page fields
}

Error Responses:

// 400 - Invalid Request
{
  error: "Page ID is required",
  details?: string
}

// 500 - Server Error
{
  error: "Failed to fetch page data",
  details: "Notion API error message"
}

Purpose: Get complete Notion page with content blocks

Input Data:

// URL Parameters
{
  id: string  // Notion page UUID
}

Processing Flow:

1. Extract page ID from URL parameter
2. Call getDemoFull(id) controller
3. Return complete page with blocks or error

Success Response (200):

{
  // Page properties (same as /properties endpoint)
  id: string,
  properties: { [key: string]: NotionPropertyValue },
  parent: NotionParent,
  created_time: string,
  last_edited_time: string,
  
  // Block content (hierarchical structure)
  blocks: [
    {
      id: string,
      type: "paragraph" | "heading_1" | "heading_2" | "heading_3" | "bulleted_list_item" | "numbered_list_item" | "to_do" | "toggle" | "child_page" | "child_database" | "embed" | "image" | "video" | "file" | "pdf" | "bookmark" | "callout" | "quote" | "equation" | "divider" | "table_of_contents" | "column" | "column_list" | "link_preview" | "synced_block" | "template" | "link_to_page" | "table" | "table_row" | "unsupported",
      created_time: string,
      last_edited_time: string,
      has_children: boolean,
      children?: NotionBlock[], // Recursive structure for nested blocks
      // Type-specific content
      [blockType]: {
        // Block-specific properties
      }
    }
  ]
}

Error Responses: Same as /properties endpoint

All API routes follow consistent error handling:

// In route handler
const result = await controllerFunction(params);

if (!result.success) {
  return c.json({ 
    error: result.error, 
    details: result.details 
  }, result.error === "Page ID is required" ? 400 : 500);
}

return c.json(result.data);

API routes return filtered data for UI consumption:

• Button properties removed: Notion button properties are filtered out to prevent UI confusion
• Raw Notion format: Other properties maintain their original Notion API structure
• Complete hierarchy: Block content includes full nested structure with children

# Get page properties only
curl https://your-val.web.val.run/api/demo/abc123/properties

# Get complete page with content
curl https://your-val.web.val.run/api/demo/abc123

# Health check
curl https://your-val.web.val.run/api/health