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