canonical: https://jentic.com/apis/mercure.local/mercure

# Mercure The Mercure protocol

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.

## For AI agents

Publish real-time updates and subscribe to topic streams over the Mercure SSE-based protocol with JWT authorization.

## Scope

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.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Hub** — Publish updates and subscribe to topic streams over Server-Sent Events
- **Subscriptions** — Introspect active subscriptions per topic and subscriber

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **Pusher Channels API** — Hosted real-time pub/sub over WebSockets with presence channels
- **PubNub Pub/Sub API** — Global real-time messaging network with presence, history, and access manager
- **Ably Realtime API** — Realtime pub/sub with strong delivery guarantees and channels

## FAQ

### 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.