> ## Documentation Index > Fetch the complete documentation index at: https://docs.adopt.ai/llms.txt > Use this file to discover all available pages before exploring further. # External API's > Description of your new file. 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](https://connect.adopt.ai/docs) * **OpenAPI (3.1) spec:** [https://connect.adopt.ai/openapi.json](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**: 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** ```bash theme={null} curl -sS https://connect.adopt.ai/v1/auth/token \ -H "Content-Type: application/json" \ -d '{"clientId":"YOUR_CLIENT_ID","secret":"YOUR_SECRET"}' ``` **Request body** ```json theme={null} { "clientId": "string", "secret": "string" } ``` **Response** ```json theme={null} { "access_token": "string", "refresh_token": "string", "expires_in": 3600, "expires": "2025-09-05T12:00:00Z" } ``` Use the token in the `Authorization` header: ```json theme={null} Authorization: Bearer ``` ## 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** ```bash theme={null} 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** ```json theme={null} [ { "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** ```bash theme={null} 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. ```bash theme={null} curl -sS https://connect.adopt.ai/v1/conversations/ \ -H "Authorization: Bearer $TOKEN" ``` **Response** ```json theme={null} { "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`) ```bash theme={null} curl -sS "https://connect.adopt.ai/v1/conversations/?page=1&limit=20" \ -H "Authorization: Bearer $TOKEN" ``` **Response** ```json theme={null} { "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. ```bash theme={null} 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** ```json theme={null} { "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** ```json theme={null} { "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. ```bash theme={null} curl -sS https://connect.adopt.ai/v1/conversations/conv_123/messages \ -H "Authorization: Bearer $TOKEN" ``` **Response** ```json theme={null} { "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: ```json theme={null} { "detail": [ { "loc": ["body", "message_request", "message"], "msg": "Field required", "type": "value_error.missing" } ] } ``` ## End-to-end example ```json theme={null} # 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 ` * Defined in OpenAPI as `JWTBearer`