wakato-io Pages API

openapi: 3.2.0
info:
  title: Wakato Space Pages API
  version: 1.0.0
  description: 'The **Wakato Space API** lets an external agent or tool (Claude Code, Cursor,

    Zapier, a partner integration, your own scripts) operate a single Wakato

    **Space** using a scoped Bearer token (a *Space API key*, `wks_live_…`).


    The **same token** works two ways:

    - **REST** — the endpoints documented here (`/functions/v1/space-api/…`).

    - **MCP** — a Model Context Protocol server at `/functions/v1/space-mcp`

    that exposes the same operations as tools to MCP clients. MCP clients

    self-discover the tools via `tools/list`; see the Quickstart to connect.


    ### Authentication

    Send the key as a Bearer token: `Authorization: Bearer wks_live_…`.

    A key is locked to exactly one Space and cannot read or write any other

    Space, the wallet (beyond read), member permissions, or other users.


    ### Scopes

    Every key grants per-domain scopes with up to three actions:

    - `read` — list / inspect

    - `write` — create / edit

    - `run` — the *consequential* action (publish a page, send an SMS, post

    socially, run an automation). Public/billable actions are deliberately

    split into `run` so you grant them explicitly.


    Each operation below notes its required scope via `x-required-scope`.

    A call without the scope returns `403`.


    ### Safety model

    - Wallet, Finance, Integrations are **read-only**. Money is never moved.

    - Secrets returns **names only** — values are never exposed.

    - Social posts and ad campaigns default to **drafts**; going live requires

    the `run` scope. Connecting new OAuth accounts is never done by a key.'
servers:
- url: https://api.wakato.io/functions/v1/space-api
  description: Production
- url: https://pnwxrleocjbcvrrwrycq.supabase.co/functions/v1/space-api
  description: Development
security:
- bearerAuth: []
tags:
- name: Pages
paths:
  /sites:
    get:
      tags:
      - Pages
      summary: List sites
      description: '**Required scope:** `pages:read`


        A site groups pages into ONE website with shared, platform-injected

        navigation. List existing sites before creating one to avoid

        duplicates.'
      x-required-scope: pages:read
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.wakato.io/functions/v1/space-api/sites\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: getSites
      x-operation-id-source: derived
    post:
      tags:
      - Pages
      summary: Create a site
      description: '**Required scope:** `pages:write`


        Create a site, then pass its `id` as `site_id` on every

        `POST /pages` call that belongs to the same website. Required when

        building a multi-page website/funnel — pages created without

        `site_id` are standalone and not linked together. Idempotent by

        title: an existing same-title site is returned instead of

        duplicated. The first page attached becomes the site''s home page.'
      x-required-scope: pages:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                title:
                  type: string
                  description: Site/brand name
                description:
                  type: string
                nav_layout:
                  type: string
                  enum:
                  - top
                  - sidebar
                  - none
                logo_url:
                  type: string
      responses:
        '201':
          $ref: '#/components/responses/Created'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.wakato.io/functions/v1/space-api/sites\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"title\": \"Launch plan\"\n}'"
      operationId: postSites
      x-operation-id-source: derived
  /pages:
    get:
      tags:
      - Pages
      summary: List pages
      x-required-scope: pages:read
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `pages:read`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.wakato.io/functions/v1/space-api/pages\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: getPages
      x-operation-id-source: derived
    post:
      tags:
      - Pages
      summary: Create a page
      description: '**Required scope:** `pages:write`


        Pass `layout_html` (a complete HTML document) to build an AI-designed

        page in one call. Any embedded form/booking page must be a real Space

        resource — references that don''t resolve in this space are rejected.


        Building a multi-page website? Create a site first (`POST /sites`)

        and pass `site_id` on every page so they form one linked website —

        omit `site_id` only for an intentionally standalone page.


        **Enforced:** creating a 2nd+ standalone page within a short window

        is rejected with an error — multiple related pages must share a

        site. Pass `standalone: true` to confirm a page is an intentional

        one-off.'
      x-required-scope: pages:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                title:
                  type: string
                description:
                  type: string
                layout_html:
                  type: string
                site_id:
                  type: string
                  description: Site to attach to (from POST /sites) — required for multi-page websites
                standalone:
                  type: boolean
                  description: Confirm this page is an intentional one-off — required for a 2nd+ standalone page in a short window
      responses:
        '201':
          $ref: '#/components/responses/Created'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.wakato.io/functions/v1/space-api/pages\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"title\": \"Launch plan\"\n}'"
      operationId: postPages
      x-operation-id-source: derived
  /pages/{id}:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
    get:
      tags:
      - Pages
      summary: Get a page (incl. layout_html)
      x-required-scope: pages:read
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `pages:read`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.wakato.io/functions/v1/space-api/pages/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: getPagesById
      x-operation-id-source: derived
    patch:
      tags:
      - Pages
      summary: Update a page
      x-required-scope: pages:write
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                layout_html:
                  type: string
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `pages:write`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X PATCH \"https://api.wakato.io/functions/v1/space-api/pages/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"
      operationId: patchPagesById
      x-operation-id-source: derived
  /pages/{id}/publish:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
    post:
      tags:
      - Pages
      summary: Publish (or unpublish) a page
      x-required-scope: pages:run
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                published_slug:
                  type: string
                publish:
                  type: boolean
                  description: false to unpublish
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `pages:run`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.wakato.io/functions/v1/space-api/pages/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c/publish\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'"
      operationId: postPagesByIdPublish
      x-operation-id-source: derived
components:
  responses:
    Ok:
      description: Success
      content:
        application/json:
          schema:
            type: object
    Created:
      description: Created
      content:
        application/json:
          schema:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Space API key, e.g. `wks_live_…`.