Create Action

Add an action to an integration that agents can execute

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

Parameter	Type	Required	Description
integrationId	string	Yes	UUID of the integration

Request Body

Parameter	Type	Required	Description
name	string	Yes	Action name (max 100 characters)
description	string	No	Action description (max 1,000 characters)
code	string	No	JavaScript code to execute (max 40,000 characters)
inputFields	array	No	Input fields for the action
requiresConfirmation	boolean	No	Whether the action requires user confirmation before running (default: true)

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
contextActionId	string	No	UUID of action to use for dynamic options
jsonSchema	string	No	JSON Schema (as a stringified JSON) describing the expected value. Typically used with OBJECT fields to constrain the shape agents must produce.

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
OBJECT	Object input
FILE	File input
ID	Identifier 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
        },
        {
          label: "Filters",
          type: "OBJECT",
          description: "Structured filters applied to the user lookup",
          required: false,
          jsonSchema: JSON.stringify({
            type: "object",
            properties: {
              status: { type: "string", enum: ["active", "inactive"] },
              limit: { type: "integer", minimum: 1, maximum: 100 }
            },
            required: ["status"]
          })
        }
      ]
    },
    {
      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
    requiresConfirmation: boolean; // Whether the action requires user confirmation before running
    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;
      jsonSchema: string | 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	Action with this name already exists in the integration
429	Rate limit exceeded
500	Internal 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.