Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified account. locationId is required in the request body.
Session Management:
For the first message in a new session, do not include the
executionIdin the request payload.The API will return an
executionIdalong with the agent response, which uniquely identifies this conversation session.To continue the conversation within the same session, include the
executionIdfrom the previous response in subsequent requests. This allows the agent to maintain conversation context and history across multiple interactions.
POST https://services.leadconnectorhq.com/agent-studio/agent/{agentId}/executeAuthorization
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
Authorization | string | Yes | Bearer token generated from the Leadway portal. See Authentication. | |
Version | string | Yes | 2021-07-28 | API version. |
Path parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
agentId | string | Yes | p1q2r3s4t5u6v7w8x9y0z1a2 |
Query parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
source | string | No | api |
Body
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
message | string | Yes | How can you help me with my marketing? | Message to send to the agent |
executionId | string | No | a1b2c3d4e5f6g7h8i9j0k1l2 | Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Omit this field for the first message in a new session. Include the executionId returned from the previous response to maintain context in subsequent messages. |
inputVariables | object | No | Input variables to pass to the agent. These should match the input variables defined in the agent configuration. | |
versionId | string | No | b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d | Published version ID to execute. If not provided, the latest published production version will be used. |
attachments(object[]): Attachments for the messagetype(string, required): Type of attachment Example:imageimageUrl(string, required): URL of the image attachment Example:https://example.com/image.png
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
locationId | string | Yes | C2QujeCh8ZnC7al2InWR | Account ID |
contactId | string | No | cid_abc123def456 | Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent. |
Responses
200 - Agent executed successfully
success(boolean, required): Success status Example:TrueexecutionId(string, required): Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Use this ID in subsequent requests to continue the conversation. Example:a1b2c3d4e5f6g7h8i9j0k1l2interactionId(string, required): Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId. Example:m9n8o7p6q5r4s3t2u1v0w9x8response(string, required): Agent response text Example:I can help you with various tasks...type(string, required): Response type Example:textnextExpectedInput(string, required): Expected input type for next interaction Example:textgoalCompletion(boolean, required): When end node is added in the graph, this will be true if the agent reached the end node in the graph Example:FalseexecutionStatus(string, required): Execution status Example:completedflowSwitch(boolean, required): Whether flow was switched Example:Falseattachments(object[], required): Response attachmentsgenerativeOutputs(object[], required): Generated outputs
{
"success": true,
"executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
"interactionId": "m9n8o7p6q5r4s3t2u1v0w9x8",
"response": "I can help you with various tasks...",
"type": "text",
"nextExpectedInput": "text",
"goalCompletion": false,
"executionStatus": "completed",
"flowSwitch": false,
"attachments": [],
"generativeOutputs": []
}400 - Agent is not active or invalid request - locationId is required
403 - User does not have required scopes to execute this agent
404 - Agent not found
422 - Unprocessable Entity
{}500 - Internal Server Error
statusCode(number): Example:500message(string): Example:Internal Server Error
{
"statusCode": 500,
"message": "Internal Server Error"
}Example
curl -X POST 'https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Version: 2021-07-28' \
-H 'Content-Type: application/json' \
-d '{
"message": "How can you help me with my marketing?",
"executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
"inputVariables": {
"customerName": "John Doe",
"orderNumber": "ORD-12345"
},
"versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"attachments": [
{
"type": "image",
"imageUrl": "https://example.com/image.png"
}
],
"locationId": "C2QujeCh8ZnC7al2InWR",
"contactId": "cid_abc123def456"
}'const response = await fetch('https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LEADWAY_TOKEN}`,
Version: '2021-07-28',
'Content-Type': 'application/json',
},
body: JSON.stringify({"message": "How can you help me with my marketing?", "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2", "inputVariables": {"customerName": "John Doe", "orderNumber": "ORD-12345"}, "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "attachments": [{"type": "image", "imageUrl": "https://example.com/image.png"}], "locationId": "C2QujeCh8ZnC7al2InWR", "contactId": "cid_abc123def456"}),
});
const data = await response.json();import os, requests
response = requests.request(
'POST',
'https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute',
headers={
'Authorization': f"Bearer {os.environ['LEADWAY_TOKEN']}",
'Version': '2021-07-28',
'Content-Type': 'application/json',
},
json={"message": "How can you help me with my marketing?", "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2", "inputVariables": {"customerName": "John Doe", "orderNumber": "ORD-12345"}, "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "attachments": [{"type": "image", "imageUrl": "https://example.com/image.png"}], "locationId": "C2QujeCh8ZnC7al2InWR", "contactId": "cid_abc123def456"},
)
data = response.json()<?php
$ch = curl_init('https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('LEADWAY_TOKEN'),
'Version: 2021-07-28',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode({'message': 'How can you help me with my marketing?', 'executionId': 'a1b2c3d4e5f6g7h8i9j0k1l2', 'inputVariables': {'customerName': 'John Doe', 'orderNumber': 'ORD-12345'}, 'versionId': 'b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d', 'attachments': [{'type': 'image', 'imageUrl': 'https://example.com/image.png'}], 'locationId': 'C2QujeCh8ZnC7al2InWR', 'contactId': 'cid_abc123def456'}),
]);
$data = json_decode(curl_exec($ch), true);