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

# Trigger Workflow

> Starts a workflow run using the specified webhook. The workflow executes asynchronously and returns immediately with a run ID that can be used to track progress.

**Rate Limit:** 60 requests per minute per API key.



## OpenAPI

````yaml POST /{key}/trigger
openapi: 3.1.0
info:
  title: Cordage Webhook API
  description: >-
    The Cordage Webhook API allows you to programmatically trigger workflows,
    monitor run status, and retrieve outputs. Use webhooks to integrate your AI
    workflows into external applications, automation pipelines, or custom tools.
  version: 1.0.0
  contact:
    name: Cordage Support
    url: https://trycordage.com
servers:
  - url: https://api.trycordage.com/api/webhooks
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Workflows
    description: Trigger and manage workflow executions
  - name: Runs
    description: Monitor and control workflow runs
paths:
  /{key}/trigger:
    post:
      tags:
        - Workflows
      summary: Trigger a workflow
      description: >-
        Starts a workflow run using the specified webhook. The workflow executes
        asynchronously and returns immediately with a run ID that can be used to
        track progress.


        **Rate Limit:** 60 requests per minute per API key.
      operationId: triggerWorkflow
      parameters:
        - name: key
          in: path
          description: >-
            The unique webhook key for your workflow. Found in the Webhook node
            settings on your canvas.
          required: true
          schema:
            type: string
            example: wh_abc123xyz
      requestBody:
        description: >-
          Optional input data to pass to the workflow. This data is accessible
          to nodes in your workflow.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerWebhookBody'
            examples:
              simple:
                summary: Simple text input
                value:
                  prompt: A beautiful sunset over mountains
              complex:
                summary: Multiple inputs
                value:
                  prompt: Generate a landscape
                  style: photorealistic
                  width: 1024
                  height: 768
      responses:
        '200':
          description: Workflow triggered successfully
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per window
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in current window
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: Seconds until rate limit resets
              schema:
                type: integer
                example: 45
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponse'
              example:
                run_id: 550e8400-e29b-41d4-a716-446655440000
                status: running
                message: Workflow started
                node_count: 5
        '400':
          description: Bad request - webhook is disabled or invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Webhook is disabled
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized. Provide valid API key in Authorization header.
        '402':
          description: Payment required - insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Insufficient credits
        '403':
          description: Forbidden - API key doesn't have access to this webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Access denied. API key workspace does not match webhook canvas
                  workspace.
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Webhook not found
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Rate limit exceeded.
                retry_after: 30
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
components:
  schemas:
    TriggerWebhookBody:
      type: object
      additionalProperties: true
      description: >-
        Optional key-value pairs to pass as input to the workflow. The structure
        depends on your workflow's input nodes.
      example:
        prompt: A beautiful landscape
        style: photorealistic
    TriggerResponse:
      type: object
      required:
        - run_id
        - status
        - message
      properties:
        run_id:
          type: string
          format: uuid
          description: Unique identifier for this workflow run
        status:
          type: string
          enum:
            - running
          description: Always 'running' for a successful trigger
        message:
          type: string
          description: Human-readable status message
        node_count:
          type: integer
          minimum: 1
          description: Number of nodes that will be executed in this run
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
        retry_after:
          type: integer
          description: Seconds to wait before retrying (only present for rate limit errors)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        API key authentication. Get your API key from the workspace settings.

        Example: `Authorization: Bearer cordage_xxxxxxxxxxxx`

````