feat: add messaging REST API spec

Document the high-level messaging client REST surface following the
existing per-endpoint-file structure:

- POST/DELETE /messaging/v1/subscriptions (subscribe by content topic)
- POST /messaging/v1/messages (send a MessageEnvelope -> requestId)
- GET /messaging/v1/events/send[/{requestId}] (poll send events)
- GET /messaging/v1/events/received (poll received messages)

Adds the messaging schemas to schemas/apitypes.yaml (MessagingJsonEnvelope,
MessagingSendResponse, SendEventRecord, SendStatus, ReceivedMessageRecord,
list wrappers) and wires the paths + a `messaging` tag into openapi.yaml.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

api-spec/messagingapi_events_received.yaml

@@ -0,0 +1,16 @@
+# /messaging/v1/events/received:
+get: # get_messaging_v1_events_received
+  summary: Poll buffered received messages
+  description: Returns buffered received messages (up to the cache capacity, oldest first), then clears them (evict-after-poll). Optimized for polling; each record carries the message hash and the full received WakuMessage.
+  operationId: getMessagingReceivedMessages
+  tags:
+    - messaging
+  responses:
+    '200':
+      description: The buffered received messages, oldest first.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/ReceivedMessagesResponse'
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_events_send.yaml

@@ -0,0 +1,16 @@
+# /messaging/v1/events/send:
+get: # get_messaging_v1_events_send
+  summary: Poll all buffered send events
+  description: Returns all buffered send events grouped by request id, then clears them (evict-after-poll). Send events are buffered because REST is a poll-based surface over the interactive MessagingClient events.
+  operationId: getMessagingSendEvents
+  tags:
+    - messaging
+  responses:
+    '200':
+      description: The buffered send events, grouped by request id.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/SendStatusList'
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_events_send_by_id.yaml

@@ -0,0 +1,27 @@
+# /messaging/v1/events/send/{requestId}:
+get: # get_messaging_v1_events_send_by_id
+  summary: Poll the send events for one request id
+  description: Returns the buffered send events for a single request id, then removes them (evict-after-poll). The request id is the value returned by POST /messaging/v1/messages.
+  operationId: getMessagingSendEventsById
+  tags:
+    - messaging
+  parameters:
+    - in: path
+      name: requestId   # Note the name is the same as in the path
+      required: true
+      schema:
+        type: string
+      description: The request id returned by the send endpoint.
+  responses:
+    '200':
+      description: The buffered send events for the request id.
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/SendStatus'
+    '404':
+      description: No send events buffered for the given request id.
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_messages.yaml

@@ -0,0 +1,23 @@
+# /messaging/v1/messages:
+post: # post_messaging_v1_messages
+  summary: Send a message through the messaging client
+  description: Sends a message (a MessageEnvelope) through the messaging client and returns the request id used to correlate the subsequent send events.
+  operationId: postMessagingMessage
+  tags:
+    - messaging
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: './schemas/apitypes.yaml#/MessagingJsonEnvelope'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: './schemas/apitypes.yaml#/MessagingSendResponse'
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.

api-spec/messagingapi_subscriptions.yaml

@@ -0,0 +1,50 @@
+# /messaging/v1/subscriptions:
+post: # post_messaging_v1_subscriptions
+  summary: Subscribe the messaging client to an array of content topics
+  description: Subscribe the messaging client to an array of Content topics.
+  operationId: postMessagingSubscriptions
+  tags:
+    - messaging
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: './schemas/apitypes.yaml#/ContentTopic'
+  responses:
+    '200':
+      description: OK
+      content:
+        text/plain:
+          schema:
+            type: string
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.
+
+delete: # delete_messaging_v1_subscriptions
+  summary: Unsubscribe the messaging client from an array of content topics
+  description: Unsubscribe the messaging client from an array of Content topics.
+  operationId: deleteMessagingSubscriptions
+  tags:
+    - messaging
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: './schemas/apitypes.yaml#/ContentTopic'
+  responses:
+    '200':
+      description: OK
+      content:
+        text/plain:
+          schema:
+            type: string
+    '4XX':
+      description: Bad request.
+    '5XX':
+      description: Unexpected error.

api-spec/openapi.yaml

@@ -28,6 +28,8 @@ tags:
     description: Control of the content filtering. See [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12/) RFC
   - name: filter_legacy
     description: Obsolate Filter interface kept for compatibility reason. Will be removed in future.
+  - name: messaging
+    description: High-level messaging client interface (subscribe / send by content topic) and poll-based observation of send and received events.
 paths:
   /health:
     $ref: "./healthapi.yaml"
@@ -89,6 +91,16 @@ paths:
     $ref: "./filterapi_v2_subscriptions_all.yaml"
   /filter/v2/messages/{contentTopic}:
     $ref: "./filterapi_v2_messages.yaml"
+  /messaging/v1/subscriptions:
+    $ref: "./messagingapi_subscriptions.yaml"
+  /messaging/v1/messages:
+    $ref: "./messagingapi_messages.yaml"
+  /messaging/v1/events/send:
+    $ref: "./messagingapi_events_send.yaml"
+  /messaging/v1/events/send/{requestId}:
+    $ref: "./messagingapi_events_send_by_id.yaml"
+  /messaging/v1/events/received:
+    $ref: "./messagingapi_events_received.yaml"
 components:
   schemas:
     $ref: "./schemas/apitypes.yaml"

api-spec/schemas/apitypes.yaml

@@ -320,3 +320,90 @@ HealthReport:
         type: object
         additionalProperties:
           $ref: "#/HealthStatus"
+
+## Messaging API types
+
+MessagingJsonEnvelope:
+  type: object
+  description: JSON wire form of the messaging MessageEnvelope (the send input).
+  properties:
+    payload:
+      type: string
+      format: byte
+    contentTopic:
+      $ref: "#/ContentTopic"
+    ephemeral:
+      type: boolean
+    meta:
+      type: string
+      format: byte
+  required:
+    - payload
+    - contentTopic
+
+MessagingSendResponse:
+  type: object
+  properties:
+    requestId:
+      type: string
+      description: Correlates the send with its MessageSent / MessageError events.
+  required:
+    - requestId
+
+SendEventRecord:
+  type: object
+  properties:
+    kind:
+      type: string
+      enum:
+        - "sent"
+        - "propagated"
+        - "error"
+    messageHash:
+      type: string
+    error:
+      type: string
+      description: Populated only when kind is "error".
+    timestamp:
+      type: integer
+      format: int64
+      description: Nanoseconds, stamped when the event was cached.
+  required:
+    - kind
+    - messageHash
+    - timestamp
+
+SendStatus:
+  type: object
+  description: All send events observed so far for a single request id.
+  properties:
+    requestId:
+      type: string
+    events:
+      type: array
+      items:
+        $ref: "#/SendEventRecord"
+  required:
+    - requestId
+    - events
+
+SendStatusList:
+  type: array
+  items:
+    $ref: "#/SendStatus"
+
+ReceivedMessageRecord:
+  type: object
+  properties:
+    messageHash:
+      type: string
+    message:
+      $ref: "#/RelayWakuMessage"
+  required:
+    - messageHash
+    - message
+
+ReceivedMessagesResponse:
+  type: array
+  items:
+    $ref: "#/ReceivedMessageRecord"