> ## Documentation Index > Fetch the complete documentation index at: https://upstash.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Trigger Workflow Run > Start a new workflow run. ## OpenAPI ````yaml /workflow/openapi.yaml post /v2/trigger/{workflowUrl} openapi: 3.1.0 info: title: Upstash Workflow REST API description: > Upstash Workflow is a serverless workflow orchestration service built on top of Upstash QStash and Upstash Redis. version: 2.0.0 contact: name: Upstash url: https://upstash.com servers: - url: https://qstash.upstash.io security: - bearerAuth: [] - bearerAuthQuery: [] paths: /v2/trigger/{workflowUrl}: post: tags: - Runs summary: Trigger Workflow Run description: Start a new workflow run. parameters: - in: path name: workflowUrl required: true schema: type: string description: The URL of the workflow to trigger. - in: header name: Upstash-Workflow-RunId required: false schema: type: string description: >- Optional custom run ID for the workflow run. A random ID will be generated if not provided. - name: Upstash-Forward-* in: header schema: type: string description: > You can send custom headers to your workflow. To send a custom header, prefix the header name with `Upstash-Forward-`. We will strip prefix and send them to the destination. | Header | Forwarded To Destination As | |--------|--------------| | Upstash-Forward-My-Header: my-value | My-Header: my-value | | Upstash-Forward-Authorization: Bearer | Authorization: Bearer | - in: header name: Upstash-Retries required: false schema: type: integer default: 3 description: Number of retries for the workflow steps in case of failure. - name: Upstash-Delay in: header schema: type: string examples: - 50s - 1d10h30m - 10h - 1d description: > Delay the message delivery. The format of this header is `` where value is a number and unit is one of: - `s` for seconds - `m` for minutes - `h` for hours. - `d` for days. - name: Upstash-Not-Before in: header schema: type: integer description: > Delay the message delivery until a certain timestamp in the future. The format is a unix timestamp in seconds, based on the UTC timezone. When both `Upstash-Not-Before` and `Upstash-Delay` headers are provided, `Upstash-Not-Before` will take precedence. - in: header name: Upstash-Label required: false schema: type: string description: >- Optional label to attach to the workflow run for easier identification in logs and DLQ. - in: header name: Upstash-Flow-Control-Key required: false schema: type: string description: >- Flow control key to manage concurrency for the workflow run. Steps with the same key will respect the same concurrency limit. Make sure you pass `Upstash-Flow-Control-Value` header as well to define the limits for the key. - in: header name: Upstash-Flow-Control-Value required: false schema: type: string description: > Parallelism and rate limit configuration for the flow control key in the format: `parallelism=, rate=, period=`. See [flow control](/workflow/features/flow-control) for details. - in: header name: Upstash-Failure-Callback required: false schema: type: string description: > Failure callback URL to be called if the workflow run fails after all retries. That is when all the defined retries are exhausted. To call the failure function defined on server, this options should be left empty. A url should be given with this header only to call a different endpoint on failure. See [failureUrl](https://upstash.com/docs/workflow/features/failureFunction/advanced). - Failure callback URL must be prefixed with a valid protocol (http:// or https://) - Failure callbacks are charged as a regular message. - Failure callbacks will use the retry setting from the original request. - name: Upstash-Failure-Callback-Forward-* in: header schema: type: string description: > You can send custom headers along with your failure callback message. To send a custom header, prefix the header name with `Upstash-Failure-Callback-Forward-`. We will strip prefix and them to the failure callback URL. | Header | Forwarded To Callback Destination As | |--------|--------------| | Upstash-Failure-Callback-Forward-My-Header: my-value | My-Header: my-value | | Upstash-Failure-Callback-Forward-Authorization: Bearer | Authorization: Bearer | - name: Upstash-Retry-Delay in: header schema: type: string description: > Customize the delay between retry attempts when step delivery fails. By default, Upstash Workflow uses [exponential backoff](/qstash/features/retry). You can override this by providing a mathematical expressions to compute next delay. This expression is computed after each failed attempt. You can use the special variable `retried`, which is how many times the message has been retried. The `retried` is 0 for the first retry. Supported functions: | Function | Description | |-------------|--------------------------------------| | `pow(x, y)`| Returns x raised to the power of y| | `exp(x)`| Returns e raised to the power of x| | `sqrt(x)`| Takes the square root of x| | `abs(x)`| Returns the absolute value of x| | `floor(x)`| Returns the largest integer less than or equal to x| | `ceil(x)`| Returns the smallest integer greater than or equal to x| | `round(x)`| Rounds x to the nearest integer| | `min(x, y)`| Returns the smaller of x and y| | `max(x, y)`| Returns the larger of x and y| Examples: - `1000`: Fixed 1 second delay - `1000 * (1 + retried)`: Linear backoff - `pow(2, retried) * 1000`: Exponential backoff - `max(1000, pow(2, retried) * 100)`: Exponential with minimum 1s delay requestBody: description: >- The raw request payload passed to the workflow endpoints as is. You can access it via requestPayload parameter on the context object. content: text/plain: schema: type: string application/json: schema: type: object application/octet-stream: schema: type: string format: binary responses: '200': description: Workflow triggered successfully content: application/json: schema: type: object properties: workflowRunId: type: string description: The ID of the triggered workflow run. workflowCreatedAt: type: number format: date-time description: The timestamp when the workflow run was created. '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object required: - error properties: error: type: string description: Error message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: QStash authentication token bearerAuthQuery: type: apiKey in: query name: qstash_token description: QStash authentication token passed as a query parameter ````