Skip to main content
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

​
Authentication

To call any API, you’ll need a clientId and secret. You can generate these from the Adopt Platform:
  1. Go to Settings → Profile → Personal Tokens
  2. Click “Generate Token”
  3. Copy the clientId and secret
  4. 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