openapi: 3.0.2
servers:
  - url: http://mercure.local
info:
  contact:
    email: contact@mercure.rocks
    name: Kévin Dunglas
    url: https://mercure.rocks
  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."
  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
  title: The Mercure protocol
  version: 0.3.2
  x-apisguru-categories:
    - messaging
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://raw.githubusercontent.com/dunglas/mercure/master/public/mercure.svg?sanitize=true
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/dunglas/mercure/main/spec/openapi.yaml
      version: "3.0"
  x-providerName: mercure.local
externalDocs:
  description: The Mercure protocol specification
  url: https://mercure.rocks/spec
security:
  - Bearer: []
  - Cookie: []
paths:
  /.well-known/mercure:
    get:
      externalDocs:
        description: Subscription specification
        url: https://mercure.rocks/spec#subscription
      parameters:
        - description: The topic to get updates from, can be a URI template (RFC6570).
          in: query
          name: topic
          required: true
          schema:
            items:
              type: string
            type: array
        - description: The last received event id, to retrieve missed events.
          in: query
          name: Last-Event-ID
          schema:
            type: string
        - description: The last received event id, to retrieve missed events, takes precedence over the query parameter.
          in: header
          name: Last-Event-ID
          schema:
            type: string
      responses:
        "200":
          content:
            text/event-stream: {}
          description: Event stream opened.
        "400":
          description: Missing topic parameter or invalid URI template.
        "401":
          $ref: "#/components/responses/401"
      summary: Subscribe to updates
    post:
      externalDocs:
        description: Publishing specification
        url: https://mercure.rocks/spec#publication
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                data:
                  description: The content of the new version of this topic.
                  type: string
                id:
                  description: "The topic's revision identifier: it will be used as the SSE's `id` property."
                  type: string
                private:
                  description: To mark an update as private. If not provided, this update will be public.
                  type: boolean
                retry:
                  description: The SSE's `retry` property (the reconnection time).
                  type: integer
                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.
                  items:
                    type: string
                  type: array
                type:
                  description: The SSE's `event` property (a specific event type).
                  type: string
              required:
                - topic
                - data
      responses:
        "200":
          content:
            text/plain: {}
          description: The id of this update
        "400":
          description: Invalid request
        "401":
          $ref: "#/components/responses/401"
      summary: Publish an update
  /.well-known/mercure/subscriptions:
    get:
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#subscription-api
      responses:
        "200":
          content:
            application/ld+json:
              schema:
                $ref: "#/components/schemas/Subscriptions"
          description: The list of active subscriptions
        "401":
          $ref: "#/components/responses/401"
      summary: Active subscriptions
  "/.well-known/mercure/subscriptions/{topic}":
    get:
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#subscription-api
      parameters:
        - in: path
          name: topic
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/ld+json:
              schema:
                $ref: "#/components/schemas/Subscriptions"
          description: The list of active subscriptions
        "401":
          $ref: "#/components/responses/401"
      summary: Active subscriptions for the given topic
  "/.well-known/mercure/subscriptions/{topic}/{subscriber}":
    get:
      externalDocs:
        description: Subscription API
        url: https://mercure.rocks/spec#active-subscriptions
      parameters:
        - in: path
          name: topic
          required: true
          schema:
            type: string
        - in: path
          name: subscriber
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/ld+json:
              schema:
                $ref: "#/components/schemas/Subscriptions"
          description: The list of active subscriptions
        "401":
          $ref: "#/components/responses/401"
      summary: Active subscription for the given topic and subscriber
components:
  responses:
    "401":
      description: Not authorized (missing or invalid JWT).
  schemas:
    Subscription:
      properties:
        "@context":
          example: https://mercure.rocks/
          format: iri
          type: string
        active:
          type: boolean
        id:
          example: /.well-known/mercure/subscriptions
          format: iri-reference
          type: string
        lastEventID:
          example: urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb
          type: string
        payload:
          type: object
        subscriber:
          example: urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6
          type: string
        topic:
          example: https://example.com/{selector}
          type: string
        type:
          example: Subscription
          format: iri-reference
          type: string
      required:
        - id
        - type
        - topic
        - subscriber
        - active
      type: object
    Subscriptions:
      properties:
        "@context":
          example: https://mercure.rocks/
          format: iri
          type: string
        id:
          example: /.well-known/mercure/subscriptions
          format: iri-reference
          type: string
        lastEventID:
          example: urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb
          type: string
        subscriptions:
          items:
            $ref: "#/components/schemas/Subscription"
          type: array
        type:
          example: Subscriptions
          format: iri-reference
          type: string
      required:
        - "@context"
        - id
        - type
        - lastEventID
        - subscriptions
      type: object
  securitySchemes:
    Bearer:
      bearerFormat: JWT
      description: Preferred for server to server
      scheme: bearer
      type: http
    Cookie:
      description: Preferred for web browsers (the cookie name may change depending on the configuration)
      in: cookie
      name: mercureAuthorization
      type: apiKey
