REST API

The versioned Notifly REST API at api.notifly.io — quickstart, API-key authentication, environments, errors, pagination, idempotency, rate limits, and subscriber credentials.

Everything in Notifly is driven by one versioned REST surface at https://api.notifly.io/v1 — workflows, subscribers, topics, messages, notifications, integrations, layouts, environments, and audit logs. The dashboard uses the same API, so anything it can do, you can automate.

Interactive reference: API reference — every endpoint, schema, and example request, generated from the OpenAPI document.
OpenAPI spec: openapi.json same-origin, or api.notifly.io/openapi.json / openapi.yaml straight from the live API, for codegen and tooling.

Heading ids are a contract

Anchors on this page are linked from outside the docs: the API's idempotency Link response header points at https://notifly.io/docs/api#idempotency, and the OpenAPI document's external-docs link points at this page. Rename a heading only alongside every consumer.

Quickstart

1. Get an API key. API keys live per environment in the Notifly dashboard under API Keys. Sign up, pick an environment, and copy its secret key.

2. Trigger a workflow. Create a workflow in the dashboard, then fire it for a subscriber:

curl -X POST https://api.notifly.io/v1/events/trigger \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<workflow-id>","to":{"subscriberId":"<subscriber-id>"},"payload":{"body":"Hello from Notifly"}}'

3. Read your subscribers. Every recipient is a subscriber you can list, inspect, and update:

curl "https://api.notifly.io/v1/subscribers?page=0&limit=10" \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY"

Authentication

Authenticate every request with the ApiKey scheme in the Authorization header:

Authorization: ApiKey <secret-key>

Keys are environment-scoped — a Development key can never touch Production data. Treat the secret key like a password: keep it server-side, never ship it in browser or mobile code, and roll it from the dashboard if it leaks.

Environments

Each organization has separate environments (Development and Production by default). Workflows, subscribers, messages, and API keys all belong to exactly one environment, so you can iterate safely in Development and promote to Production when ready. The environment a request operates on is determined by the API key you authenticate with.

Errors

The API uses standard HTTP status codes: 2xx success, 400 invalid input, 401 missing or bad key, 404 not found, 409/422 conflicts, 429 rate limited. Error responses carry a JSON body with a message and a statusCode:

{
  "statusCode": 404,
  "message": "Workflow not found",
  "error": "Not Found"
}

Pagination

List endpoints accept page (0-based) and limit query parameters and return items in data. Responses include either a hasMore boolean or a total count depending on the endpoint — when hasMore is true, request the next page.

Idempotency

Send an Idempotency-Key header (any unique string, e.g. a UUID) on POST and PATCH requests to make retries safe. Idempotency applies to ApiKey-authenticated requests.

curl -X POST https://api.notifly.io/v1/events/trigger \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Idempotency-Key: 0d1f6c1e-8f2a-4b0c-9d3e-5a6b7c8d9e0f" \
  -H "Content-Type: application/json" \
  -d '{"name":"<workflow-id>","to":{"subscriberId":"<subscriber-id>"},"payload":{"body":"Hello"}}'

Replays within the 24-hour window return the original response with the Idempotency-Replay: true header.
Reusing a key with a different request body is rejected with 422.
A concurrent duplicate (first request still in flight) returns 409 with a Retry-After header.

Rate limits

Requests are metered with a token-bucket algorithm: each environment has a steady refill rate plus burst capacity, and heavier endpoints draw more from the bucket. Every response includes RateLimit-* headers describing the current limit, remaining allowance, and reset time. On 429, back off for the Retry-After duration and retry — read the headers rather than hard-coding numbers, since exact limits depend on the deployment and plan.

Subscriber credentials

Push device tokens and chat webhook credentials are stored per subscriber, per provider. Set them with PUT /v1/subscribers/{subscriberId}/credentials — they also show up in the subscriber drawer in the dashboard.

curl -X PUT https://api.notifly.io/v1/subscribers/<subscriber-id>/credentials \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"fcm","credentials":{"deviceTokens":["<device-token>"]}}'

SDKs

Python — notifly-py is published on PyPI and covers the full REST surface. See the Python SDK page.
JavaScript, React, Next.js, React Native — these client SDKs are open source and publishing them to npm is in progress. Until they land, the REST API is the supported integration path.

MCP server

Notifly also ships a remote MCP server at api.notifly.io/mcp with OAuth 2.1 sign-in and seven tools for AI clients. See Connect AI assistants for the tool list and the setup command.

On this page