docs/api-reference.mdx
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.
<Note> 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. </Note>| Region | Base URL |
|---|---|
| US (default) | https://api.novu.co/v1 |
| EU | https://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.
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.
POST to create, GET to read, PATCH/PUT to update, and DELETE to remove.Content-Type: application/json on requests with a body. Responses are JSON-encoded.data field, for example { "data": { ... } }. List endpoints return { "data": [ ... ] } alongside pagination metadata.statusCode and message. See Errors./v1, /v2).The REST API is organized around the core resources you use to build and operate notifications:
<Columns cols={2}> <Card title="Events" icon="zap" href="/api-reference/events/trigger-event"> Trigger, bulk trigger, broadcast, and cancel workflow executions. </Card> <Card title="Subscribers" icon="users" href="/api-reference/subscribers/create-a-subscriber"> Create, update, and manage notification recipients and their preferences. </Card> <Card title="Inbox" icon="inbox" href="/api-reference/subscribers/retrieve-subscriber-notifications"> Read, mark, archive, snooze, and manage in-app notifications. </Card> <Card title="Topics" icon="hash" href="/api-reference/topics/create-a-topic"> Group subscribers and send notifications to topic audiences. </Card> <Card title="Workflows" icon="git-branch" href="/api-reference/workflows/create-a-workflow"> Create, sync, and manage notification workflow definitions. </Card> <Card title="Integrations" icon="plug" href="/api-reference/integrations/create-an-integration"> Configure channel providers for email, SMS, push, and chat delivery. </Card> <Card title="Agents" icon="bot" href="/api-reference/agents/agent-schema"> Create agents, link providers, and send replies. </Card> <Card title="Environments" icon="server" href="/api-reference/environments/list-all-environments"> Manage environments and publish resources between them. </Card> <Card title="Messages" icon="message-square" href="/api-reference/messages/list-all-messages"> List and delete sent messages across channels. </Card> </Columns>Browse the sidebar for the full endpoint reference, including agents, translations, contexts, layouts, channel connections, and activity tracking.
Use these resources to explore, test, and integrate with the API:
<Columns cols={2}> <Card title="OpenAPI specification" icon="file-json" href="https://api.novu.co/openapi.json"> Machine-readable API schema for code generation, validation, and tooling. </Card> <Card title="Postman collection" icon="send" href="https://github.com/novuhq/novu-postman"> Official Postman collection with pre-built requests for every endpoint. </Card> <Card title="Server-side SDKs" icon="code" href="/platform/sdks#server-side-sdks"> Official SDKs for TypeScript, Python, Go, PHP, .NET, and Java. </Card> <Card title="Authentication" icon="key" href="/api-reference/authentication"> Set up API keys, environment credentials, and security best practices. </Card> <Card title="Errors" icon="circle-alert" href="/api-reference/errors"> HTTP status codes, error response shapes, and how to debug failed requests. </Card> <Card title="Pagination" icon="list" href="/api-reference/pagination"> Page through large list responses with cursor-based pagination. </Card> </Columns>The novu-postman repository contains the official Novu API Postman collection, kept in sync with the REST API.
postman/novu_api_postman_collection.json into Postman (or any compatible client).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.