> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Action

> Add an action to an integration that agents can execute

<Info>
  **Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

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                        |

### 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      |

### 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

```javascript theme={null}
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)

```typescript theme={null}
{
  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

<Warning>
  Action code should handle errors gracefully. Unhandled errors will cause the action to fail and return an error message to the agent.
</Warning>

<Info>
  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](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>