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: 0.3.2
  contact:
    name: Kévin Dunglas
    url: https://mercure.rocks
    email: contact@mercure.rocks
  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: topic
          in: query
          description: The topic to get updates from, can be a URI template (RFC6570).
          required: true
          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.
          content:
            "text/event-stream": {}
        "401":
          $ref: "#/components/responses/401"
        "400":
          description: Missing topic parameter or invalid URI template.
    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: IRIs of the updated topic. If this key is present several times, the first occurrence is considered to be the canonical URL of the topic, and other ones are considered to be alternate URLs.
                  type: array
                  items:
                    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"
        '400':
          description: Invalid request
  "/.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/ld+json":
              schema:
                $ref: "#/components/schemas/Subscriptions"
        "401":
          $ref: "#/components/responses/401"
  "/.well-known/mercure/subscriptions/{topic}":
    get:
      summary: Active subscriptions for the given topic
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#subscription-api
      parameters:
        - in: path
          name: topic
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The list of active subscriptions
          content:
            "application/ld+json":
              schema:
                $ref: "#/components/schemas/Subscriptions"
        "401":
          $ref: "#/components/responses/401"
  "/.well-known/mercure/subscriptions/{topic}/{subscriber}":
    get:
      summary: Active subscription for the given topic and subscriber
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#active-subscriptions
      parameters:
        - in: path
          name: topic
          schema:
            type: string
          required: true
        - in: path
          name: subscriber
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The list of active subscriptions
          content:
            "application/ld+json":
              schema:
                $ref: "#/components/schemas/Subscriptions"
        "401":
          $ref: "#/components/responses/401"
components:
  schemas:
    Subscriptions:
      type: object
      required: ["@context", "id", "type", "lastEventID", "subscriptions"]
      properties:
        "@context":
          type: string
          format: iri
          example: https://mercure.rocks/
        id:
          type: string
          format: iri-reference
          example: /.well-known/mercure/subscriptions
        type:
          type: string
          format: iri-reference
          example: Subscriptions
        lastEventID:
          type: string
          example: urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
    Subscription:
      type: object
      required: ["id", "type", "topic", "subscriber", "active"]
      properties:
        "@context":
          type: string
          format: iri
          example: https://mercure.rocks/
        id:
          type: string
          format: iri-reference
          example: /.well-known/mercure/subscriptions
        type:
          type: string
          format: iri-reference
          example: Subscription
        topic:
          type: string
          example: https://example.com/{selector}
        subscriber:
          type: string
          example: urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6
        active:
          type: boolean
        payload:
          type: object
        lastEventID:
          type: string
          example: urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb
  responses:
    "401":
      description: Not authorized (missing or invalid JWT).
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Preferred for server to server
    Cookie:
      type: apiKey
      in: cookie
      name: mercureAuthorization
      description: 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