Skip to content
ajan.io

Docs menu

On this page

Integrations API Overview

Programmatically create and manage custom integrations in your ajan workspace

The Integrations API lets you programmatically create and manage custom integrations in your ajan workspace. Build integrations that connect to your internal tools, APIs, and services.

Base URL

https://api.ajan.io

API Key Scopes

The Integrations API requires specific API key scopes:

ScopeEndpoints
ASSISTANT_API or INTEGRATION_APIList integrations (GET /integrations/v1/get)
INTEGRATION_APIAll other integration endpoints

Available Endpoints

Integrations

MethodEndpointDescription
GET/integrations/v1/getList shared private API, MCP, and A2A integrations
POST/integrations/v1/createCreate a new integration
GET/integrations/v1/{integrationId}Get integration details
PATCH/integrations/v1/{integrationId}Update an integration
GET/integrations/v1/{integrationId}/iconGet the integration icon
PUT/integrations/v1/{integrationId}/iconReplace the integration icon
PATCH/integrations/v1/{integrationId}/authUpdate auth configuration

Actions

Actions are capabilities you can add to integrations that agents can execute. Each action has a requiresConfirmation default. Agents, workflows, and automations can override it when they run the action.

MethodEndpointDescription
POST/integrations/v1/{integrationId}/actions/createCreate an action
PUT/integrations/v1/{integrationId}/actions/{actionId}Update an action
DELETE/integrations/v1/{integrationId}/actions/{actionId}Delete an action

Triggers

Triggers allow integrations to start workflows based on external events.

MethodEndpointDescription
POST/integrations/v1/{integrationId}/triggers/createCreate a trigger
PUT/integrations/v1/{integrationId}/triggers/{triggerId}Update a trigger
DELETE/integrations/v1/{integrationId}/triggers/{triggerId}Delete a trigger

Quick Start

Here's how to create a simple integration with an action:

javascript
const axios = require("axios");

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.ajan.io";

// 1. Create an integration
const integrationResponse = await axios.post(
  `${BASE_URL}/integrations/v1/create`,
  {
    name: "My Custom Integration",
    description: "Connects to my internal API"
  },
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    }
  }
);

const integrationId = integrationResponse.data.integration.id;

// 2. Add an action to the integration
const actionResponse = await axios.post(
  `${BASE_URL}/integrations/v1/${integrationId}/actions/create`,
  {
    name: "Get User Data",
    description: "Retrieves user information from the internal API",
    code: `
      const response = await ld.request({
        method: "GET",
        url: "https://my-api.example.com/users/" + data.input.userId
      });
      return response.json;
    `,
    inputFields: [
      {
        label: "User ID",
        type: "TEXT",
        description: "The ID of the user to retrieve",
        required: true
      }
    ]
  },
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    }
  }
);

console.log("Action created:", actionResponse.data.action);

Use Cases

  • Internal Tools Integration: Connect agents to your company's internal APIs, databases, or services
  • Custom Workflows: Build integrations that trigger workflows based on external events
  • Data Enrichment: Create actions that fetch and enrich data from multiple sources
  • Automated Reporting: Build integrations that generate and distribute reports

Rate Limits

The Integrations API is limited to 500 RPM per workspace and API key. No token limit applies. If you exceed the limit, you receive a 429 response. Wait and retry with exponential backoff.