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

# Trigger pipeline via webhook

## Idempotency

Send an optional `Idempotency-Key` request header to make a trigger safe to retry. The value must be a **GUID**.

* A request whose key is missing or is not a valid GUID is processed normally, with no idempotency protection.
* While a request with a given key is in flight, or after it has completed, a second request with the same key returns **409 Conflict**.
* If the request fails, its pending marker is released automatically, so you can safely retry the same key.

```bash theme={null}
curl -X POST "https://api.ingestly.ai/pipelines/{pipelineId}/trigger" \
  -H "X-Api-Key: ing_your_api_key_here" \
  -H "Idempotency-Key: 3f2504e0-4f89-41d3-9a0c-0305e82c3301" \
  -F "file=@document.pdf"
```

## Correlation ID

Every response includes an `X-Correlation-ID` header, a server-generated identifier for the request. Include it when contacting support so a specific request can be traced.

<Note>Any `X-Correlation-ID` you send on the request is ignored at the public edge; the platform always mints a fresh id and returns it on the response.</Note>


## OpenAPI

````yaml POST /pipelines/{pipelineId}/trigger
openapi: 3.1.1
info:
  title: Gateway | v1
  version: 1.0.0
servers:
  - url: http://localhost:4000/
security: []
tags:
  - name: Workspaces
  - name: WebhookSigningKey
  - name: Users
  - name: Templates
  - name: Subscriptions
  - name: Admin
  - name: Runs
  - name: Roles
  - name: Review Tasks
  - name: Pipelines
  - name: Pipeline Groups
  - name: Pipeline Corrections
  - name: Organizations
  - name: Notifications
  - name: Auth
  - name: Invitations
  - name: Documents
  - name: Dev
  - name: Dashboard
  - name: Contact
  - name: Connectors
  - name: Comments
  - name: Beta
  - name: ApiKeys
  - name: Alert Rules
  - name: AI
paths:
  /pipelines/{pipelineId}/trigger:
    post:
      tags:
        - Pipelines
      parameters:
        - name: pipelineId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Optional GUID that makes the request idempotent. A duplicate request
            with the same key returns 409 while the first is in flight or after
            it completed.
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  $ref: '#/components/schemas/IFormFile'
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerPipelineWebhookResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailResponse'
components:
  schemas:
    IFormFile:
      type: string
      format: binary
    TriggerPipelineWebhookResponse:
      required:
        - documentId
        - status
      type: object
      properties:
        documentId:
          type: string
          format: uuid
        status:
          type: string
    ProblemDetailResponse:
      required:
        - status
        - title
        - type
        - instance
        - traceId
      type: object
      properties:
        status:
          type: integer
          format: int32
        title:
          type: string
        type:
          type: string
        instance:
          type: string
        traceId:
          type: string
        detail:
          type:
            - 'null'
            - string
        errors:
          type:
            - 'null'
            - object
          additionalProperties:
            type: array
            items:
              type: string

````