githubmirror/novu

docs/api-reference.mdx
116 строк6 KB
Dima Grossman
docs(docs): improve SEO and GEO positioning fixes DOC-386 (#11728)
30 июн 2026, 18:52
30 июн 2026, 18:524eacbb0
---
title: 'Novu REST API Reference'
description: 'Manage subscribers, trigger workflows, configure integrations, and operate your notification infrastructure with the Novu REST API.'
sidebarTitle: Overview
---

The Novu REST API lets you manage subscribers, trigger workflows, configure integrations, and operate your notification infrastructure from your backend. Start with these common operations:

- [Trigger event](/api-reference/events/trigger-event) — send a workflow to a subscriber
- [Create a subscriber](/api-reference/subscribers/create-a-subscriber) — register a notification recipient
- [Retrieve subscriber notifications](/api-reference/subscribers/retrieve-subscriber-notifications) — read in-app notifications for the Inbox
- [Create a workflow](/api-reference/workflows/create-a-workflow) — define a notification workflow programmatically
- [Authentication](/api-reference/authentication) — authenticate requests with your secret API key

Use the API directly with HTTP requests, or through one of our [server-side SDKs](/platform/sdks#server-side-sdks).

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

## Base URL

| 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](/api-reference/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, 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](/api-reference/pagination) metadata.
- **Consistent errors** — Failures return a standard error body with a `statusCode` and `message`. See [Errors](/api-reference/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:

<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="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 translations, contexts, layouts, channel connections, and activity tracking.

## Developer resources

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/blob/main/postman/novu_api_postman_collection.json">
    Pre-built requests to test endpoints in Postman or compatible tools.
  </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>

### Import the Postman collection

1. Clone or download the [novu-postman](https://github.com/novuhq/novu-postman) repository.
2. Import `postman/novu_api_postman_collection.json` into Postman.
3. Set the `secretKey` collection variable to your environment's secret key from the [API Keys](https://dashboard.novu.co/api-keys) page.

## Getting started

<Steps>
  <Step title="Get your API key">
    Copy your environment's secret key from the [Novu Dashboard](https://dashboard.novu.co/api-keys). See [Authentication](/api-reference/authentication) for details on credential types and security.
  </Step>
  <Step title="Make your first request">
    Trigger a workflow or create a subscriber using the REST API or an SDK. Start with [Trigger event](/api-reference/events/trigger-event) or [Create a subscriber](/api-reference/subscribers/create-a-subscriber).
  </Step>
  <Step title="Review API policies">
    Understand [Errors](/api-reference/errors), [Pagination](/api-reference/pagination), [Rate limiting](/api-reference/rate-limiting), [Idempotency](/api-reference/idempotency), and [Payload limits](/api-reference/payload-limits) before building production integrations.
  </Step>
</Steps>