Nash Notifications API

openapi: 3.2.0
info:
  title: Nash AI Functions Notifications API
  version: 1.0.0
  description: LLM-backed domain tools
servers:
- url: https://api.sandbox.usenash.com
  description: Sandbox API
- url: https://api.sandbox.ap-southeast-2.usenash.com
  description: Sandbox API (Australia)
- url: https://api.usenash.com
  description: Production API
- url: https://api.ap-southeast-2.usenash.com
  description: Production API (Australia)
tags:
- name: Notifications
  description: Notifications
  x-nash-topic: config
paths:
  /v1/notification-triggers:
    get:
      tags:
      - Notifications
      summary: List Notification Triggers
      description: List notification triggers configured on the authenticated organization. Use the `Nash-Org-Id` header to scope the request to a specific org (e.g. a child org).
      operationId: list_notification_triggers_v1_notification_triggers_get
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotificationTriggersResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
    post:
      tags:
      - Notifications
      summary: Create Notification Trigger
      description: 'Create a notification trigger on the authenticated organization. The request body is a discriminated union on `type`: each trigger type (see GET /v1/notification-triggers/templates) has its own typed `parameters` shape in the OpenAPI schema. An invalid `type` returns a 400 listing all valid types. Use the `Nash-Org-Id` header to scope creation to a specific org (e.g. a child org).'
      operationId: create_notification_trigger_v1_notification_triggers_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNotificationTriggerInput'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTriggerResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/notification-triggers/catalog:
    get:
      tags:
      - Notifications
      summary: Get Notification Trigger Catalog
      description: The full notification-trigger catalog. Each entry describes a trigger's `type` slug, human `title`, the `value` used to subscribe automations, the `entityType` (route/delivery/task/order/activity), its `statuses` vocabulary, the JSON Schema of its create `parameters`, and the `supportedFilters` / `supportedActions`. The shared `filterCriteria` (dispatch strategies, contracts, zones, metadata conditions) and `actions` are described once at the top level. Designed for agents and humans to discover what can be automated and how.
      operationId: get_notification_trigger_catalog_v1_notification_triggers_catalog_get
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTriggerCatalogResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/notification-triggers/templates:
    get:
      tags:
      - Notifications
      summary: List Notification Trigger Templates
      description: List pre-defined notification trigger templates. Each template has a `type` slug (e.g. 'tasks_attempts_exhausted') and a human-readable `title` (e.g. 'Tasks Attempts Exhausted'). Use the `type` when creating a trigger via POST /v1/notification-triggers.
      operationId: list_notification_trigger_templates_v1_notification_triggers_templates_get
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotificationTriggerTemplatesResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/notification/{id}/trigger:
    post:
      tags:
      - Notifications
      summary: Trigger Notification
      description: Manually trigger a notification for a specific delivery event. The notification is sent using the configured channel and template for the trigger.
      operationId: trigger_notification_v1_notification__string_id__trigger_post
      parameters:
      - name: id
        in: path
        description: Notification trigger ID
        required: true
        schema:
          title: Id
          type: string
          description: Notification trigger ID
          example: ntf_123
        example: ntf_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerNotificationInputSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerNotificationOutputSerializer'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
  /v1/organization-management/notifications/deny-list:
    get:
      tags:
      - Notifications
      summary: Get contacts in the deny list.
      description: Retrieve all contacts in the organization's notification deny list. Contacts on this list will not receive delivery notifications.
      operationId: _get_deny_list_v1_organization_management_notifications_deny_list_get
      parameters:
      - name: orgId
        in: query
        description: The organization id to get the deny list for.
        required: false
        schema:
          title: Orgid
          anyOf:
          - type: string
          - type: 'null'
          description: The organization id to get the deny list for.
          default: null
      - name: page
        in: query
        description: Use this parameter to show more pages of results (page starts at 0)..
        required: false
        schema:
          title: Page
          type: integer
          description: Use this parameter to show more pages of results (page starts at 0)..
          default: 0
      - name: pageSize
        in: query
        description: The number of items to return per page.
        required: false
        schema:
          title: Pagesize
          type: integer
          description: The number of items to return per page.
          default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DenyListResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
    post:
      tags:
      - Notifications
      summary: Add a contact to the deny list.
      description: Add a contact (phone number or email) to the organization's notification deny list. The contact will no longer receive delivery notifications.
      operationId: _add_contact_to_deny_list_v1_organization_management_notifications_deny_list_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddContactToDenyListSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DenyList'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
    delete:
      tags:
      - Notifications
      summary: Remove a contact from the deny list.
      description: Remove a contact from the organization's notification deny list. The contact will resume receiving delivery notifications.
      operationId: _remove_contact_from_deny_list_v1_organization_management_notifications_deny_list_delete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddContactToDenyListSerializer'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
