wakato-io Events API

openapi: 3.2.0
info:
  title: Wakato Space Events 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: Events
  description: What happens in your space (a new order, a booking, a form reply…) sent to your system as signed webhooks, or kept as a feed you pull. Uses the automations scope.
paths:
  /event-types:
    get:
      tags:
      - Events
      summary: Every event you can listen to, with its data fields
      description: '**Required scope:** `automations:read`


        Self-describing: each type carries `label`, `group` and `fields`

        (the keys its `data` holds). `?type=` returns one type; `?group=` narrows.'
      x-required-scope: automations:read
      parameters:
      - in: query
        name: type
        schema:
          type: string
      - in: query
        name: group
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.wakato.io/functions/v1/space-api/event-types\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: getEventTypes
      x-operation-id-source: derived
  /events:
    get:
      tags:
      - Events
      summary: Pull events (the feed), oldest first, after a cursor
      description: '**Required scope:** `automations:read`


        The space keeps an event while some listener wants its type, for 14

        days. Pass the answer''s `next_cursor` as `after` on the next call;

        `has_more` says whether to call again at once. `subscription_id`

        narrows to one feed''s types and filters.'
      x-required-scope: automations:read
      parameters:
      - in: query
        name: after
        schema:
          type: string
        description: A cursor (evt_…)
      - in: query
        name: types
        schema:
          type: string
        description: Comma-separated event types
      - in: query
        name: subscription_id
        schema:
          type: string
      - in: query
        name: limit
        schema:
          type: integer
          maximum: 200
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.wakato.io/functions/v1/space-api/events\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: getEvents
      x-operation-id-source: derived
  /event-subscriptions:
    get:
      tags:
      - Events
      summary: List listeners (webhooks, feeds, agents) with 24-hour delivery counts
      x-required-scope: automations:read
      parameters:
      - in: query
        name: kind
        schema:
          type: string
          enum:
          - webhook
          - feed
          - agent
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `automations:read`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.wakato.io/functions/v1/space-api/event-subscriptions\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: getEventSubscriptions
      x-operation-id-source: derived
    post:
      tags:
      - Events
      summary: Create a webhook or a feed
      description: '**Required scope:** `automations:write`


        `kind: "webhook"` — we POST each event to your https `url`, signed:

        `Wakato-Signature: t=,v1=`, v1 = HMAC-SHA256(secret,

        "."). The `secret` is in this response ONCE (rotate it with

        `/rotate-secret`). Failed deliveries are retried with backoff; a URL

        that keeps failing is switched off, saying why.

        `kind: "feed"` — the events are kept for you to pull with `GET /events`.

        `kind: "agent"` is only for an agent''s own key (its events arrive in its chat).

        `filters` take the automation trigger''s own config per event type.'
      x-required-scope: automations:write
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - kind
              - event_types
              properties:
                kind:
                  type: string
                  enum:
                  - webhook
                  - feed
                  - agent
                event_types:
                  type: array
                  items:
                    type: string
                  description: Types from /event-types, or ["*"]
                url:
                  type: string
                  description: https URL (webhook)
                name:
                  type: string
                filters:
                  type: object
      responses:
        '201':
          $ref: '#/components/responses/Ok'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.wakato.io/functions/v1/space-api/event-subscriptions\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"kind\": \"webhook\",\n  \"event_types\": []\n}'"
      operationId: postEventSubscriptions
      x-operation-id-source: derived
  /event-subscriptions/{id}:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
    patch:
      tags:
      - Events
      summary: Change a listener (event_types, filters, name, url, enabled)
      x-required-scope: automations:write
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `automations:write`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X PATCH \"https://api.wakato.io/functions/v1/space-api/event-subscriptions/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: patchEventSubscriptionsById
      x-operation-id-source: derived
    delete:
      tags:
      - Events
      summary: Delete a listener
      x-required-scope: automations:write
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `automations:write`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X DELETE \"https://api.wakato.io/functions/v1/space-api/event-subscriptions/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: deleteEventSubscriptionsById
      x-operation-id-source: derived
  /event-subscriptions/{id}/deliveries:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
    get:
      tags:
      - Events
      summary: The delivery log, newest first
      x-required-scope: automations:read
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `automations:read`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X GET \"https://api.wakato.io/functions/v1/space-api/event-subscriptions/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c/deliveries\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: getEventSubscriptionsByIdDeliveries
      x-operation-id-source: derived
  /event-subscriptions/{id}/deliveries/{deliveryId}/resend:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
    - in: path
      name: deliveryId
      required: true
      schema:
        type: integer
    post:
      tags:
      - Events
      summary: Put a delivery back in the queue (a failed one included)
      x-required-scope: automations:write
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `automations:write`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.wakato.io/functions/v1/space-api/event-subscriptions/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c/deliveries/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c/resend\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: postEventSubscriptionsByIdDeliveriesByDeliveryIdResend
      x-operation-id-source: derived
  /event-subscriptions/{id}/test:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
    post:
      tags:
      - Events
      summary: Send a webhook a signed test event now
      x-required-scope: automations:write
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `automations:write`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.wakato.io/functions/v1/space-api/event-subscriptions/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c/test\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: postEventSubscriptionsByIdTest
      x-operation-id-source: derived
  /event-subscriptions/{id}/rotate-secret:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
    post:
      tags:
      - Events
      summary: Make a new signing secret (returned once; the old one stops at once)
      x-required-scope: automations:write
      responses:
        '200':
          $ref: '#/components/responses/Ok'
      description: '**Required scope:** `automations:write`'
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST \"https://api.wakato.io/functions/v1/space-api/event-subscriptions/b7e4a1c2-9d3f-4e8a-b2c1-5f6d7e8a9b0c/rotate-secret\" \\\n  -H \"Authorization: Bearer wks_live_YOUR_TOKEN\""
      operationId: postEventSubscriptionsByIdRotateSecret
      x-operation-id-source: derived
components:
  responses:
    Ok:
      description: Success
      content:
        application/json:
          schema:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Space API key, e.g. `wks_live_…`.