> ## Documentation Index
> Fetch the complete documentation index at: https://novu-c5de82d9-docs-homepage-redesign.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Novu REST API Reference

> Manage subscribers, trigger workflows, configure integrations, and operate your notification infrastructure with the Novu REST API.

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>