> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Nash exposes two MCP servers. The docs MCP server at https://docs.usenash.com/mcp searches this documentation and needs no credentials. The Nash MCP server at https://mcp.usenash.com/mcp operates an organization's deliveries and needs a Nash API key. See https://docs.usenash.com/reference/build-with-ai.
> Use the Sandbox environment (https://api.sandbox.usenash.com/v1) for anything that creates or dispatches deliveries during development.

# Create Workflow

> Create a new workflow with nodes, edges, and a trigger. The workflow is created in draft status by default. Nodes define the actions and filters, edges define the execution flow between nodes, and the trigger defines when the workflow is activated. First fetch GET /workflows/schema for current action config schemas and branch rules. Bounded AI decisions use nodeType=action, nodeAction=ai_decision; a workflow may contain multiple decision nodes, each with its own config and named decision edges.



## OpenAPI

````yaml post /v1/workflows
openapi: 3.1.0
info:
  title: Nash API
  version: 1.0.0
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)
security: []
tags:
  - name: Notifications
    description: Notifications
    x-nash-topic: config
  - name: Annotate
    description: Annotate
    x-nash-topic: wismo
  - name: Notifications — Send
    description: One-off notification send without a NotificationTrigger.
    x-nash-topic: notifications
  - name: Shipping
    description: Shipping operations
    x-nash-topic: shipping
  - name: Workflow
    description: Workflow automation management
    x-nash-topic: scheduling
  - name: Workflow Execution
    description: Workflow execution history and monitoring
    x-nash-topic: scheduling
  - name: Optimization Strategies
    description: Create, read, update, and delete route optimization strategies.
    x-nash-topic: scheduling
  - name: AI Agents
    description: AI agent management — create, read, update, and delete agents
    x-nash-topic: config
  - name: AI Functions
    description: LLM-backed domain tools
    x-nash-topic: ai
  - name: Webhooks
    description: Webhook delivery inspection
    x-nash-topic: webhooks
  - name: Miscellaneous
    description: Miscellaneous
  - name: Job
    description: Job
    x-nash-topic: wismo
  - name: Batch Job
    description: Batch Job
    x-nash-topic: wismo
  - name: Order
    description: Order
    x-nash-topic: wismo
  - name: Provider
    description: Provider
    x-nash-topic: provider
  - name: Dispatch Strategies
    description: Dispatch Strategies
    x-nash-topic: scheduling
  - name: Store Locations
    description: Store Locations
    x-nash-topic: config
  - name: Delivery Windows
    description: Delivery Windows
    x-nash-topic: config
  - name: Zones
    description: Zones
    x-nash-topic: config
  - name: Feedback
    description: Feedback
    x-nash-topic: reporting
  - name: Organizations
    description: Organizations
    x-nash-topic: config
  - name: Store Catalog
    description: Store Catalog
    x-nash-topic: config
  - name: Route
    description: Route
    x-nash-topic: scheduling
  - name: Messaging
    description: Messaging
    x-nash-topic: config
  - name: Billing
    description: Invoice-aligned customer billing usage
    x-nash-topic: config
  - name: Contracts
    description: Provider contract pricing and version listings
    x-nash-topic: provider
  - name: Couriers
    description: Couriers
    x-nash-topic: provider
  - name: Fleet
    description: >-
      Inbound endpoints fleets call to manage their drivers and update in-flight
      deliveries.
    x-nash-topic: driver
  - name: Embed Sessions
    description: >-
      Mint short-lived, browser-safe sessions for embedded Nash Widgets.
      Authenticated with an org embed credential, which must stay on your
      backend.
    x-nash-topic: config
  - name: Event Timeline
    description: Entity-scoped event timeline + outbound provider traffic for one entity.
    x-nash-topic: internal
  - name: Files
    description: Stable links to files such as proof-of-delivery photos.
    x-nash-topic: wismo
  - name: Optimization Fleet Projection
    description: >-
      Optimizer-facing projection of the effective fleet for a single-store
      solve
    x-nash-topic: scheduling
  - name: Hub Scanning
    description: Scan physical packages onto their route rack at a hub.
    x-nash-topic: scheduling
  - name: Imports
    description: >-
      Import orders, store locations and couriers from rows, validated first
      with a dry run.
    x-nash-topic: config
  - name: Inventory
    description: Store inventory catalog sync to SFTP retail destinations (e.g. Uber).
    x-nash-topic: store_catalog
  - name: Launchpad
    description: >-
      Launchpad self-serve setup: the Payment step and the setup tracking
      preview.
    x-nash-topic: config
  - name: Optimization Activities
    description: Optimization runs launched from the portal or the API
    x-nash-topic: scheduling
  - name: Optimization Run Comparison
    description: >-
      Why a route optimization run left orders unassigned, from the difference
      with the previous run
    x-nash-topic: scheduling
  - name: Optimization Run Re-solve
    description: >-
      Whether the change since the previous run caused a run to drop orders,
      from solving both again
    x-nash-topic: scheduling
  - name: Order Intake
    description: >-
      The hosted Order Intake form's browser API: mint a short-lived session
      from the form's public link, refresh it, and read the form's public
      configuration. From your backend, mint a session for the form embedded on
      your own site.
    x-nash-topic: config
  - name: Dispatch plans
    description: >-
      Draft dispatch plans: the orders and routes a dispatcher is planning
      before release.
    x-nash-topic: scheduling
  - name: Route Restrictions
    description: Org-scoped geographic areas the route optimizer must avoid traversing.
    x-nash-topic: config
  - name: Rule Books
    description: >-
      An organization's routing rules for planning, versioned as a whole: read
      the version in use, change rules in a draft, record who confirmed them,
      and publish.
    x-nash-topic: config
  - name: Driver Scheduling
    description: Assign drivers to fixed loads across days under US hours-of-service rules
    x-nash-topic: scheduling
  - name: Shifts
    description: Shifts
    x-nash-topic: provider
  - name: Signup
    description: >-
      Launchpad self-serve signup: create the user, then the person's first
      organization.
    x-nash-topic: config
  - name: Templates
    description: Templates
    x-nash-topic: config
  - name: Users
    description: User, role, and organization-membership management.
    x-nash-topic: config
  - name: Vehicles
    description: Vehicles
    x-nash-topic: provider
  - name: Widgets
    description: >-
      Org configuration for embedded Nash Widgets: parent origins, enablement,
      and embed credentials.
    x-nash-topic: config
  - name: Conversation Agent
    description: >-
      Inbox conversation context and team-only whispers for Nash's conversation
      agent.
    x-nash-topic: internal
  - name: Driver Chat
    description: Operator-approved messages from Nash's route agent to the route's driver.
    x-nash-topic: internal
  - name: Integration Health
    description: Aggregate API errors
    x-nash-topic: internal
  - name: Provider Chat
    description: Carrier-chat context for a route, scoped to the caller's organization.
    x-nash-topic: internal
  - name: Order Ingestion
    description: >-
      Internal validate, commit, and reconciliation boundary for governed Order
      imports.
    x-nash-topic: internal
