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 |
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 |
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
}
]
},
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
}
);
console.log("Created action:", response.data.action);
}
createAction("550e8400-e29b-41d4-a716-446655440000");
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 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.