Skip to main content
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

ParameterTypeRequiredDescription
integrationIdstringYesUUID of the integration

Request Body

ParameterTypeRequiredDescription
namestringYesTrigger name (max 100 characters)
descriptionstringNoTrigger description (max 90 characters)
pollingCodestringNoJavaScript code to poll for new events (max 1,000 characters)
inputFieldsarrayNoInput fields for configuring the trigger

Input Field Schema

Each input field has the following properties:
PropertyTypeRequiredDescription
labelstringYesField label (max 100 characters)
typestringNoField type (default: “TEXT”)
descriptionstringNoField description (max 500 characters)
placeholderstringNoPlaceholder text (max 200 characters)
requiredbooleanNoWhether the field is required (default: false)
optionsarrayNoOptions for SELECT type fields
allowMultiSelectbooleanNoAllow multiple selections for SELECT fields

Field Types

TypeDescription
TEXTSingle-line text input
MULTI_LINE_TEXTMulti-line text input
NUMBERNumeric input
BOOLEANTrue/false toggle
SELECTDropdown selection
PASSWORDPassword input (masked)
VECTORVector 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");

Response Format

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 CodeDescription
400Invalid request body or invalid integration ID
401Invalid or missing API key
403No access to this integration
404Integration not found
409Trigger with this name already exists in the integration
429Rate limit exceeded
500Internal 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.