Skip to main content
The Agent Graph API lets you build multi-turn AI-powered conversations with Connectly agents entirely in code. You control the full session lifecycle — starting a session, passing customer input, receiving AI responses, and closing the session when the conversation ends.

​
Use cases

Custom chatbots

Embed a Connectly AI agent in your own web or mobile interface.

Sales assistants

Guide customers through product discovery and purchase flows programmatically.

Support automation

Resolve common queries without human escalation, integrated into your existing systems.

​
Session lifecycle

Every Agent Graph interaction follows a three-phase lifecycle:
1

Init

Call POST /agent_graph/init with your businessId and clientKey. Receive a sessionId that identifies this conversation.
2

Invoke

Call POST /agent_graph/invoke (or /invoke_sync) with the sessionId and customer inputEvents. Receive the agent’s response. Repeat for each turn in the conversation.
3

Close

Call POST /agent_graph/close when the conversation is complete to release the session and its resources.

​
Endpoints

MethodEndpointDescription
POST/external/v1/ai/agent_graph/initStart a session — returns sessionId.
POST/external/v1/ai/agent_graph/invokeSend input, receive a streaming NDJSON response.
POST/external/v1/ai/agent_graph/invoke_syncSend input, receive a single aggregated JSON response.
POST/external/v1/ai/agent_graph/closeEnd a session and release its resources.
POST/external/v1/ai/agent_graph/healthCheck API availability.
All endpoints are hosted at https://api.connectly.ai.

​
Authentication

Include your API key in the x-api-key header (lowercase): 
x-api-key: YOUR_API_KEY

​
Required fields

All endpoints (except /init) require these three fields in the request body:
FieldDescription
businessIdYour Connectly business UUID.
clientKeyA stable identifier for the customer (e.g. phone number or internal user ID).
sessionIdThe session ID returned by /init.

​
Streaming vs sync

The /invoke endpoint returns a streaming NDJSON response — one JSON object per line — so your application can begin processing the agent’s reply progressively rather than waiting for the full response. Use /invoke_sync when you don’t need streaming — for example, in a backend job that waits for the complete response before proceeding. It returns a single aggregated JSON object and works with a standard response.json() call.
Never call response.json() on a streaming /invoke response — it will throw a parse error. See NDJSON streaming for the correct approach.

​
End-to-end example (Python)

import requests, json

BASE_URL = "https://api.connectly.ai/external/v1/ai/agent_graph"
HEADERS  = {"Content-Type": "application/json", "x-api-key": "YOUR_API_KEY"}
BUSINESS_ID = "YOUR_BUSINESS_ID"
CLIENT_KEY  = "YOUR_CLIENT_KEY"

# 1. Init
session_id = requests.post(f"{BASE_URL}/init", headers=HEADERS,
    json={"businessId": BUSINESS_ID, "clientKey": CLIENT_KEY}
).json()["response"]["sessionId"]

# 2. Invoke (streaming)
response = requests.post(f"{BASE_URL}/invoke", headers=HEADERS,
    json={
        "businessId": BUSINESS_ID,
        "clientKey": CLIENT_KEY,
        "sessionId": session_id,
        "inputEvents": [{
            "messageEvent": {
                "role": "USER",
                "content": {"textContent": {"text": "What are your store hours?"}}
            }
        }]
    },
    stream=True
)
for raw_line in response.iter_lines():
    if raw_line:
        print(json.loads(raw_line.decode("utf-8")))

# 3. Close
requests.post(f"{BASE_URL}/close", headers=HEADERS,
    json={"businessId": BUSINESS_ID, "clientKey": CLIENT_KEY, "sessionId": session_id})

​
Next steps

Init session

Start a conversation and get a sessionId.

Invoke (stream)

Send input events and parse the NDJSON streaming response.

Invoke (sync)

Get a single aggregated response without streaming.

NDJSON streaming

How to correctly parse the streaming response body.