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

# Create Trigger

> Add a trigger to an integration that can start workflows or agent conversations

<Info>
  **Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

Creates a new trigger for an integration. Triggers allow integrations to start workflows or agent conversations based on external events, typically by polling an external system for changes.

## Required Scopes

This endpoint requires the `INTEGRATION_API` scope.

## Path Parameters

| Parameter       | Type   | Required | Description             |
| --------------- | ------ | -------- | ----------------------- |
| `integrationId` | string | Yes      | UUID of the integration |

## Request Body

| Parameter     | Type   | Required | Description                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------------- |
| `name`        | string | Yes      | Trigger name (max 100 characters)                             |
| `description` | string | No       | Trigger description (max 90 characters)                       |
| `pollingCode` | string | No       | JavaScript code to poll for new events (max 1,000 characters) |
| `inputFields` | array  | No       | Input fields for configuring the trigger                      |

### Input Field Schema

Each input field has the following properties:

| Property           | Type    | Required | Description                                    |
| ------------------ | ------- | -------- | ---------------------------------------------- |
| `label`            | string  | Yes      | Field label (max 100 characters)               |
| `type`             | string  | No       | Field type (default: "TEXT")                   |
| `description`      | string  | No       | Field description (max 500 characters)         |
| `placeholder`      | string  | No       | Placeholder text (max 200 characters)          |
| `required`         | boolean | No       | Whether the field is required (default: false) |
| `options`          | array   | No       | Options for SELECT type fields                 |
| `allowMultiSelect` | boolean | No       | Allow multiple selections for SELECT fields    |

### Field Types

| Type              | Description             |
| ----------------- | ----------------------- |
| `TEXT`            | Single-line text input  |
| `MULTI_LINE_TEXT` | Multi-line text input   |
| `NUMBER`          | Numeric input           |
| `BOOLEAN`         | True/false toggle       |
| `SELECT`          | Dropdown selection      |
| `PASSWORD`        | Password input (masked) |
| `VECTOR`          | Vector input            |

## Example

```javascript theme={null}
const axios = require("axios");

async function createTrigger(integrationId) {
  const response = await axios.post(
    `https://api.langdock.com/integrations/v1/${integrationId}/triggers/create`,
    {
      name: "New Issue Created",
      description: "Triggers when a new issue is created in the project tracker",
      pollingCode: `
        const response = await fetch('https://api.example.com/issues?since=' + lastPollTime, {
          headers: {
            'Authorization': 'Bearer ' + secrets.API_TOKEN
          }
        });

        if (!response.ok) {
          throw new Error('Failed to fetch issues');
        }

        const issues = await response.json();
        return issues.map(issue => ({
          id: issue.id,
          title: issue.title,
          description: issue.description,
          createdAt: issue.created_at
        }));
      `,
      inputFields: [
        {
          label: "Project ID",
          type: "TEXT",
          description: "The ID of the project to monitor",
          placeholder: "e.g., proj_123",
          required: true
        },
        {
          label: "Priority Filter",
          type: "SELECT",
          description: "Only trigger for issues with this priority",
          options: [
            { label: "All", value: "all" },
            { label: "High", value: "high" },
            { label: "Medium", value: "medium" },
            { label: "Low", value: "low" }
          ],
          required: false
        }
      ]
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Created trigger:", response.data.trigger);
}

createTrigger("550e8400-e29b-41d4-a716-446655440000");
```

## Response Format

### Success Response (201 Created)

```typescript theme={null}
{
  trigger: {
    id: string;           // UUID of the created trigger
    name: string;         // Trigger name
    slug: string;         // URL-friendly identifier (auto-generated)
    description: string;  // Trigger description
    type: string;         // Trigger type
    pollingCode: string | null;  // JavaScript polling code
    inputFields: Array<{
      slug: string;       // Field identifier
      label: string;      // Display label
      type: string;       // Field type
      description: string;
      placeholder: string | null;
      required: boolean;
      options: Array<{label: string, value: string}> | null;
      allowMultiSelect: boolean | null;
    }>;
  };
}
```

## Error Handling

| Status Code | Description                                              |
| ----------- | -------------------------------------------------------- |
| 400         | Invalid request body or invalid integration ID           |
| 401         | Invalid or missing API key                               |
| 403         | No access to this integration                            |
| 404         | Integration not found                                    |
| 409         | Trigger with this name already exists in the integration |
| 429         | Rate limit exceeded                                      |
| 500         | Internal server error                                    |

## Polling Code Environment

Trigger polling code runs in a sandboxed JavaScript environment with access to:

* `inputs` - Object containing the values of input fields configured by the user
* `secrets` - Object containing configured secrets for the integration
* `lastPollTime` - Timestamp of the last successful poll (for incremental fetching)
* `fetch` - Standard fetch API for HTTP requests
* Standard JavaScript built-ins

The polling code should return an array of events. Each returned event will trigger the associated workflow or agent conversation.

<Warning>
  Polling code should handle errors gracefully. Unhandled errors will cause the trigger to fail and may result in missed events.
</Warning>

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>