dunglas / mercure

openapi: 3.0.2
info:
  title: The Mercure protocol
  description: "[Mercure](https://mercure.rocks) is a protocol allowing to push data updates to web browsers and other HTTP clients in a convenient, fast, reliable and battery-efficient way."
  version: 1.0.0
  contact:
    name: Kévin Dunglas
    url: https://mercure.rocks
    email: [email protected]
  license:
    name: GNU Affero General Public License v3.0 or later
    url: https://github.com/dunglas/mercure/blob/master/LICENSE
    x-spdx: AGPL-3.0-or-later
paths:
  "/.well-known/mercure":
    get:
      summary: Subscribe to updates
      externalDocs:
        description: Subscription specification
        url: https://mercure.rocks/spec#subscription
      parameters:
        - name: match
          in: query
          description: >-
            Exact topic matcher (the default matcher type). Repeatable.
            Case-sensitive. At least one matcher parameter is required.
          schema:
            type: array
            items:
              type: string
        - name: match_urlpattern
          in: query
          description: >-
            URL Pattern topic matcher (WHATWG URL Pattern). Repeatable.
          schema:
            type: array
            items:
              type: string
        - name: last_event_id
          in: query
          description: The last received event id, to retrieve missed events.
          schema:
            type: string
        - name: Last-Event-ID
          in: header
          description: The last received event id, to retrieve missed events, takes precedence over the query parameter.
          schema:
            type: string
      responses:
        "200":
          description: Event stream opened.
          headers:
            Mercure-Last-Event-ID:
              description: The id of the event preceding the first one sent, or the reserved value earliest when there is none. Set whenever the request carried a resumption cursor; compare it with the requested id to detect data loss.
              schema:
                type: string
          content:
            "text/event-stream": {}
        "401":
          $ref: "#/components/responses/401"
        "400":
          description: Missing or invalid topic matcher parameter.
    post:
      summary: Publish an update
      externalDocs:
        description: Publishing specification
        url: https://mercure.rocks/spec#publication
      requestBody:
        content:
          "application/x-www-form-urlencoded":
            schema:
              properties:
                topic:
                  description: The IRI of the updated topic. Exactly one topic field is allowed.
                  type: string
                data:
                  description: The content of the new version of this topic.
                  type: string
                private:
                  description: To mark an update as private. If not provided, this update will be public.
                  type: boolean
                id:
                  description: "The topic's revision identifier: it will be used as the SSE's `id` property."
                  type: string
                type:
                  description: The SSE's `event` property (a specific event type).
                  type: string
                retry:
                  description: The SSE's `retry` property (the reconnection time).
                  type: integer
              required:
                - topic
                - data
      responses:
        "200":
          description: The id of this update
          content:
            "text/plain": {}
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "400":
          description: Invalid request
  "/.well-known/oauth-protected-resource/.well-known/mercure":
    get:
      summary: OAuth 2.0 protected resource metadata
      description: >-
        RFC 9728 protected resource metadata for the hub, advertising its
        resource identifier, accepted bearer methods, and (when configured)
        authorization servers.
      externalDocs:
        description: Protected resource metadata
        url: https://mercure.rocks/spec#protected-resource-metadata
      security: []
      responses:
        "200":
          description: The protected resource metadata document
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ProtectedResourceMetadata"
  "/.well-known/mercure/subscriptions":
    get:
      summary: Active subscriptions
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#subscription-api
      responses:
        "200":
          description: The list of active subscriptions
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Subscriptions"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
  "/.well-known/mercure/subscriptions/{match_type}/{match}":
    get:
      summary: Active subscriptions for the given topic matcher
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#subscription-api
      parameters:
        - in: path
          name: match_type
          description: The matcher type (e.g. exact, urlpattern).
          schema:
            type: string
          required: true
        - in: path
          name: match
          description: The percent-encoded topic matcher.
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The list of active subscriptions
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Subscriptions"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
  "/.well-known/mercure/subscriptions/{match_type}/{match}/{subscriber}":
    get:
      summary: Active subscription for the given matcher and subscriber
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#active-subscriptions
      parameters:
        - in: path
          name: match_type
          description: The matcher type (e.g. exact, urlpattern).
          schema:
            type: string
          required: true
        - in: path
          name: match
          description: The percent-encoded topic matcher.
          schema:
            type: string
          required: true
        - in: path
          name: subscriber
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The list of active subscriptions
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Subscriptions"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
components:
  schemas:
    Subscriptions:
      type: object
      required: ["id", "type", "last_event_id", "subscriptions"]
      properties:
        id:
          type: string
          format: iri-reference
          example: /.well-known/mercure/subscriptions
        type:
          type: string
          example: subscriptions
        last_event_id:
          type: string
          example: urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb
        subscriptions:
          type: array
          items:
            $ref: "#/components/schemas/Subscription"
    Subscription:
      type: object
      required: ["id", "type", "match", "match_type", "subscriber", "active"]
      properties:
        id:
          type: string
          format: iri-reference
          example: /.well-known/mercure/subscriptions
        type:
          type: string
          example: subscription
        match:
          type: string
          example: https://example.com/:selector
        match_type:
          type: string
          example: urlpattern
        subscriber:
          type: string
          example: urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6
        active:
          type: boolean
        payload:
          type: object
        last_event_id:
          type: string
          example: urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb
    ProtectedResourceMetadata:
      type: object
      required: ["resource"]
      properties:
        resource:
          type: string
          format: uri
          example: https://example.com/.well-known/mercure
        bearer_methods_supported:
          type: array
          items:
            type: string
          example: ["header"]
        authorization_servers:
          type: array
          items:
            type: string
        authorization_details_types_supported:
          type: array
          items:
            type: string
          example: ["https://mercure.rocks/authorization-detail"]
        mercure_cookie:
          type: string
          example: __Secure-mercure_access_token
        mercure_subscriptions:
          type: boolean
  responses:
    "401":
      description: >-
        Missing or invalid access token. Carries a `WWW-Authenticate: Bearer`
        challenge (with `error="invalid_token"` when a token was presented but
        failed validation) and, per RFC 9728, a `resource_metadata` parameter
        pointing to the protected resource metadata document.
    "403":
      description: >-
        The access token is valid but does not grant the requested action on
        the topic. Carries a `WWW-Authenticate: Bearer` challenge with
        `error="insufficient_scope"` (RFC 6750).
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: at+jwt
      description: >-
        RFC 9068 JWT access token (`typ: at+jwt`) carrying an
        `authorization_details` claim (RFC 9396) of `type: mercure`, whose
        entries grant the `publish` and/or `subscribe` actions on topic
        matchers. Preferred for server to server.
    Cookie:
      type: apiKey
      in: cookie
      name: mercure_access_token
      description: >-
        Same access token carried in a cookie (a Mercure extension to
        RFC 6750). Preferred for web browsers; the cookie name may change
        depending on the configuration.
security:
  - Bearer: []
  - Cookie: []
externalDocs:
  description: The Mercure protocol specification
  url: https://mercure.rocks/spec