External API's

Adopt’s External API lets you integrate agentic functionality directly into your app or backend services — no UI embed required. You can:

Authenticate with client credentials
Create conversations for end users
Send messages and get AI responses (optionally streaming)
List conversations with filters and pagination
Fetch messages for a given conversation

Base URLs

Swagger UI (interactive): https://connect.adopt.ai/docs
OpenAPI (3.1) spec: https://connect.adopt.ai/openapi.json

Authentication

To call any API, you’ll need a clientId and secret. You can generate these from the Adopt Platform:

Go to Settings → Profile → Personal Tokens
Click “Generate Token”
Copy the clientId and secret
Use them in the /v1/auth/token request below

💡 You can manage and revoke tokens from the same page at any time.

All requests require a JWT Bearer Token. First, exchange your client credentials for an access token using: POST /v1/auth/token Request

curl -sS https://connect.adopt.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"YOUR_CLIENT_ID","secret":"YOUR_SECRET"}'

Request body

{
  "clientId": "string",
  "secret": "string"
}

Response

{
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": 3600,
  "expires": "2025-09-05T12:00:00Z"
}

Use the token in the Authorization header:

Authorization: Bearer <access_token>

Action Logs

The Action Logs endpoints let you inspect, filter, and paginate through low-level execution logs produced while an action runs inside a conversation.
Use them to debug failures, trace tool calls, or review inputs/outputs for compliance and QA.

List Action Logs

**GET **/v1/action-logs Fetches action logs filtered to specific fields only.
Supports pagination and optional date range filtering. Query Parameters

page – (integer) Page number
- Default: 1
- Minimum: 1
page_size – (integer) Number of items per page
- Default: 10
- Minimum: 1
- Maximum: 100
start_date – (string | null) Start date in YYYY-MM-DD format
end_date – (string | null) End date in YYYY-MM-DD format

Example Request

curl -sS "https://connect.adopt.ai/v1/action-logs/?page=1&page_size=10&start_date=2025-11-01&end_date=2025-11-04" \
  -H 
"Authorization: Bearer $TOKEN"

Example Response

[
{
            "id": "074e591b-2332-469e-8dc2-ea63e53a2c6d",
            "conversation_id": "e2586571-338a-48d6-ba61-c817924d5da1",
            "action_statement": "Test User prompt",
            "message_ids": [
                "63465bc6-f297-41fc-b862-da4ee4321d48",
                "8c4d7c31-5363-4e1c-8de3-84d2c05219f9"
            ],
            "org_id": "9cce52e6-969b-46d3-919e-fd148072d399",
            "action_type": "FETCH",
            "action_status": "Completed",
            "created_at": "2025-11-03T12:27:51"
}
]

Get Messages for an Action Log

**GET **/v1/action-logs/{action_log_id}/messages Retrieves all messages associated with a specific action log, identified by its action_log_id.
This endpoint is typically used to debug or inspect the sequence of messages (user, system, or agent) recorded during an action’s execution. Path Parameters

action_log_id – (string, required) Unique ID of the action log to retrieve messages for.

Query Parameters

None

Example Request

curl -sS "https://connect.adopt.ai/v1/action-logs/al_123456/messages" \
  -H 
"Authorization: Bearer $TOKEN"

Example Response

[
    {
        "id": "caabd147-a132-4e99-bacf-ccf55e576195",
        "conversation_id": "e2586571-338a-48d6-ba61-c817924d5da1",
        "message": "Test User prompt"",
        "role": "user",
        "feedback": null,
        "created_at": "2025-11-03 12:28:16.425000"
    },
    {
        "id": "c5a10631-a657-4f9e-9c5b-633cdad70d23",
        "conversation_id": "e2586571-338a-48d6-ba61-c817924d5da1",
        "message": {
            "additional_data": {},
            "body": [
                {
                    "data": "This is a test Agent response",
                    "id": "1",
                    "output_type": "default"
                }
            ],
            "footer": "",
            "header": ""
        },
        "role": "agent",
        "feedback": null,
        "created_at": "2025-11-03 12:28:32.174000"
    }
]

Conversations

Create a conversation

