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 action for an integration. Actions are capabilities that agents can execute, like sending messages, fetching data, or creating records in external systems.

Required Scopes

This endpoint requires the INTEGRATION_API scope.

Path Parameters

ParameterTypeRequiredDescription
integrationIdstringYesUUID of the integration

Request Body

ParameterTypeRequiredDescription
namestringYesAction name (max 100 characters)
descriptionstringNoAction description (max 1,000 characters)
codestringNoJavaScript code to execute (max 40,000 characters)
inputFieldsarrayNoInput fields for the action

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
contextActionIdstringNoUUID of action to use for dynamic options

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
OBJECTObject input
FILEFile input
IDIdentifier input

Example

const axios = require("axios");

async function createAction(integrationId) {
  const response = await axios.post(
    `https://api.langdock.com/integrations/v1/${integrationId}/actions/create`,
    {
      name: "Get User Data",
      description: "Retrieves user information from the internal API by user ID",
      code: `
        const response = await fetch('https://api.example.com/users/' + inputs.userId, {
          headers: {
            'Authorization': 'Bearer ' + secrets.API_TOKEN
          }
        });

        if (!response.ok) {
          throw new Error('User not found');
        }

        return await response.json();
      `,
      inputFields: [
        {
          label: "User ID",
          type: "TEXT",
          description: "The unique identifier of the user",
          placeholder: "e.g., user_123",
          required: true
        },
        {
          label: "Include Details",
          type: "BOOLEAN",
          description: "Include extended user details",
          required: false
        }
      ]
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

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

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

Response Format

Success Response (201 Created)

{
  action: {
    id: string;           // UUID of the created action
    name: string;         // Action name
    slug: string;         // URL-friendly identifier (auto-generated)
    description: string;  // Action description
    code: string | null;  // JavaScript code
    order: number;        // Display order
    inputFields: Array<{
      slug: string;       // Field identifier
      label: string;      // Display label
      type: string;       // Field type
      description: string;
      placeholder: string | null;
      required: boolean;
      order: number;
      options: Array<{label: string, value: string}> | null;
      allowMultiSelect: boolean | null;
      contextActionId: string | 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
409Action with this name already exists in the integration
429Rate limit exceeded
500Internal server error

Code Execution Environment

Action code runs in a sandboxed JavaScript environment with access to:
  • inputs - Object containing the values of input fields
  • secrets - Object containing configured secrets for the integration
  • fetch - Standard fetch API for HTTP requests
  • Standard JavaScript built-ins
Action code should handle errors gracefully. Unhandled errors will cause the action to fail and return an error message to the agent.
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.