Overview

The External AOP API lets you programmatically trigger and monitor AOP (Agent Operating Procedure) executions from your own systems. You authenticate once with OAuth client credentials, exchange them for a short-lived JWT access token, then use that token to start an AOP run and poll its status until it reaches a terminal state.

All requests use HTTPS and JSON. The API is asynchronous: the execute endpoint queues a run and returns an aop_item_id, which you use to track progress through the status endpoint.

Getting Started

Follow these four steps to get up and running:

1. Request an OAuth app from Leena AI team. You will receive a client_id, client_secret, username, and password. Leena AI will share these with you.
2. Generate an access token by calling POST https://<region-code>-acl.leena.ai/api/v1.0/oauth/token with your credentials.
3. Trigger an AOP run by calling POST https://<region-code>-aic.leena.ai/api/v1/external/aop/execute with the aop_id you want to execute.
4. (Optional) Poll the run status at GET https://<region-code>-aic.leena.ai/api/v1/external/aop/items/{aop_item_id}/status until it reaches a terminal state (completed, failed, or aborted).

How to Get the AOP ID

The aop_id required by the execute endpoint is the AOP's identifier. You can fetch it directly from the Leena AI dashboard.

Follow these steps:

1. Sign in to the Leena AI dashboard.
2. Navigate to AI Colleagues, then open the relevant colleague (for example, "IT Support Specialist").
3. Open the AOP whose ID you want to retrieve. This opens the AOP details view.
4. In the AOP details section, locate the Identifier field. The value shown there is your aop_id.
5. Copy the value and use it as the aop_id parameter in the Execute AOP request.

Figure 1 — The Identifier value shown on the AOP details view is the aop_id used in the API.

📘

Tip

The Identifier is a human-readable slug (e.g. it_support_ticket_creation). The execute endpoint also accepts the AOP's ObjectId, but the slug shown here is usually easier to use.

Authentication

All endpoints require a Bearer JWT token in the Authorization header. Tokens are obtained via the platform's OAuth token API.

Step 1 — Register an OAuth App

Request an OAuth app from the Leena AI team. You will receive:

Step 2 — Generate an Access Token

Exchange your credentials for a JWT access token.

POST https://<region-code>-acl.leena.ai/api/v1.0/oauth/token

Headers

Request Body

{
  "username": "<username-received-from-leena>",
  "password": "<password-received-from-leena>",
  "grant_type": "password"
}

Example Request

curl -X POST "https://<region-code>-acl.leena.ai/api/v1.0/oauth/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <Base64-encoded-string-of-clientId:clientSecret>" \
  -d '{
    "username": "<username-received-from-leena>",
    "password": "<password-received-from-leena>",
    "grant_type": "password"
  }'

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "refresh_token": "<Refresh-token>",
  "expires_in": 3600
}

Step 3 — Use the Token

Include the token in the Authorization header for all API calls:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Endpoints

1. Execute AOP

Initiate an AOP execution. The request is accepted and queued for asynchronous processing.

POST https://<region-code>-aic.leena.ai/api/v1/external/aop/execute

Headers

Request Body

Example Request

curl -X POST "https://<region-code>-aic.leena.ai/api/v1/external/aop/execute" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "aop_id": "aop-1",
    "message_to_start": "Analyze the ticket shared",
    "context": {
      "ticket_number": "INC0503407",
      "state": "In Progress",
      "priority": "Priority 4",
      "impact": "3 - Low",
      "urgency": "3 - Low",
      "severity": "3 - Low",
      "category": "Request",
      "subcategory": "General Question",
      "short_description": "voucher approval",
      "description": "<Tickets-Description>",
      "comments_and_work_notes": "<comments>",
      "close_notes": "",
      "close_code": "",
      "contact_type": "Phone",
      "opened_at": "04/15/26 03:22:21",
      "closed_at": "",
      "resolved_at": "",
      "opened_by": "",
      "assigned_to": "",
      "assignment_group": "",
      "caller_id": "",
      "resolved_by": "",
      "closed_by": "",
      "location": ""
    }
  }'

Response — 200 OK

{
  "aop_item_id": "69e90f247276b2fa8f2766e0",
  "request_id": "69e90f237276b2fa8f2766da",
  "run_id": "ID_007762",
  "status": "accepted"
}

📘

Note

"accepted" is an acknowledgement status (analogous to HTTP 202). It means the execution has been queued, not completed. Use the status endpoint to track progress.

Error Responses

2. Get AOP Execution Status

Poll the current status of an AOP execution.

GET https://<region-code>-aic.leena.ai/api/v1/external/aop/items/{aop_item_id}/status

Headers

Path Parameters

Example Request

curl "https://<region-code>-aic.leena.ai/api/v1/external/aop/items/69e90f247276b2fa8f2766e0/status" \
  -H "Authorization: Bearer <access_token>"

Response — 200 OK

{
  "aop_item_id": "69e90f247276b2fa8f2766e0",
  "reference_id": "RPT000042",
  "status": "in_progress",
  "initiated_at": "2026-04-22T15:50:55.000000",
  "completed_at": null
}

Execution Statuses

Error Responses

Usage Pattern

A typical integration follows this flow:

1. POST https://<region-code>-acl.leena.ai/api/v1.0/oauth/token
      → get access_token

2. POST https://<region-code>-aic.leena.ai/api/v1/external/aop/execute
      → get aop_item_id (status: "accepted")

3. (Optional) GET https://<region-code>-aic.leena.ai/api/v1/external/aop/items/{id}/status
      → poll until status is terminal

Terminal statuses: completed, failed, aborted.

Region Codes and Endpoints