Novu

Novu Translations API

Used to localize your notifications to different languages.

Documentation GitHub OpenAPI

Operations 9

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /v2/translations/upload Upload locale files for a workflow · Novu Upload Translation Files #

Ask an LLM

“How do I upload JSON translation files for one workflow?”

“What should my translation files be named so the locale is recognized?”

Tell an agent

Upload translation files {files} for {resourceType} {resourceId}.

Attach these per-locale JSON files to workflow {resourceId} as a {resourceType}: {files}.

POST /v2/translations Create or update a translation · Novu Create a Translation #

Ask an LLM

“How do I add a translation for one locale to a workflow?”

“What happens if a translation for that locale already exists?”

Tell an agent

Create the {locale} translation for {resourceType} {resourceId} with content {content}.

Save {content} as the {locale} strings for workflow {resourceId} of type {resourceType}.

GET /v2/translations/master-json Export all translations as master JSON · Novu Retrieve Master Translations JSON #

Ask an LLM

“Can I export every workflow's translations for a locale in one JSON file?”

“What does the master translations JSON look like for a given language?”

Tell an agent

Export the master translations JSON for locale {locale}.

Download all translations in master JSON format.

POST /v2/translations/master-json Import translations from master JSON · Novu Import Master Translations JSON #

Ask an LLM

“How do I import translations for many workflows at once from a JSON body?”

“Can I bulk load one locale's strings across all workflows?”

Tell an agent

Import master JSON {masterJson} for locale {locale}.

Load these {locale} translations for multiple workflows from master JSON {masterJson}.

POST /v2/translations/master-json/upload Upload a master translations file · Novu Upload Master Translations JSON File #

Ask an LLM

“Can I upload a master translations file and have the locale detected from its filename?”

“Which endpoint accepts a master JSON file upload rather than a JSON body?”

Tell an agent

Upload master translations file {file}.

Upload {file} as a master JSON file and detect the locale from its name.

GET /v2/translations/group/{resourceType}/{resourceId} Get a translation group · Novu Retrieve a Translation Group #

Ask an LLM

“Which locales have translations for a specific workflow or layout?”

“How do I get the whole translation group for one resource?”

Tell an agent

Show the translation group for {resourceType} {resourceId}.

List every locale translated for the {resourceType} {resourceId}.

GET /v2/translations/{resourceType}/{resourceId}/{locale} Get one locale's translation · Novu Retrieve a Translation #

Ask an LLM

“How do I read the French strings for a particular workflow?”

“Can I fetch a single translation by resource and locale?”

Tell an agent

Get the {locale} translation for {resourceType} {resourceId}.

Show the {locale} strings of {resourceType} {resourceId}.

DELETE /v2/translations/{resourceType}/{resourceId}/{locale} Delete one locale's translation · Novu Delete a Translation #

Ask an LLM

“How do I remove just one language from a workflow's translations?”

“Can I delete a single locale without removing the others?”

Tell an agent destructive · confirm first

Delete the {locale} translation for {resourceType} {resourceId}.

Remove only locale {locale} from {resourceType} {resourceId}.

DELETE /v2/translations/{resourceType}/{resourceId} Delete all translations for a resource · Novu Delete a Translation Group #

Ask an LLM

“How do I wipe every translation for a workflow in one go?”

“Can I delete a whole translation group along with all its locales?”

Tell an agent destructive · confirm first

Delete the entire translation group for {resourceType} {resourceId}.

Remove all locales translated for {resourceType} {resourceId}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/novu:novu-translations-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Novu Translations API
  description: Novu REST API. Please see https://docs.novu.co/api-reference for more details.
  version: 3.15.0
  contact:
    name: Novu Support
    url: https://discord.gg/novu
    email: support@novu.co
  termsOfService: https://novu.co/terms
  license:
    name: MIT
    url: https://opensource.org/license/mit
servers:
- url: https://api.novu.co
- url: https://eu.api.novu.co
security:
- secretKey: []
tags:
- name: Translations
  description: Used to localize your notifications to different languages.
  externalDocs:
    url: https://docs.novu.co/platform/workflow/advanced-features/translations
