Manage contexts

Novu lets you manage contexts through the Novu dashboard, or the Novu API. This lets you create, view, update, and delete context entities to suit your application’s needs.

You can pass a maximum of five contexts per workflow trigger and the serialized data object for each context is limited to 64KB.

Context object schema

When defining contexts, Novu supports multiple formats per key-value pair that let you store and reference metadata relevant to your workflows and templates. Each context consists of:

A type (for example, tenant, app, or region).
An id that uniquely identifies the specific context instance.
An optional data object that holds additional properties available to your templates.

Supported data formats include:

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: "user123" },
  payload: { userName: "John" },
  context: {
    // Simple string format
    tenant: "acme-corp",
    // Rich object format (ID only)
    app: { id: "jira" },
    // Rich object format (ID + data)
    region: {
      id: "us-east",
      data: {
        name: "US East",
        timezone: "America/New_York",
        currency: "USD",
      },
    },
  },
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "user123"},
        payload={"userName": "John"},
        context={
            "tenant": "acme-corp",
            "app": {"id": "jira"},
            "region": {
                "id": "us-east",
                "data": {
                    "name": "US East",
                    "timezone": "America/New_York",
                    "currency": "USD",
                },
            },
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "user123",
    }),
    Payload: map[string]any{
        "userName": "John",
    },
    Context: map[string]any{
        "tenant": "acme-corp",
        "app": map[string]any{
            "id": "jira",
        },
        "region": map[string]any{
            "id": "us-east",
            "data": map[string]any{
                "name":     "US East",
                "timezone": "America/New_York",
                "currency": "USD",
            },
        },
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'user123'),
        payload: [
            'userName' => 'John',
        ],
        context: [
            'tenant' => 'acme-corp',
            'app' => ['id' => 'jira'],
            'region' => [
                'id' => 'us-east',
                'data' => [
                    'name' => 'US East',
                    'timezone' => 'America/New_York',
                    'currency' => 'USD',
                ],
            ],
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() {
        SubscriberId = "user123",
    }),
    Payload = new Dictionary<string, object>() {
        { "userName", "John" },
    },
    Context = new Dictionary<string, object>() {
        { "tenant", "acme-corp" },
        { "app", new Dictionary<string, object>() { { "id", "jira" } } },
        { "region", new Dictionary<string, object>() {
            { "id", "us-east" },
            { "data", new Dictionary<string, object>() {
                { "name", "US East" },
                { "timezone", "America/New_York" },
                { "currency", "USD" },
            } },
        } },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("user123")
            .build()))
        .payload(Map.of("userName", "John"))
        .context(Map.ofEntries(
            Map.entry("tenant", TriggerEventRequestDtoContextUnion.of("acme-corp")),
            Map.entry("app", TriggerEventRequestDtoContextUnion.of(
                TriggerEventRequestDtoContext2.builder()
                    .id("jira")
                    .build())),
            Map.entry("region", TriggerEventRequestDtoContextUnion.of(
                TriggerEventRequestDtoContext2.builder()
                    .id("us-east")
                    .data(Map.ofEntries(
                        Map.entry("name", "US East"),
                        Map.entry("timezone", "America/New_York"),
                        Map.entry("currency", "USD")))
                    .build()))))
        .build())
    .call();

curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": { "subscriberId": "user123" },
    "payload": { "userName": "John" },
    "context": {
        "tenant": "acme-corp",
        "app": { "id": "jira" },
        "region": {
            "id": "us-east",
            "data": {
                "name": "US East",
                "timezone": "America/New_York",
                "currency": "USD"
            }
        }
    }
}'

Create a Context

You can create a new context via the Novu dashboard or API when you want to register reusable metadata. After creation, this context becomes available to all workflows and templates within your environment.

Create a context via dashboard

Use the dashboard to manually define contexts that represent key business entities.

Open the Novu Dashboard.

Open Contexts

In the Novu dashboard sidebar, click Contexts.

Create context

Complete the fields

Identifier: A unique identifier within that type (for example, acme-corp).
Context type: A category such as tenant, app, or region.
Custom data (JSON): An optional JSON object that contains metadata, such as branding, plan, or region details.

Save the context

Review the fields, then click Create context to save.

Create a context via API

Novu provides an API to create a context. If a context with the same type:id combination already exists, then the request will fail.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.contexts.create({
  type: "tenant",
  id: "acme-corp",
  data: {
    name: "Acme Corporation",
    plan: "enterprise",
  },
});

