docs/api-reference.mdx - next - githubmirror/novu

docs/api-reference.mdx
124 строки7 KB
George Djabarov
docs(docs): replace em dashes with spaced hyphens (#11970)
19 июл 2026, 13:33
19 июл 2026, 13:3306949a1
---
title: 'Novu REST API Reference'
description: 'Manage subscribers, trigger workflows, configure integrations, operate agents, and run your notification infrastructure with the Novu REST API.'
sidebarTitle: Overview
---

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:

- [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
- [Create an agent](/api-reference/agents/create-an-agent) - create a custom code or managed agent
- [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, through one of our [server-side SDKs](/platform/sdks#server-side-sdks), or with our official [Postman collection](https://github.com/novuhq/novu-postman).

<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, 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](/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="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.

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

### Import the Postman collection

The [novu-postman](https://github.com/novuhq/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](https://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](https://dashboard.novu.co/api-keys) page.

You can also import the collection directly from the raw JSON file: [novu_api_postman_collection.json](https://raw.githubusercontent.com/novuhq/novu-postman/refs/heads/main/postman/novu_api_postman_collection.json).

## 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, create a subscriber, or create an agent using the REST API or an SDK. Start with [Trigger event](/api-reference/events/trigger-event), [Create a subscriber](/api-reference/subscribers/create-a-subscriber), or [Create an agent](/api-reference/agents/create-an-agent).
  </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>