paths:
  /v2/translations/upload:
    post:
      operationId: TranslationController_uploadTranslationFiles
      x-speakeasy-name-override: upload
      summary: Novu Upload Translation Files
      description: Upload one or more JSON translation files for a specific workflow. Files name must match the locale, e.g. en_US.json. Supports both "files" and "files[]" field names for backwards compatibility.
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                resourceId:
                  type: string
                  description: The resource ID to associate localizations with. Accepts identifier or slug format
                  example: welcome-email
                resourceType:
                  type: string
                  enum:
                  - workflow
                  - layout
                  description: The resource type to associate localizations with
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: One or more JSON translation files. Filenames must match locale format (e.g., en_US.json, fr_FR.json). Field name can be "files" or "files[]".
              required:
              - resourceId
              - resourceType
              - files
      responses:
        '200':
          description: Upload results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadTranslationsResponseDto'
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
  /v2/translations:
    post:
      operationId: TranslationController_createTranslationEndpoint
      x-speakeasy-name-override: create
      summary: Novu Create a Translation
      description: Create a translation for a specific workflow and locale, if the translation already exists, it will be updated
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTranslationRequestDto'
      responses:
        '200':
          description: Translation created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationResponseDto'
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
  /v2/translations/master-json:
    get:
      operationId: TranslationController_getMasterJsonEndpoint
      x-speakeasy-name-override: retrieve
      x-speakeasy-group: Translations.master
      summary: Novu Retrieve Master Translations JSON
      description: Retrieve all translations for a locale in master JSON format organized by resourceId (workflowId)
      parameters:
      - name: locale
        required: false
        in: query
        description: Locale to export. If not provided, exports organization default locale
        example: en_US
        schema:
          type: string
      responses:
        '200':
          description: Master translations JSON retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMasterJsonResponseDto'
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
    post:
      operationId: TranslationController_importMasterJsonEndpoint
      x-speakeasy-name-override: import
      x-speakeasy-group: Translations.Master
      summary: Novu Import Master Translations JSON
      description: Import translations for multiple workflows from master JSON format for a specific locale
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportMasterJsonRequestDto'
      responses:
        '200':
          description: Master translations imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportMasterJsonResponseDto'
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
  /v2/translations/master-json/upload:
    post:
      operationId: TranslationController_uploadMasterJsonEndpoint
      x-speakeasy-name-override: upload
      x-speakeasy-group: Translations.Master
      summary: Novu Upload Master Translations JSON File
      description: Upload a master JSON file containing translations for multiple workflows. Locale is automatically detected from filename (e.g., en_US.json)
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Master JSON file with locale as filename (e.g., en_US.json)
              required:
              - file
      responses:
        '200':
          description: Master translations uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportMasterJsonResponseDto'
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
  /v2/translations/group/{resourceType}/{resourceId}:
    get:
      operationId: TranslationController_getTranslationGroupEndpoint
      x-speakeasy-name-override: retrieve
      x-speakeasy-group: Translations.Groups
      summary: Novu Retrieve a Translation Group
      description: Retrieves a single translation group by resource type (workflow, layout) and resource ID (workflowId, layoutId)
      parameters:
      - name: resourceType
        required: true
        in: path
        description: Resource type
        example: workflow
        schema:
          enum:
          - workflow
          - layout
          type: string
      - name: resourceId
        required: true
        in: path
        description: Resource ID
        example: welcome-email
        schema:
          type: string
      responses:
        '200':
          description: Translation group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationGroupDto'
        '404':
          description: Translation group not found
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
  /v2/translations/{resourceType}/{resourceId}/{locale}:
    get:
      operationId: TranslationController_getSingleTranslation
      x-speakeasy-name-override: retrieve
      summary: Novu Retrieve a Translation
      description: Retrieve a specific translation by resource type, resource ID and locale
      parameters:
      - name: resourceType
        required: true
        in: path
        description: Resource type
        schema:
          enum:
          - workflow
          - layout
          type: string
      - name: resourceId
        required: true
        in: path
        description: Resource ID
        example: welcome-email
        schema:
          type: string
      - name: locale
        required: true
        in: path
        description: Locale code
        example: en_US
        schema:
          type: string
      responses:
        '200':
          description: Translation found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationResponseDto'
        '404':
          description: Translation not found
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
    delete:
      operationId: TranslationController_deleteTranslationEndpoint
      x-speakeasy-name-override: delete
      summary: Novu Delete a Translation
      description: Delete a specific translation by resource type, resource ID and locale
      parameters:
      - name: resourceType
        required: true
        in: path
        description: Resource type
        schema:
          enum:
          - workflow
          - layout
          type: string
      - name: resourceId
        required: true
        in: path
        description: Resource ID
        schema:
          type: string
      - name: locale
        required: true
        in: path
        description: Locale code
        schema:
          type: string
      responses:
        '204':
          description: Translation deleted successfully
        '404':
          description: Translation not found
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
  /v2/translations/{resourceType}/{resourceId}:
    delete:
      operationId: TranslationController_deleteTranslationGroupEndpoint
      x-speakeasy-name-override: delete
      x-speakeasy-group: Translations.Groups
      summary: Novu Delete a Translation Group
      description: Delete an entire translation group and all its translations
      parameters:
      - name: resourceType
        required: true
        in: path
        description: Resource type
        example: workflow
        schema:
          enum:
          - workflow
          - layout
          type: string
      - name: resourceId
        required: true
        in: path
        description: Resource ID
        example: welcome-email
        schema:
          type: string
      responses:
        '204':
          description: Translation group deleted successfully
        '404':
          description: Translation group not found
      tags:
      - Translations
      security:
      - secretKey: []
      - secretKey: []
