Skip to content
ajan.io

Docs menu

On this page

Create Action

Add an action to an integration that agents can execute

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.

Base URL

https://api.ajan.io/integrations/v1/{integrationId}/actions/create

Required Scopes

This endpoint requires the INTEGRATION_API scope.

Parameters

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 150,000 characters)
inputFieldsarrayNoInput fields for the action
requiresConfirmationbooleanNoWhether the action requires user confirmation before running (default: true)

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
jsonSchemastringNoJSON Schema (as a stringified JSON) describing the expected value. Typically used with OBJECT fields to constrain the shape agents must produce.

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

javascript
const axios = require("axios");

async function createAction(integrationId) {
  const response = await axios.post(
    `https://api.ajan.io/integrations/v1/${integrationId}/actions/create`,
    {
      name: "Get User Data",
      description: "Retrieves user information from the internal API by user ID",
      code: `
        const response = await ld.request({
          method: "GET",
          url: "https://api.example.com/users/" + data.input.userId,
          headers: {
            Authorization: "Bearer " + data.auth.apiToken
          }
        });

        if (response.status < 200 || response.status >= 300) {
          throw new Error("User not found");
        }

        return 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)

typescript
{
  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 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:

  • data.input - Object containing the values of input fields
  • data.auth - Object containing configured connection credentials for the integration
  • ld.request - HTTP requests to external APIs
  • ld.log - Execution logs
  • Standard JavaScript built-ins