openapi: 3.1.0
info:
  title: Loam Durable (Resonate protocol)
  version: Resonate 0.10
  description: '**Status: In progress.** The Resonate server is linked into the engine binary and served
    on the main branch, on `127.0.0.1:8001` (loopback only, no auth yet). Its TiKV backend and per-namespace
    tenancy are next.


    Loam Durable speaks the Resonate protocol, so the Resonate SDKs (TypeScript, Python, Rust and others)
    work unmodified. It is an RPC protocol, not REST: every call is `POST /` with an envelope whose `kind`
    names the operation, and the HTTP status equals `head.status`. For the semantics of each kind (promises,
    tasks, schedules, callbacks), read the Resonate protocol documentation at [docs.resonatehq.io](https://docs.resonatehq.io).


    The older REST paths (`/promises`, `/tasks`, `/schedules`) answer 410.'
servers:
- url: http://127.0.0.1:8001
  description: Embedded Resonate server (loopback)
tags:
- name: Protocol
- name: Transport
paths:
  /:
    post:
      tags:
      - Protocol
      summary: Send a protocol request
      operationId: rpc
      x-badges:
      - name: In progress
        color: '#c0842f'
      description: 'One endpoint for every operation. `Authorization: Bearer <token>` fills `head.auth`
        when it is empty.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
            example:
              kind: promise.create
              head:
                corrId: c-1
                version: '0.10'
              data:
                id: research.42
                timeoutAt: 4102444800000
                param:
                  data: eyJxIjoic29pbCJ9
                tags:
                  resonate:target: poll://any@workers
      responses:
        '200':
          description: Response envelope; the HTTP status mirrors `head.status`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        default:
          description: Error response envelope (4xx or 5xx); the HTTP status mirrors `head.status`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
  /ready:
    get:
      tags:
      - Transport
      summary: Readiness
      operationId: ready
      x-badges:
      - name: In progress
        color: '#c0842f'
      responses:
        '200':
          description: Ready.
        '503':
          description: Not ready.
  /poll/{group}/{id}:
    get:
      tags:
      - Transport
      summary: Poll for messages (SSE)
      operationId: poll
      x-badges:
      - name: In progress
        color: '#c0842f'
      description: Server-sent events carrying `execute` and `unblock` messages to workers registered
        under `poll://<id>@<group>`.
      parameters:
      - name: group
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: An event stream.
          content:
            text/event-stream:
              schema:
                type: string
components:
  schemas:
    Request:
      type: object
      required:
      - kind
      - head
      - data
      properties:
        kind:
          type: string
          enum:
          - promise.create
          - promise.get
          - promise.settle
          - promise.search
          - promise.register_callback
          - promise.register_listener
          - task.create
          - task.acquire
          - task.release
          - task.fulfill
          - task.suspend
          - task.continue
          - task.fence
          - task.heartbeat
          - task.halt
          - task.get
          - task.search
          - schedule.create
          - schedule.get
          - schedule.search
          - schedule.delete
        head:
          type: object
          required:
          - corrId
          - version
          properties:
            corrId:
              type: string
            version:
              type: string
            auth:
              type: string
        data:
          type: object
          description: Operation-specific fields, as defined by the Resonate protocol.
    Response:
      type: object
      properties:
        kind:
          type: string
        head:
          type: object
          properties:
            corrId:
              type: string
            status:
              type: integer
            version:
              type: string
        data:
          type: object