canonical: https://jentic.com/apis/ntfy.sh/ntfy

# Ntfy Sh ntfy API

The ntfy API is an open-source push notification service that sends and receives notifications over simple HTTP requests. Its publish and subscribe operations need no credential for public topics, so a message can be sent with a single request. Publishing supports titles, priorities, tags, actions, attachments, and scheduled delivery, and subscribers can read a topic as a JSON stream, Server-Sent Events, raw text, or a WebSocket.

## For AI agents

Publish push notifications to a topic with titles, priorities, tags, and attachments, and subscribe to a topic as JSON, SSE, raw text, or WebSocket.

## Scope

Does not handle SMS, voice calls, or email delivery. Use for topic-based push notifications only.

## Capabilities

- Publish a notification to a topic with a title, priority, tags, and actions
- Attach a file or schedule delivery when publishing a message
- Subscribe to a topic as a JSON stream, Server-Sent Events, raw text, or WebSocket
- Publish a notification using a JSON payload to the root endpoint
- Send notifications to public topics without an account

## Use cases

### AI Agent Alerting

An AI agent connected through Jentic sends operational alerts by publishing a notification to a topic when a task finishes or fails, setting a priority and tags so the message is easy to triage. Because public topics need no account, the agent can start sending with a single request.

Example prompt: Publish a high-priority notification with a title and tags to a topic when a job finishes

### Message Subscription Stream

A service subscribes to an ntfy topic and processes each new message as it arrives, choosing a JSON stream or Server-Sent Events depending on the client. This turns a topic into a lightweight message channel between systems.

Example prompt: Subscribe to a topic via Server-Sent Events and process each new message

### Self-Hosted Push Without Accounts

A team running its own ntfy instance publishes notifications to public topics without managing credentials, keeping the whole flow on its own infrastructure. Optional token or Basic auth can be added later for private topics.

Example prompt: Publish a notification to a public topic without any credential

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/{topic}` | Publish a notification to a topic |
| PUT | `/{topic}` | Publish a notification to a topic (PUT variant) |
| POST | `/` | Publish a notification using a JSON payload |
| GET | `/{topic}/json` | Subscribe via a JSON stream |
| GET | `/{topic}/sse` | Subscribe via Server-Sent Events |
| GET | `/{topic}/ws` | Subscribe via WebSocket |

## Key resources

- **Publish** — Publish notifications to a topic with titles, priorities, tags, and attachments
- **Subscribe** — Subscribe to a topic as JSON, Server-Sent Events, raw text, or WebSocket

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 56 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 52 / 100
  - AI-Readiness & Agent Experience: 44 / 100
  - Agent Usability: 94 / 100
  - Security: 35 / 100
  - AI Discoverability: 59 / 100
- **View full report:** https://jentic.com/apis/ntfy.sh/ntfy/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the ntfy API by hand means choosing between public topics and optional Basic or bearer auth, and shaping each publish request with its title, priority, and tags yourself. Through Jentic you install once, import ntfy from the API Directory, store a token only if you need one, and your agent calls it.
- **Permission scoping:** ntfy puts the topic in the URL path (/{topic}), so a rule can pin your agent to one topic. You choose the operations it may call, such as publishing to that topic, so subscribing to other topics is not included unless you add it.
- **Credential handling:** If you use an ntfy access token or Basic credentials, they are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a push notification' or 'subscribe to a topic', and Jentic returns the matching ntfy operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Pushover** — Pushover delivers push notifications to mobile and desktop devices.
- **Pusher** — Pusher provides hosted realtime pub/sub channels and push.
- **Plivo** — Plivo adds SMS and voice channels alongside push notifications.

## FAQ

### What authentication does the ntfy API use?

Authentication is optional: ntfy supports HTTP Basic and bearer access-token auth, as declared in its OpenAPI spec, but the publish and subscribe operations need no credential for public topics. Through Jentic any token you do use is stored encrypted by your own Jentic One instance and injected at call time.

### Can I set a priority and tags on a notification with the ntfy API?

Yes. When you publish to a topic you can set a title, priority, tags, and actions, attach a file, or schedule the message for later delivery.

### What are the rate limits for the ntfy API?

The OpenAPI spec does not specify rate limits for the ntfy API. See the ntfy documentation at https://docs.ntfy.sh for the limits on the public server or configure your own on a self-hosted instance.

### Can I limit what my agent is allowed to do with the ntfy API?

Yes. Write a rule that allows only publishing to one topic by naming it in the path, so the agent can send alerts to that topic but cannot subscribe to or publish on others, and every call it makes is logged.

### How do I send a notification with the ntfy API through Jentic?

Search Jentic for 'send a push notification', add the ntfy API from the directory, and store a token once if you use private topics. Your agent then publishes a message to a topic in one call. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there an ntfy API MCP server?

You don't need an MCP server to give your agent the ntfy API. Jentic connects it directly from the API Directory: import it, and your agent calls the publish and subscribe operations. That keeps extra tool definitions out of the agent's context.