openapi: 3.1.0
info:
  title: Sanaa API
  version: '1'
  description: >
    Manage your booking connector, webhooks and read calls and usage for your
    organization. Authenticate with a bearer API key (`sk_test_...` or
    `sk_live_...`). A test key only sees test tenants; a live key only live ones.
    This describes only what exists. Tenant creation and provisioning exist on the platform deployment only.
servers:
  - url: https://REPLACE-WITH-API-HOST
security:
  - bearerAuth: []
paths:
  /api/v1/connector:
    get:
      summary: Get the connector settings (never the secret)
      description: 'Scope: `connector:write`'
      responses:
        '200': { description: Connector settings, content: { application/json: { schema: { $ref: '#/components/schemas/Connector' } } } }
        '404': { $ref: '#/components/responses/Error' }
    put:
      summary: Create or update the connector
      description: >
        Scope `connector:write`. The signing secret is returned once, when the
        connector is created or when `rotate_secret` is true. The URL must be
        https and resolve to public addresses.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [base_url]
              properties:
                base_url: { type: string, format: uri }
                timeout_ms: { type: integer, minimum: 1000, maximum: 4800 }
                rotate_secret: { type: boolean }
      responses:
        '200': { description: Updated, content: { application/json: { schema: { $ref: '#/components/schemas/Connector' } } } }
        '201': { description: Created or rotated; includes `secret`, content: { application/json: { schema: { $ref: '#/components/schemas/Connector' } } } }
        '400': { $ref: '#/components/responses/Error' }
  /api/v1/connector/test:
    post:
      summary: Run the conformance checks against your connector
      description: 'Scope: `connector:write`. Makes about twenty signed test-mode requests. See docs/connector-spec.md.'
      responses:
        '200': { description: Report, content: { application/json: { schema: { $ref: '#/components/schemas/ConformanceReport' } } } }
        '404': { $ref: '#/components/responses/Error' }
  /api/v1/webhook_endpoints:
    get:
      summary: List webhook endpoints
      description: 'Scope: `webhooks:write`'
      responses:
        '200': { description: Endpoints (secrets are never returned) }
    post:
      summary: Create a webhook endpoint
      description: 'Scope `webhooks:write`. The signing secret is returned once.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url: { type: string, format: uri }
                events:
                  type: array
                  items: { type: string, enum: [call.started, call.ended, booking.created, booking.rescheduled, booking.cancelled, transfer.requested, waitlist.added, tenant.provisioned, '*'] }
      responses:
        '201': { description: Created; includes `secret` }
        '400': { $ref: '#/components/responses/Error' }
  /api/v1/webhook_endpoints/{id}:
    delete:
      summary: Delete a webhook endpoint
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        '200': { description: Deleted }
        '404': { $ref: '#/components/responses/Error' }
  /api/v1/webhook_deliveries:
    get:
      summary: Delivery log
      description: 'Scope `webhooks:write`. Newest first.'
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [pending, sending, delivered, failed] } }
        - { name: endpoint_id, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 } }
      responses:
        '200': { description: Deliveries }
  /api/v1/webhook_deliveries/{id}/replay:
    post:
      summary: Send a delivered or failed event again
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        '200': { description: Queued }
        '404': { $ref: '#/components/responses/Error' }
  /api/v1/tenants:
    get:
      summary: List your tenants (your customers)
      description: 'Scope: `tenants:read`'
      responses:
        '200': { description: Tenants }
    post:
      summary: Create a tenant for one of your customers
      description: >
        Scope `tenants:write`. Platform deployment only. Sanaa reads the business profile from your
        connector (`business-profile`) and stores it. A test key creates a test tenant; a live key
        creates a live tenant and requires a connector that has passed the conformance check. Sending
        the same `external_id` again returns the existing tenant (200 instead of 201). Does not create
        the voice assistant: call provision next.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [external_id]
              properties:
                external_id: { type: string, maxLength: 200, description: Your own id for this business }
                booking_backend: { type: string, enum: [partner, native, sandbox], default: partner, description: 'partner: your own booking system through your connector. native: Sanaa keeps the schedule (send `business`). sandbox: test keys only.' }
                business:
                  type: object
                  description: 'Required for native, rejected otherwise. { business_name, timezone (IANA), hours, services: [{ name, duration_minutes, price? }], staff: [{ name, hours?, service_ids? }] }. A person may have their own hours (same weekday-name shape, inside the business hours; a weekday left out means not working; null or omitted means the business hours) and service_ids (the ids of the services they do; null or omitted means every service). hours uses lowercase weekday names: { monday: { open: "09:00", close: "17:00" }, sunday: { closed: true } }.'
                transfer_number: { type: string, example: '+15551234567' }
                tone: { type: string, enum: [warm_casual, professional_formal, upbeat_energetic] }
      responses:
        '200': { description: Already existed }
        '201': { description: Created }
        '400': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '502': { $ref: '#/components/responses/Error' }
  /api/v1/tenants/{id}/provision:
    post:
      summary: Set up or refresh the tenant's receptionist
      description: >
        Scope `tenants:write`. Platform deployment only. Refreshes the business profile from the booking
        backend, then creates or updates the voice assistant on the current engine release. Safe to call
        again after services, staff or hours change. Does not buy a phone number (see `/tenants/{id}/number`).
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        '200': { description: Provisioned }
        '404': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '502': { $ref: '#/components/responses/Error' }
  /api/v1/numbers/search:
    get:
      summary: Search available phone numbers
      description: 'Scope `tenants:read`. US and Canadian local numbers only. Free and read-only.'
      parameters:
        - { name: area_code, in: query, description: '3-digit area code', schema: { type: string } }
        - { name: state, in: query, description: '2-letter state or province', schema: { type: string } }
      responses:
        '200': { description: 'Up to 5 available numbers: { data: [{ phone_number }] }' }
        '400': { $ref: '#/components/responses/Error' }
  /api/v1/tenants/{id}/number:
    post:
      summary: Buy and attach a phone number to a tenant
      description: >
        Scope `tenants:write`. Platform deployment only. Costs real money, so it works only with a live key
        and a live tenant (test tenants use browser test calls), only for a provisioned tenant, and only up to
        the organization's limit (5 by default). US and Canadian local numbers only. Repeating the call never
        buys a second number. Body (all optional): `mode` "new" (publish this number) or "forward" (the
        business keeps its own number and forwards calls to this one; the response carries instructions),
        `area_code`, `state`.
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        '200': { description: 'Active: { tenant_id, phone_number, status, already_assigned, mode, forwarding_instructions? }' }
        '403': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '502': { $ref: '#/components/responses/Error' }
  /api/v1/calls:
    get:
      summary: List calls, newest first
      description: 'Scope `calls:read`. Transcripts are not included.'
      parameters:
        - { name: tenant_id, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 } }
        - { name: starting_after, in: query, description: 'The `next_cursor` of the previous page', schema: { type: string } }
      responses:
        '200': { description: A page of calls with `has_more` and `next_cursor` }
  /api/v1/usage:
    get:
      summary: Billable usage in a date range
      description: 'Scope `usage:read`.'
      parameters:
        - { name: from, in: query, required: true, schema: { type: string, format: date } }
        - { name: to, in: query, required: true, schema: { type: string, format: date } }
      responses:
        '200': { description: Totals by kind, and by tenant }
        '400': { $ref: '#/components/responses/Error' }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, description: 'API key: sk_test_... or sk_live_...' }
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type: { type: string, description: 'e.g. invalid_key, insufficient_scope, invalid_request, unsafe_url, not_found, server_error' }
            message: { type: string }
            request_id: { type: string }
    Connector:
      type: object
      properties:
        baseUrl: { type: string }
        timeoutMs: { type: integer }
        enabled: { type: boolean }
        lastTestedAt: { type: [string, 'null'] }
        lastTestPassed: { type: [boolean, 'null'] }
        secret: { type: string, description: 'Only on create or rotate. Shown once.' }
    ConformanceReport:
      type: object
      properties:
        passed: { type: boolean }
        failedRequired: { type: integer }
        warnings: { type: integer }
        latency: { type: object, properties: { p50Ms: { type: [integer, 'null'] }, p95Ms: { type: [integer, 'null'] }, budgetMs: { type: integer } } }
        steps:
          type: array
          items:
            type: object
            properties:
              id: { type: string }
              title: { type: string }
              required: { type: boolean }
              passed: { type: boolean }
              durationMs: { type: [integer, 'null'] }
              detail: { type: string }
        ranAt: { type: string }
webhooks:
  sanaaEvent:
    post:
      summary: An event Sanaa sends to your webhook endpoint
      description: >
        Signed like connector requests: header `Sanaa-Signature: v1=<hex HMAC-SHA256 of "<Sanaa-Timestamp>.<raw body>">`
        using the endpoint's secret, plus `Sanaa-Timestamp` and `Sanaa-Event-Id`. Reply 2xx to acknowledge.
        Delivery is at least once: de-duplicate on the event id. Failures are retried after
        1 min, 5 min, 30 min, 2 h, 6 h, 24 h, 24 h (8 attempts in all); a 4xx other than 408 or 429 is final.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id: { type: string, example: evt_0f3c9a }
                type: { type: string, example: call.ended }
                api_version: { type: string, example: '2026-11-14' }
                created: { type: integer, description: Unix seconds }
                data: { type: object }
      responses:
        '200': { description: Acknowledged }
