Mercure The Mercure protocol
Agent-ready OpenAPI document · curated by JenticCommunicationsPush Notificationsbearer, apiKey5 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Publish real-time updates and subscribe to topic streams over the Mercure SSE-based protocol with JWT authorization.
Use for: I need to push a live update to web browsers, Subscribe to a Mercure topic stream, Publish a JSON event to multiple topics at once, List active subscriptions on the Mercure hub
Not supported: Does not handle email, SMS, mobile push notifications, or message persistence beyond the configured hub history - use for SSE-based real-time fan-out only.
Jentic publishes the only available OpenAPI specification for The Mercure protocol, keeping it validated and agent-ready. Mercure is an open protocol built on top of Server-Sent Events for pushing data updates from a server to web browsers and HTTP clients in a fast, battery-efficient way. The hub exposes a single well-known endpoint for publishing JSON-LD updates and subscribing to topics, plus introspection endpoints that report active subscriptions per topic and subscriber, making it a lightweight backbone for live UIs, real-time dashboards, and notification fan-out.
Install Jentic One Beta
Connect the The Mercure protocol to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the The Mercure protocol, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmercure.local%2Fmercure" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmercure.local%2Fmercure" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with The Mercure protocol API.
Publish JSON updates to one or more topics for live fan-out to subscribed clients
Subscribe to a Mercure topic stream and receive Server-Sent Events for matching updates
List currently active subscriptions on the hub for monitoring and debugging
Inspect subscribers attached to a specific topic to verify delivery routing
Authorise publishers and subscribers with scoped JWTs that constrain topic access
Use Cases
Patterns agents use The Mercure protocol API for, with concrete tasks.
★ Live UI Updates
Web applications can push state changes to every connected browser by POSTing JSON updates to /.well-known/mercure with a topic IRI. Clients subscribe to the same topic via GET on the same path and receive Server-Sent Events. Mercure handles reconnection, last-event-id replay, and HTTP/2 multiplexing, so adding live updates to a SaaS dashboard is typically a few hours of work.
Call POST /.well-known/mercure with topic 'https://example.com/orders/42' and a JSON body to broadcast an order status change.
Notification Fan-Out
Internal tools that need to notify many users about a single event (a deploy, an incident, a chat mention) can publish once to a Mercure topic and let the hub fan out to every subscribed client over Server-Sent Events. This avoids per-user fetch loops and keeps battery and bandwidth use low on mobile clients.
Publish a JSON notification to topic 'https://example.com/incidents' so every subscribed dashboard renders the new alert.
Subscription Monitoring
Operators running a Mercure hub can introspect connected subscribers to debug delivery issues. GET /.well-known/mercure/subscriptions lists all active subscriptions, and the per-topic and per-subscriber endpoints narrow the view to a specific topic or client. This is useful for verifying that a release of a frontend client is actually subscribing to the expected topics.
Call GET /.well-known/mercure/subscriptions/https%3A%2F%2Fexample.com%2Forders%2F42 to see who is currently listening to the orders topic.
Agent-Driven Real-Time Events
An AI agent producing live updates (a long-running build, a multi-step generation job) can publish progress events to a Mercure topic via Jentic, and any frontend or backend subscriber receives them as Server-Sent Events. The agent searches Jentic for the publish operation, loads the schema, and posts updates without writing custom Mercure client code.
Search Jentic for 'publish a Mercure update', load POST /.well-known/mercure, and execute it with the topic and JSON payload describing the agent's progress.
Key Endpoints
5 endpoints — jentic publishes the only available openapi specification for the mercure protocol, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/.well-known/mercure
Publish an update to one or more topics
GET
/.well-known/mercure
Subscribe to topic updates over SSE
GET
/.well-known/mercure/subscriptions
List active subscriptions on the hub
GET
/.well-known/mercure/subscriptions/{topic}
List subscriptions for a topic
GET
/.well-known/mercure/subscriptions/{topic}/{subscriber}
Inspect a specific subscription
POST
/.well-known/mercure
Publish an update to one or more topics
GET
/.well-known/mercure
Subscribe to topic updates over SSE
GET
/.well-known/mercure/subscriptions
List active subscriptions on the hub
GET
/.well-known/mercure/subscriptions/{topic}
List subscriptions for a topic
GET
/.well-known/mercure/subscriptions/{topic}/{subscriber}
Inspect a specific subscription
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Mercure protocol by hand means signing topic-scoped JWTs for the hub, choosing between bearer and cookie auth, and shaping publish and subscription requests against /.well-known/mercure yourself. Through Jentic you install once, import Mercure from the API Directory, store the signing credential once, and your agent calls it.
Permission scoping
Mercure carries the topic in the request body when publishing rather than as a URL path resource, so scope your agent to the operations it needs: limit it to publishing updates or reading subscriptions, and keep out any operation the agent does not require. The subscription topic that does appear in the path (/.well-known/mercure/subscriptions/{topic}) is read-only.
Credential isolation
Your Mercure JWT signing credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'publish a real-time update' or 'list active subscriptions', and Jentic returns the matching Mercure operation such as POST /.well-known/mercure with its topic and data fields so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using The Mercure protocol API through Jentic.
Why is there no official OpenAPI spec for The Mercure protocol?
Mercure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call The Mercure protocol via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does The Mercure protocol use?
The hub accepts a JWT bearer token via the standard Authorization header, preferred for server-to-server calls, or a cookie named mercureAuthorization for browsers. JWT claims constrain which topics a publisher can write to and which a subscriber can read. Through Jentic, JWT signing keys live in the credential vault and the agent gets a scoped Jentic token.
Can I publish to multiple topics in a single Mercure call?
Yes. POST /.well-known/mercure accepts repeated topic form fields, so a single update can be delivered to several topic IRIs at once. This is the standard way to fan out one event to multiple groupings, for example a per-user inbox topic plus a global feed topic.
What are the rate limits for The Mercure protocol?
The protocol itself does not define rate limits; these are enforced by the hub deployment. The reference Mercure hub supports thousands of concurrent subscribers per process and limits are set in hub configuration rather than in the spec, so production rollouts should size the hub for peak concurrent SSE connections.
How do I publish a Mercure update through Jentic?
Install the SDK with pip install jentic, search for 'publish a Mercure update', load the POST /.well-known/mercure operation, and execute it with the topic IRI and JSON data. Jentic attaches the JWT and posts to the configured hub URL.
Does Mercure support private updates only some subscribers can read?
Yes. The publish endpoint accepts a private flag and a list of mercure.publish or mercure.subscribe topic selectors in the JWT. The hub only delivers the update to subscribers whose JWT grants them access to the matching topic IRI.
Can I limit what my agent is allowed to do with the Mercure API?
Yes. Because you run Jentic One yourself, your own rules decide which Mercure operations and credentials the agent may use, so you can grant only what a given agent needs. You can restrict it to publishing updates with POST /.well-known/mercure, or limit it to the read-only introspection endpoints such as GET /.well-known/mercure/subscriptions, while keeping every other operation out of reach. Note that Mercure passes the topic in the request body when publishing rather than in the URL path, so scoping is done at the operation level; the one topic that does appear in the path, /.well-known/mercure/subscriptions/{topic}, is read-only. This lets an operator, for example, allow an agent to broadcast progress events but never inspect who is subscribed.
GET STARTED