components:
  schemas:
    CreateDriverGeolocationTrigger:
      title: CreateDriverGeolocationTrigger
      required:
      - name
      - notificationGroupIds
      - type
      - parameters
      type: object
      properties:
        name:
          title: Name
          minLength: 1
          type: string
          description: Human-readable name for this trigger instance.
        notificationGroupIds:
          title: Notificationgroupids
          type: array
          items:
            type: string
          description: IDs of the notification groups that will receive notifications when this trigger fires.
        description:
          title: Description
          anyOf:
          - type: string
          - type: 'null'
          description: Optional description of the trigger.
          default: null
        enabled:
          title: Enabled
          type: boolean
          description: Whether the trigger is enabled on creation. Defaults to true.
          default: true
        message:
          title: Message
          anyOf:
          - type: string
          - type: 'null'
          description: Optional custom message body.
          default: null
        flag:
          title: Flag
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether firing this trigger should also flag the job for operator attention.
          default: null
        autoResolveFlag:
          title: Autoresolveflag
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, a flag raised by this trigger resolves automatically when the flag condition clears.
          default: null
        optionsGroupIds:
          title: Optionsgroupids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Options groups that scope when this trigger applies.
          default: null
        contractIds:
          title: Contractids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Contract IDs that scope when this trigger applies.
          default: null
        isInternal:
          title: Isinternal
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the trigger is for internal use only (not exposed to customers).
          default: null
        zoneIds:
          title: Zoneids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Zone IDs that scope when this trigger applies (separate from zone-geolocation parameters).
          default: null
        customEventName:
          title: Customeventname
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: For triggers that emit a custom event when fired, the name of that event.
          default: null
        conditionalLogic:
          title: Conditionallogic
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: Optional AND/OR conditional tree that gates when the trigger fires. Shape mirrors the Zod ConditionalStatement schema in nash-ui; currently passed through as JSON. A follow-up will type this explicitly.
          default: null
        type:
          title: Type
          type: string
          const: driver_geolocation
        parameters:
          title: Parameters
          oneOf:
          - $ref: '#/components/schemas/DriverGeolocationWithinParams'
          - $ref: '#/components/schemas/DriverGeolocationGreaterThanParams'
          - $ref: '#/components/schemas/DriverGeolocationStoppedForParams'
          discriminator:
            propertyName: condition
            mapping:
              greater_than: '#/components/schemas/DriverGeolocationGreaterThanParams'
              stopped_for: '#/components/schemas/DriverGeolocationStoppedForParams'
              within: '#/components/schemas/DriverGeolocationWithinParams'
    DeliveryWindowBookedTimeoutParams:
      title: DeliveryWindowBookedTimeoutParams
      required:
      - timeoutMinutes
      type: object
      properties:
        timeoutMinutes:
          title: Timeoutminutes
          minimum: 1.0
          type: integer
    CreateOrderModifiedTrigger:
      title: CreateOrderModifiedTrigger
      required:
      - name
      - notificationGroupIds
      - type
      type: object
      properties:
        name:
          title: Name
          minLength: 1
          type: string
          description: Human-readable name for this trigger instance.
        notificationGroupIds:
          title: Notificationgroupids
          type: array
          items:
            type: string
          description: IDs of the notification groups that will receive notifications when this trigger fires.
        description:
          title: Description
          anyOf:
          - type: string
          - type: 'null'
          description: Optional description of the trigger.
          default: null
        enabled:
          title: Enabled
          type: boolean
          description: Whether the trigger is enabled on creation. Defaults to true.
          default: true
        message:
          title: Message
          anyOf:
          - type: string
          - type: 'null'
          description: Optional custom message body.
          default: null
        flag:
          title: Flag
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether firing this trigger should also flag the job for operator attention.
          default: null
        autoResolveFlag:
          title: Autoresolveflag
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, a flag raised by this trigger resolves automatically when the flag condition clears.
          default: null
        optionsGroupIds:
          title: Optionsgroupids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Options groups that scope when this trigger applies.
          default: null
        contractIds:
          title: Contractids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Contract IDs that scope when this trigger applies.
          default: null
        isInternal:
          title: Isinternal
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the trigger is for internal use only (not exposed to customers).
          default: null
        zoneIds:
          title: Zoneids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Zone IDs that scope when this trigger applies (separate from zone-geolocation parameters).
          default: null
        customEventName:
          title: Customeventname
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: For triggers that emit a custom event when fired, the name of that event.
          default: null
        conditionalLogic:
          title: Conditionallogic
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: Optional AND/OR conditional tree that gates when the trigger fires. Shape mirrors the Zod ConditionalStatement schema in nash-ui; currently passed through as JSON. A follow-up will type this explicitly.
          default: null
        type:
          title: Type
          type: string
          const: order_modified
        parameters:
          anyOf:
          - $ref: '#/components/schemas/OrderModifiedParams'
          - type: 'null'
          default: null
    ActivityAction:
      title: ActivityAction
      enum:
      - act_dispatch_optimized_orders
      - act_optimize_orders
      - act_optimize_routes
      - act_manifest_orders
      - act_orders_bulk_operation
      - act_orders_bulk_action
      - act_process_csv_upload
      - act_dispatch_routes
      - act_dispatch_delivery_window_orders
      - act_dispatch_and_manifest_batch
      - act_dispatch_and_manifest_chunk
      - generate_refund_ai_analysis_report
      - generate_customer_feedback_report
      - generate_report
      type: string
    CreateApiBasedTrigger:
      title: CreateApiBasedTrigger
      required:
      - name
      - notificationGroupIds
      - type
      type: object
      properties:
        name:
          title: Name
          minLength: 1
          type: string
          description: Human-readable name for this trigger instance.
        notificationGroupIds:
          title: Notificationgroupids
          type: array
          items:
            type: string
          description: IDs of the notification groups that will receive notifications when this trigger fires.
        description:
          title: Description
          anyOf:
          - type: string
          - type: 'null'
          description: Optional description of the trigger.
          default: null
        enabled:
          title: Enabled
          type: boolean
          description: Whether the trigger is enabled on creation. Defaults to true.
          default: true
        message:
          title: Message
          anyOf:
          - type: string
          - type: 'null'
          description: Optional custom message body.
          default: null
        flag:
          title: Flag
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether firing this trigger should also flag the job for operator attention.
          default: null
        autoResolveFlag:
          title: Autoresolveflag
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, a flag raised by this trigger resolves automatically when the flag condition clears.
          default: null
        optionsGroupIds:
          title: Optionsgroupids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Options groups that scope when this trigger applies.
          default: null
        contractIds:
          title: Contractids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Contract IDs that scope when this trigger applies.
          default: null
        isInternal:
          title: Isinternal
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the trigger is for internal use only (not exposed to customers).
          default: null
        zoneIds:
          title: Zoneids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Zone IDs that scope when this trigger applies (separate from zone-geolocation parameters).
          default: null
        customEventName:
          title: Customeventname
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: For triggers that emit a custom event when fired, the name of that event.
          default: null
        conditionalLogic:
          title: Conditionallogic
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: Optional AND/OR conditional tree that gates when the trigger fires. Shape mirrors the Zod ConditionalStatement schema in nash-ui; currently passed through as JSON. A follow-up will type this explicitly.
          default: null
        type:
          title: Type
          type: string
          const: api_based
        parameters:
          $ref: '#/components/schemas/_NoParams'
    DeliveryIncidentReportParams:
      title: DeliveryIncidentReportParams
      type: object
      properties:
        dirType:
          title: Dirtype
          enum:
          - all
          - refund_request
          type: string
          default: all
        dirCreated:
          title: Dircreated
          type: boolean
          default: false
        dirResolved:
          title: Dirresolved
          type: boolean
          default: false
    DeliveryStatusTransitionParams:
      title: DeliveryStatusTransitionParams
      required:
      - deliveryStatus
      type: object
      properties:
        deliveryStatus:
          title: Deliverystatus
          minLength: 1
          type: string
          description: Delivery status that triggers the notification.
        sendScheduledMessage:
          title: Sendscheduledmessage
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, schedule the message to send at a later time instead of firing immediately.
          default: null
        scheduledSendDeltaMinutes:
          title: Scheduledsenddeltaminutes
          anyOf:
          - maximum: 4320
            minimum: 15.0
            type: integer
          - type: 'null'
          description: Minutes after the status transition to send the scheduled message (15 min to 3 days).
          default: null
    CreateStuckStatusTrigger:
      title: CreateStuckStatusTrigger
      required:
      - name
      - notificationGroupIds
      - type
      - parameters
      type: object
      properties:
        name:
          title: Name
          minLength: 1
          type: string
          description: Human-readable name for this trigger instance.
        notificationGroupIds:
          title: Notificationgroupids
          type: array
          items:
            type: string
          description: IDs of the notification groups that will receive notifications when this trigger fires.
        description:
          title: Description
          anyOf:
          - type: string
          - type: 'null'
          description: Optional description of the trigger.
          default: null
        enabled:
          title: Enabled
          type: boolean
          description: Whether the trigger is enabled on creation. Defaults to true.
          default: true
        message:
          title: Message
          anyOf:
          - type: string
          - type: 'null'
          description: Optional custom message body.
          default: null
        flag:
          title: Flag
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether firing this trigger should also flag the job for operator attention.
          default: null
        autoResolveFlag:
          title: Autoresolveflag
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, a flag raised by this trigger resolves automatically when the flag condition clears.
          default: null
        optionsGroupIds:
          title: Optionsgroupids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Options groups that scope when this trigger applies.
          default: null
        contractIds:
          title: Contractids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Contract IDs that scope when this trigger applies.
          default: null
        isInternal:
          title: Isinternal
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the trigger is for internal use only (not exposed to customers).
          default: null
        zoneIds:
          title: Zoneids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Zone IDs that scope when this trigger applies (separate from zone-geolocation parameters).
          default: null
        customEventName:
          title: Customeventname
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: For triggers that emit a custom event when fired, the name of that event.
          default: null
        conditionalLogic:
          title: Conditionallogic
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: Optional AND/OR conditional tree that gates when the trigger fires. Shape mirrors the Zod ConditionalStatement schema in nash-ui; currently passed through as JSON. A follow-up will type this explicitly.
          default: null
        type:
          title: Type
          type: string
          const: stuck_status
        parameters:
          $ref: '#/components/schemas/StuckStatusParams'
    AddContactToDenyListSerializer:
      title: AddContactToDenyListSerializer
      required:
      - type
      - value
      type: object
      properties:
        type:
          title: Type
          type: string
          description: The type of contact to add to the deny list.
        value:
          title: Value
          type: string
          description: The value of the contact to add to the deny list.
      description: Expected payload for endpoint assigning role names to a user.
    CreateProofOfDeliveryUploadedTrigger:
      title: CreateProofOfDeliveryUploadedTrigger
      required:
      - name
      - notificationGroupIds
      - type
      type: object
      properties:
        name:
          title: Name
          minLength: 1
          type: string
          description: Human-readable name for this trigger instance.
        notificationGroupIds:
          title: Notificationgroupids
          type: array
          items:
            type: string
          description: IDs of the notification groups that will receive notifications when this trigger fires.
        description:
          title: Description
          anyOf:
          - type: string
          - type: 'null'
          description: Optional description of the trigger.
          default: null
        enabled:
          title: Enabled
          type: boolean
          description: Whether the trigger is enabled on creation. Defaults to true.
          default: true
        message:
          title: Message
          anyOf:
          - type: string
          - type: 'null'
          description: Optional custom message body.
          default: null
        flag:
          title: Flag
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether firing this trigger should also flag the job for operator attention.
          default: null
        autoResolveFlag:
          title: Autoresolveflag
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, a flag raised by this trigger resolves automatically when the flag condition clears.
          default: null
        optionsGroupIds:
          title: Optionsgroupids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Options groups that scope when this trigger applies.
          default: null
        contractIds:
          title: Contractids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Contract IDs that scope when this trigger applies.
          default: null
        isInternal:
          title: Isinternal
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether the trigger is for internal use only (not exposed to customers).
          default: null
        zoneIds:
          title: Zoneids
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Zone IDs that scope when this trigger applies (separate from zone-geolocation parameters).
          default: null
        customEventName:
          title: Customeventname
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: For triggers that emit a custom event when fired, the name of that event.
          default: null
        conditionalLogic:
          title: Conditionallogic
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: Optional AND/OR conditional tree that gates when the trigger fires. Shape mirrors the Zod ConditionalStatement schema in nash-ui; currently passed through as JSON. A follow-up will type this explicitly.
          default: null
        type:
          title: Type
          type: string
          const: proof_of_delivery_uploaded
        parameters:
          $ref: '#/components/schemas/_NoParams'
    OrderModifiedParams:
      title: OrderModifiedParams
      required:
      - modifiedFields
      type: object
      properties:
        modifiedFields:
          title: Modifiedfields
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/OrderModifiedField'
          description: Order fields whose modification fires the trigger. The trigger fires when any of the selected fields changes on an order. Select one, several, or all fields.
    CreateDemoTrigger:
      title: CreateDemoTrigger
      required:
      - name
      - notificationGroupIds
      - type
      type: object
      properties:
        name:
          title: Name
          minLength: 1
          type: string
          description: Human-readable name for this trigger instance.
        notificationGroupIds:
          title: Notificationgroupids
          type: array
          items:
            type: string
          description: IDs of the notification groups that will receive notifications when this trigger fires.
        description:
          title: Description
          anyOf:
          - type: string
          - type: 'null'
          description: Optional description of the trigger.
          default: null
        enabled:
          title: Enabled
          type: boolean
          description: Whether the trigger is enabled on creation. Defaults to true.
          default: true
        message:
          title: Message
          anyOf:
          - type: string
          - type: 'null'
          description: Optional custom message body.
          default: null
        flag:
          title: Flag
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether firing this trigger should also flag the job for operator attention.
          default: null
        autoResolveFlag:
          title: Autoresolveflag
          anyOf:
          -

# --- truncated at 32 KB (190 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nash/refs/heads/main/openapi/nash-notifications-api-openapi.yml