Skip to main content
The Novu REST API lets you manage subscribers, trigger workflows, configure integrations, operate agents, and run your notification infrastructure from your backend. Start with these common operations: Use the API directly with HTTP requests, through one of our server-side SDKs, or with our official Postman collection.
The REST API and server-side SDKs are intended for server-side applications only. Using them in client-side code causes Cross-Origin Resource Sharing (CORS) errors and exposes your secret key.

​
Base URL

RegionBase URL
US (default)https://api.novu.co/v1
EUhttps://eu.api.novu.co/v1
All endpoints in this reference use the US base URL unless noted otherwise. See Authentication for regional WebSocket hostnames and credential setup.

​
API conventions

The Novu API is organized around REST. It has predictable, resource-oriented URLs, accepts and returns JSON request and response bodies, and uses standard HTTP verbs and status codes.
  • Resource-oriented — Each resource (subscribers, topics, workflows, agents, and more) has its own set of endpoints. Use POST to create, GET to read, PATCH/PUT to update, and DELETE to remove.
  • JSON everywhere — Send Content-Type: application/json on requests with a body. Responses are JSON-encoded.
  • Response envelope — Successful responses wrap the result in a data field, for example { "data": { ... } }. List endpoints return { "data": [ ... ] } alongside pagination metadata.
  • Consistent errors — Failures return a standard error body with a statusCode and message. See Errors.
  • Versioned paths — The API version is part of the URL (/v1, /v2).

​
API capabilities

The REST API is organized around the core resources you use to build and operate notifications:

Events

Trigger, bulk trigger, broadcast, and cancel workflow executions.

Subscribers

Create, update, and manage notification recipients and their preferences.

Inbox

Read, mark, archive, snooze, and manage in-app notifications.

Topics

Group subscribers and send notifications to topic audiences.

Workflows

Create, sync, and manage notification workflow definitions.

Integrations

Configure channel providers for email, SMS, push, and chat delivery.

Agents

Create agents, link providers, and send replies.

Environments

Manage environments and publish resources between them.

Messages

List and delete sent messages across channels.
Browse the sidebar for the full endpoint reference, including agents, translations, contexts, layouts, channel connections, and activity tracking.

​
Developer resources

Use these resources to explore, test, and integrate with the API:

OpenAPI specification

Machine-readable API schema for code generation, validation, and tooling.

Postman collection

Official Postman collection with pre-built requests for every endpoint.

Server-side SDKs

Official SDKs for TypeScript, Python, Go, PHP, .NET, and Java.

Authentication

Set up API keys, environment credentials, and security best practices.

Errors

HTTP status codes, error response shapes, and how to debug failed requests.

Pagination

Page through large list responses with cursor-based pagination.

​
Import the Postman collection

The novu-postman repository contains the official Novu API Postman collection, kept in sync with the REST API.
  1. Clone or download the repository from github.com/novuhq/novu-postman.
  2. Import postman/novu_api_postman_collection.json into Postman (or any compatible client).
  3. Set the secretKey collection variable to your environment’s secret key from the API Keys page.
You can also import the collection directly from the raw JSON file: novu_api_postman_collection.json.

​
Getting started

1

Get your API key

Copy your environment’s secret key from the Novu Dashboard. See Authentication for details on credential types and security.
2

Make your first request

Trigger a workflow, create a subscriber, or create an agent using the REST API or an SDK. Start with Trigger event, Create a subscriber, or Create an agent.
3

Review API policies

Understand Errors, Pagination, Rate limiting, Idempotency, and Payload limits before building production integrations.