Skip to content
Permalink
main
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
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
security:
- Bearer: []
- Cookie: []
externalDocs:
description: The Mercure protocol specification
url: https://mercure.rocks/spec