import os
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.contexts.create(create_context_request_dto={
        "type": "tenant",
        "id": "acme-corp",
        "data": {
            "name": "Acme Corporation",
            "plan": "enterprise",
        },
    })

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Contexts.Create(context.Background(), components.CreateContextRequestDto{
    Type: "tenant",
    ID:   "acme-corp",
    Data: map[string]any{
        "name": "Acme Corporation",
        "plan": "enterprise",
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->contexts->create(
    createContextRequestDto: new Components\CreateContextRequestDto(
        type: 'tenant',
        id: 'acme-corp',
        data: [
            'name' => 'Acme Corporation',
            'plan' => 'enterprise',
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.Contexts.CreateAsync(createContextRequestDto: new CreateContextRequestDto() {
    Type = "tenant",
    Id = "acme-corp",
    Data = new Dictionary<string, object>() {
        { "name", "Acme Corporation" },
        { "plan", "enterprise" },
    },
});

import co.novu.Novu;
import co.novu.models.components.CreateContextRequestDto;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.contexts().create()
    .body(CreateContextRequestDto.builder()
        .type("tenant")
        .id("acme-corp")
        .data(Map.ofEntries(
            Map.entry("name", "Acme Corporation"),
            Map.entry("plan", "enterprise")))
        .build())
    .call();

curl -L -g -X POST 'https://api.novu.co/v2/contexts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "type": "tenant",
    "id": "acme-corp",
    "data": {
        "name": "Acme Corporation",
        "plan": "enterprise"
    }
}'

Create a context via API (Just-in-time)

Contexts can also be created automatically when you trigger a workflow that includes a new context object. If the specified type:id doesn’t exist, then Novu automatically creates it before running the workflow.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: "[email protected]" },
  payload: { userName: "John" },
  context: {
    tenant: "acme-corp", // Created automatically if it doesn't exist
    app: "jira",
  },
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "[email protected]"},
        payload={"userName": "John"},
        context={
            "tenant": "acme-corp",
            "app": "jira",
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "[email protected]",
    }),
    Payload: map[string]any{
        "userName": "John",
    },
    Context: map[string]any{
        "tenant": "acme-corp",
        "app":    "jira",
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: '[email protected]'),
        payload: ['userName' => 'John'],
        context: [
            'tenant' => 'acme-corp',
            'app' => 'jira',
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() {
        SubscriberId = "[email protected]",
    }),
    Payload = new Dictionary<string, object>() {
        { "userName", "John" },
    },
    Context = new Dictionary<string, object>() {
        { "tenant", "acme-corp" },
        { "app", "jira" },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("[email protected]")
            .build()))
        .payload(Map.of("userName", "John"))
        .context(Map.ofEntries(
            Map.entry("tenant", TriggerEventRequestDtoContextUnion.of("acme-corp")),
            Map.entry("app", TriggerEventRequestDtoContextUnion.of("jira"))))
        .build())
    .call();

curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": { "subscriberId": "[email protected]" },
    "payload": { "userName": "John" },
    "context": {
        "tenant": "acme-corp",
        "app": "jira"
    }
}'

If a matching context already exists and you pass only a string identifier, Novu reuses it without changing stored data. If you pass a rich object with a data field, Novu replaces the stored data with the values from your trigger request. This upsert behavior applies to workflow triggers only. Inbox and other subscriber-facing APIs find or create contexts but do not update existing data.

Update a context

You can update a context’s data payload at any time. The context type and id remain immutable. You can update existing context data through the dashboard, API, or by passing inline data on a workflow trigger.

Update a context via dashboard

Open the Novu Dashboard.

Open Contexts

In the Novu dashboard sidebar, click Contexts.

Select the context

Modify the data object

Edit the JSON payload for this context in the editor.

Save changes

Your updates apply immediately to future workflow triggers.

Update a context via API

Novu provides an API to update an existing context. The data object is replaced entirely during updates (not merged). Include all fields you want to retain.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.contexts.update({
  type: "tenant",
  id: "acme-corp",
  updateContextRequestDto: {
    data: {
      plan: "premium",
      region: "us-east",
    },
  },
});