POST /v1/conversations/
Creates a new conversation for an end user.

curl -sS https://connect.adopt.ai/v1/conversations/ \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "conversation_id": "conv_123"
}

List conversations (paginated)

GET /v1/conversations/ Query parameters:

page (int, default 1, min 1)
limit (int, default 20, min 1, max 100)
created_at_from, created_at_to (ISO date strings or null)
updated_at_from, updated_at_to (ISO date strings or null)

curl -sS "https://connect.adopt.ai/v1/conversations/?page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "conversations": [
    {
      "conversation_id": "conv_123",
      "created_at": "2025-09-05T10:00:00Z",
      "updated_at": "2025-09-05T11:00:00Z"
    }
  ],
  "total_count": 42,
  "has_next_page": true,
  "has_previous_page": false
}

Messages

Send a message

POST /v1/conversations/{conversation_id}/messages
Adds a new message to an existing conversation and generates an AI response. Optionally stream the reply.

curl -sS https://connect.adopt.ai/v1/conversations/conv_123/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "message_request": {
          "conversation_id":"conv_123",
          "message":"How do I reset my password?",
          "workflow_params":{"flow_id":"reset_password_v2"},
          "security_params":{"end_user_id":"user_789"}
        },
        "stream": false
      }'

Request body

{
  "message_request": {
    "conversation_id": "conv_123",
    "message": "How do I reset my password?",
    "base_url": "",
    "app_base_url": "",
    "workflow_params": { "flow_id": "reset_password_v2" },
    "security_params": { "end_user_id": "user_789" },
    "additional_metadata_values": { "followups_clickable": true }
  },
  "stream": false
}

Response

{
  "message_id": "msg_456",
  "conversation_id": "conv_123",
  "role": "assistant",
  "content": "You can reset your password from Settings → Security..."
}

Get conversation messages

GET /v1/conversations/{conversation_id}/messages
Retrieves paginated messages for a conversation.

curl -sS https://connect.adopt.ai/v1/conversations/conv_123/messages \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "conversation_id": "conv_123",
  "messages": [
    {
      "message_id": "msg_001",
      "conversation_id": "conv_123",
      "role": "user",
      "content": "Hi",
      "created_at": "2025-09-05T10:00:00Z",
      "updated_at": "2025-09-05T10:00:00Z"
    }
  ],
  "total_count": 12,
  "has_next_page": false,
  "has_previous_page": true
}

Errors

Validation failures return 422 Unprocessable Entity with a standard structure:

{
  "detail": [
    {
      "loc": ["body", "message_request", "message"],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}

End-to-end example

# 1) Get token
TOKEN=$(curl -sS https://connect.adopt.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"YOUR_CLIENT_ID","secret":"YOUR_SECRET"}' \
  | jq -r '.access_token')

# 2) Create conversation
CONV=$(curl -sS https://connect.adopt.ai/v1/conversations/ \
  -H "Authorization: Bearer $TOKEN")
CONV_ID=$(echo "$CONV" | jq -r '.conversation_id')

# 3) Send message
curl -sS https://connect.adopt.ai/v1/conversations/$CONV_ID/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"message_request\": {\"conversation_id\":\"$CONV_ID\",\"message\":\"Hello!\"}}"

Security

Scheme: HTTP Bearer
Header: Authorization: Bearer <token>
Defined in OpenAPI as JWTBearer

Our Products

Workflows & Use Cases

Features

Authentication

JavaScript SDK

API

Base URLs

Authentication

Action Logs

List Action Logs

Get Messages for an Action Log

Conversations

Create a conversation

List conversations (paginated)

Messages

Send a message

Get conversation messages

Errors

End-to-end example

Security

​Base URLs

​Authentication

​Action Logs

​List Action Logs

​Get Messages for an Action Log

​Conversations

​Create a conversation

​List conversations (paginated)

​Messages

​Send a message

​Get conversation messages

​Errors

​End-to-end example

​Security

Base URLs

Authentication

Action Logs

List Action Logs

Get Messages for an Action Log

Conversations

Create a conversation

List conversations (paginated)

Messages

Send a message

Get conversation messages

Errors

End-to-end example

Security