components:
  schemas:
    TranslationGroupDto:
      type: object
      properties:
        resourceId:
          type: string
          description: Resource identifier (slugified ID)
          example: welcome-email
        resourceType:
          type: string
          description: Resource type
          example: workflow
          enum:
          - workflow
          - layout
        resourceName:
          type: string
          description: Resource name (e.g., workflow name)
          example: Welcome Email Workflow
        locales:
          description: Array of available locales for this resource
          example:
          - en_US
          - es_ES
          - fr_FR
          type: array
          items:
            type: string
        outdatedLocales:
          description: Locales that are outdated compared to the default locale (only present when there are outdated locales)
          example:
          - es_ES
          - fr_FR
          type: array
          items:
            type: string
        createdAt:
          type: string
          description: Creation timestamp
          example: '2024-01-01T00:00:00.000Z'
        updatedAt:
          type: string
          description: Last update timestamp
          example: '2024-01-01T00:00:00.000Z'
      required:
      - resourceId
      - resourceType
      - resourceName
      - locales
      - createdAt
      - updatedAt
    CreateTranslationRequestDto:
      type: object
      properties:
        resourceId:
          type: string
          description: The resource ID to associate translation with. Accepts identifier or slug format
          example: welcome-email
        resourceType:
          type: string
          description: The resource type to associate translation with
          enum:
          - workflow
          - layout
        locale:
          type: string
          description: Locale code (e.g., en_US, es_ES)
          example: en_US
        content:
          type: object
          description: Translation content as JSON object
          example:
            welcome.title: Welcome
            welcome.message: Hello there!
          additionalProperties: true
      required:
      - resourceId
      - resourceType
      - locale
      - content
    ImportMasterJsonResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Overall success status of the import operation
          example: true
        message:
          type: string
          description: Human-readable message describing the import result
          example: 'Successfully imported translations for 2 resources: welcome-email, password-reset'
        successful:
          description: List of resource IDs that were successfully imported
          example:
          - welcome-email
          - password-reset
          type: array
          items:
            type: string
        failed:
          description: List of resource IDs that failed to import
          example:
          - missing-workflow
          type: array
          items:
            type: string
      required:
      - success
      - message
    GetMasterJsonResponseDto:
      type: object
      properties:
        workflows:
          type: object
          description: All translations for given locale organized by workflow identifier
          example:
            welcome-email:
              welcome.title: Welcome to our platform
              welcome.message: Hello there!
            password-reset:
              reset.title: Reset your password
              reset.message: Click the link to reset
          additionalProperties: true
        layouts:
          type: object
          description: All translations for given locale organized by layout identifier
          example:
            default-layout:
              layout.title: Default layout
              layout.message: Hello there!
          additionalProperties: true
      required:
      - workflows
      - layouts
    UploadTranslationsResponseDto:
      type: object
      properties:
        totalFiles:
          type: number
          description: Total number of files processed
          example: 3
        successfulUploads:
          type: number
          description: Number of files successfully uploaded
          example: 2
        failedUploads:
          type: number
          description: Number of files that failed to upload
          example: 1
        errors:
          description: List of error messages for failed uploads
          example:
          - 'Invalid JSON in file: es-ES.json'
          type: array
          items:
            type: string
      required:
      - totalFiles
      - successfulUploads
      - failedUploads
      - errors
    ImportMasterJsonRequestDto:
      type: object
      properties:
        locale:
          type: string
          description: The locale for which translations are being imported
          example: en_US
        masterJson:
          type: object
          description: Master JSON object containing all translations organized by workflow identifier
          example:
            workflows:
              welcome-email:
                welcome.title: Welcome to our platform
                welcome.message: Hello there!
              password-reset:
                reset.title: Reset your password
                reset.message: Click the link to reset
          additionalProperties: true
      required:
      - locale
      - masterJson
    TranslationResponseDto:
      type: object
      properties:
        resourceId:
          type: string
          description: Resource identifier
          example: welcome-email
        resourceType:
          type: string
          description: Resource type
          example: workflow
          enum:
          - workflow
          - layout
        locale:
          type: string
          description: Locale code
          example: en_US
        content:
          type: object
          description: Translation content as JSON object
          example:
            welcome.title: Welcome
            welcome.message: Hello there!
          additionalProperties: true
        createdAt:
          type: string
          description: Creation timestamp
          example: '2024-01-01T00:00:00.000Z'
        updatedAt:
          type: string
          description: Last update timestamp
          example: '2024-01-01T00:00:00.000Z'
      required:
      - resourceId
      - resourceType
      - locale
      - content
      - createdAt
      - updatedAt
  securitySchemes:
    secretKey:
      type: apiKey
      name: Authorization
      in: header
      description: 'API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".'
      x-speakeasy-example: YOUR_SECRET_KEY_HERE
externalDocs:
  description: Novu Documentation
  url: https://docs.novu.co
x-provenance:
  method: harvested
  publisher: Novu
  source: https://api.novu.co/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)

Novu Translations API

Operations 9

Documentation

Specifications

Code Examples

Schemas & Data

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification