Using our API via a dedicated deployment? Just replace api.langdock.com with your deployment’s base URL: <deployment-url>/api/public
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 |
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
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");
Success Response (201 Created)
{
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.
Polling code should handle errors gracefully. Unhandled errors will cause the trigger to fail and may result in missed events.
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.