import os
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.contexts.update(
        type_="tenant",
        id="acme-corp",
        update_context_request_dto={
            "data": {
                "plan": "premium",
                "region": "us-east",
            },
        },
    )

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Contexts.Update(context.Background(), "acme-corp", "tenant", components.UpdateContextRequestDto{
    Data: map[string]any{
        "plan":   "premium",
        "region": "us-east",
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->contexts->update(
    id: 'acme-corp',
    type: 'tenant',
    updateContextRequestDto: new Components\UpdateContextRequestDto(
        data: [
            'plan' => 'premium',
            'region' => 'us-east',
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.Contexts.UpdateAsync(
    id: "acme-corp",
    type: "tenant",
    updateContextRequestDto: new UpdateContextRequestDto() {
        Data = new Dictionary<string, object>() {
            { "plan", "premium" },
            { "region", "us-east" },
        },
    }
);

import co.novu.Novu;
import co.novu.models.components.UpdateContextRequestDto;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.contexts().update()
    .id("acme-corp")
    .type("tenant")
    .body(UpdateContextRequestDto.builder()
        .data(Map.ofEntries(
            Map.entry("plan", "premium"),
            Map.entry("region", "us-east")))
        .build())
    .call();

curl -L -g -X PATCH 'https://api.novu.co/v2/contexts/tenant/acme-corp' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "data": {
        "plan": "premium",
        "region": "us-east"
    }
}'

Retrieve a single context

You can retrieve a context to verify its data, confirm its creation, or inspect the metadata it holds.

Retrieve a context via dashboard

Open the Novu Dashboard.

Open Contexts

In the Novu dashboard sidebar, click Contexts.

View context details

Click any context entry to see its details.

Retrieve a context via API

Novu provides an API to retrieve a single, specific context by providing its type and id in the URL.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.contexts.retrieve("tenant", "acme-corp");

import os
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.contexts.retrieve(type_="tenant", id="acme-corp")

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Contexts.Retrieve(context.Background(), "acme-corp", "tenant", nil)

use novu;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->contexts->retrieve(
    id: 'acme-corp',
    type: 'tenant',
);

using Novu;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.Contexts.RetrieveAsync(
    id: "acme-corp",
    type: "tenant"
);

import co.novu.Novu;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.contexts().get()
    .id("acme-corp")
    .type("tenant")
    .call();

curl -L -g -X GET 'https://api.novu.co/v2/contexts/tenant/acme-corp' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>'

List or search for contexts

You can list all contexts in your environment or search for specific ones by context type or ID.

List or search for contexts via dashboard

Open the Novu Dashboard.

Open Contexts

In the Novu dashboard sidebar, click Contexts.

Search contexts

Use the search bar to filter by context type or ID.

List or search for contexts via API

Novu provides an API that lists or searches available contexts. Use pagination and search parameters to retrieve subsets efficiently.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.contexts.list({ search: "acme" });

import os
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.contexts.list(request={"search": "acme"})

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/operations"
)

search := "acme"
s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Contexts.List(context.Background(), operations.ContextsControllerListContextsRequest{
    Search: &search,
}, nil)

use novu;
use novu\Models\Operations;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->contexts->list(
    request: new Operations\ContextsControllerListContextsRequest(
        search: 'acme',
    ),
);

using Novu;
using Novu.Models.Requests;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.Contexts.ListAsync(new ContextsControllerListContextsRequest() {
    Search = "acme",
});

import co.novu.Novu;
import co.novu.models.operations.ContextsControllerListContextsRequest;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.contexts().list()
    .request(ContextsControllerListContextsRequest.builder()
        .search("acme")
        .build())
    .call();

curl -L -g -X GET 'https://api.novu.co/v2/contexts?search=acme' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>'

Delete a context

Delete a context if it’s no longer needed. This action permanently removes the context from your Novu environment.

Deleting a context cannot be undone. Ensure the context is no longer required by any active or historical workflows you might need to analyze.

Delete a context via dashboard

Open the Novu Dashboard.

Open Contexts

In the Novu dashboard sidebar, click Contexts.

Select the context to remove

Click the context or the … icon on the row you want to remove.

Confirm deletion

A confirmation menu will appear.

Delete the context

Select Delete context to confirm removal.

Delete a context via API

Novu provides an API that you can use to delete a context. Once deleted, the context will no longer be available for use in new workflow executions.

import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>" });

await novu.contexts.delete("tenant", "acme-corp");

import os
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.contexts.delete(type_="tenant", id="acme-corp")

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Contexts.Delete(context.Background(), "acme-corp", "tenant", nil)

use novu;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->contexts->delete(
    id: 'acme-corp',
    type: 'tenant',
);

using Novu;

var sdk = new NovuSDK(secretKey: "<YOUR_SECRET_KEY_HERE>");

await sdk.Contexts.DeleteAsync(
    id: "acme-corp",
    type: "tenant"
);

import co.novu.Novu;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.contexts().delete()
    .id("acme-corp")
    .type("tenant")
    .call();

curl -L -g -X DELETE 'https://api.novu.co/v2/contexts/tenant/acme-corp' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>'

Getting Started

Integrate <Inbox />

Integrate <Subscription />

Build a Workflow

Integrate Channels Providers

SDKs

Developer

Account

Build with AI

Additional Resources

Manage contexts

Context object schema

Create a Context

Create a context via dashboard

Create a context via API

Create a context via API (Just-in-time)

Update a context

Update a context via dashboard

Update a context via API

Retrieve a single context

Retrieve a context via dashboard

Retrieve a context via API

List or search for contexts

List or search for contexts via dashboard

List or search for contexts via API

Delete a context

Delete a context via dashboard

Delete a context via API

​Context object schema

​Create a Context

​Create a context via dashboard

​Create a context via API

​Create a context via API (Just-in-time)

​Update a context

​Update a context via dashboard

​Update a context via API

​Retrieve a single context

​Retrieve a context via dashboard

​Retrieve a context via API

​List or search for contexts

​List or search for contexts via dashboard

​List or search for contexts via API

​Delete a context

​Delete a context via dashboard

​Delete a context via API

Context object schema

Create a Context

Create a context via dashboard

Create a context via API

Create a context via API (Just-in-time)

Update a context

Update a context via dashboard

Update a context via API

Retrieve a single context

Retrieve a context via dashboard

Retrieve a context via API

List or search for contexts

List or search for contexts via dashboard

List or search for contexts via API

Delete a context

Delete a context via dashboard

Delete a context via API