paths:
  /v1/workflows:
    post:
      tags:
        - Workflow
      summary: Create Workflow
      description: >-
        Create a new workflow with nodes, edges, and a trigger. The workflow is
        created in draft status by default. Nodes define the actions and
        filters, edges define the execution flow between nodes, and the trigger
        defines when the workflow is activated. First fetch GET
        /workflows/schema for current action config schemas and branch rules.
        Bounded AI decisions use nodeType=action, nodeAction=ai_decision; a
        workflow may contain multiple decision nodes, each with its own config
        and named decision edges.
      operationId: create_workflow_v1_workflows_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowInputSerializer'
        required: true
      responses:
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NashValidationError'
components:
  schemas:
    CreateWorkflowInputSerializer:
      title: CreateWorkflowInputSerializer
      required:
        - name
        - nodes
        - edges
        - trigger
      type: object
      properties:
        name:
          title: Name
          type: string
        description:
          title: Description
          anyOf:
            - type: string
            - type: 'null'
          default: null
        status:
          anyOf:
            - $ref: '#/components/schemas/WorkflowStatus'
            - type: 'null'
          default: null
        nodes:
          title: Nodes
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNodeInputSerializer'
        edges:
          title: Edges
          type: array
          items:
            $ref: '#/components/schemas/WorkflowEdgeInputSerializer'
        trigger:
          $ref: '#/components/schemas/WorkflowTriggerInputSerializer'
    NashValidationError:
      title: NashValidationError
      required:
        - error
        - response_status
        - RequestID
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NashErrorDetails'
        response_status:
          title: Response Status
          type: string
        RequestID:
          title: Requestid
          type: string
    WorkflowStatus:
      title: WorkflowStatus
      enum:
        - draft
        - active
        - inactive
        - archived
        - template
      type: string
    WorkflowNodeInputSerializer:
      title: WorkflowNodeInputSerializer
      required:
        - nodeType
        - nodeKey
        - nodeLabel
      type: object
      properties:
        nodeType:
          $ref: '#/components/schemas/WorkflowNodeType'
          description: 'Node role: trigger, action, filter, or switch.'
        nodeKey:
          title: Nodekey
          type: string
          description: Unique key within this workflow. Edges reference nodes by this key.
        nodeAction:
          anyOf:
            - $ref: '#/components/schemas/WorkflowNodeAction'
            - type: 'null'
          description: >-
            Required for action nodes. GET /workflows/schema lists valid actions
            and their config schemas.
          default: null
        nodeActionConfig:
          title: Nodeactionconfig
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          description: >-
            Config for the action. Shape depends on node_action. See GET
            /workflows/schema.
          default: null
        nodeFilterConfig:
          title: Nodefilterconfig
          anyOf:
            - type: array
              items:
                type: object
                additionalProperties: true
            - type: 'null'
          description: >-
            Filter conditions. Each dict has field, operator, and value. See GET
            /workflows/schema for available fields and operators.
          default: null
        nodeLabel:
          title: Nodelabel
          type: string
          description: Human-readable label for this node.
        isEnabled:
          title: Isenabled
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
        isTrigger:
          title: Istrigger
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
    WorkflowEdgeInputSerializer:
      title: WorkflowEdgeInputSerializer
      required:
        - edgeKey
        - sourceNodeKey
        - targetNodeKey
        - executionOrder
      type: object
      properties:
        edgeKey:
          title: Edgekey
          type: string
          description: Unique key within this workflow.
        sourceNodeKey:
          title: Sourcenodekey
          type: string
          description: node_key of the source node.
        targetNodeKey:
          title: Targetnodekey
          type: string
          description: node_key of the target node.
        executionOrder:
          title: Executionorder
          type: integer
          description: Execution order when a node has multiple outgoing edges.
        edgeType:
          anyOf:
            - $ref: '#/components/schemas/WorkflowEdgeType'
            - type: 'null'
          description: >-
            Use 'default' for trigger and ordinary action nodes; 'decision' with
            branchKey for AI Decision. Filters use 'success' or 'negative'.
          default: null
        branchKey:
          title: Branchkey
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Required only for decision edges from ai_decision: yes/no for
            yes_no, a configured choices[].key for choice, above/below for
            score, or uncertain/error for any mode. At most one edge per outcome
            per node.
          default: null
    WorkflowTriggerInputSerializer:
      title: WorkflowTriggerInputSerializer
      required:
        - triggerType
      type: object
      properties:
        triggerType:
          $ref: '#/components/schemas/WorkflowTriggerType'
          description: >-
            Currently only 'event' is supported via this REST API. Other trigger
            types (manual, cron, webhook) exist but are not exposed here.
        eventTriggerType:
          title: Eventtriggertype
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            For notification-based triggers only. Pass the entry's 'value' from
            the GET /workflows/schema triggers list, not the trigger key. Leave
            null for event triggers like order.created.
          default: null
        eventName:
          title: Eventname
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The event to listen for. For schema entries whose input_field is
            'eventName', pass the entry's value here (e.g. 'order.created'). For
            notification triggers, omit this. Defaults to
            'notification_trigger.tripped'.
          default: null
        customEventDefinitionId:
          title: Customeventdefinitionid
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Reference to a pre-defined custom event from the organization's
            catalog. Mutually exclusive with eventName: the definition's key
            becomes the trigger's event name. Not valid for cron triggers.
          default: null
        courierFormDefinitionId:
          title: Courierformdefinitionid
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Reference to a CourierFormDefinition. Required when eventName is
            'courier_form.submitted'; not valid for any other trigger type.
          default: null
        notificationTriggerParameters:
          title: Notificationtriggerparameters
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          description: Extra config for notification triggers. Not used for event triggers.
          default: null
        isEnabled:
          title: Isenabled
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
    NashErrorDetails:
      title: NashErrorDetails
      required:
        - code
        - message
      type: object
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
        details:
          title: Details
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          description: >-
            Structured error context; shape depends on `code`. For
            `VALIDATION_ERRORS` (HTTP 422) it is `{"fields": [{"loc": [...],
            "msg": "...", "type": "..."}]}` — one entry per invalid field, where
            `loc` is the field path, `msg` the human-readable message, and
            `type` the machine-readable error type (e.g. `string_type`,
            `missing`).
          default: null
    WorkflowNodeType:
      title: WorkflowNodeType
      enum:
        - trigger
        - action
        - filter
        - dispatch_check
        - switch
        - subgraph
        - agent_invoke
      type: string
      description: Types of workflow nodes.
    WorkflowNodeAction:
      title: WorkflowNodeAction
      enum:
        - dispatch_strategy
        - optimization_strategy
        - modify_order_price_or_tip
        - modify_order_instructions
        - modify_order_metadata
        - reschedule_order
        - add_tag
        - flag_delivery
        - send_email
        - send_sms
        - send_slack
        - send_webhook
        - send_to_destinations
        - agent_call
        - summarize
        - extract_metadata_field
        - add_requirements
        - auto_reassign
        - emit_custom_event
        - browser_automation
        - cancel_delivery
        - mark_order_ready
        - send_teams_channel_message
        - cancel_order
        - remove_order_from_route
        - invoke_agent
        - ai_decision
        - create_route_flag
        - update_route_flag
        - resolve_route_flag
        - assign_route_flags
        - send_http_request
        - add_validation_error
        - generate_document
        - add_handling_tags
      type: string
      description: Actions that can be performed by a workflow node.
    WorkflowEdgeType:
      title: WorkflowEdgeType
      enum:
        - default
        - success
        - negative
        - decision
      type: string
    WorkflowTriggerType:
      title: WorkflowTriggerType
      enum:
        - manual
        - webhook
        - cron
        - event
        - subgraph
      type: string
      description: Types of workflow triggers.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.