Chat
Talk to a deployed Custodian Agent or squad over HTTP. The SDKs wrap this with session handling — use raw HTTP from other languages or a backend.
| Target | Endpoint |
|---|---|
| Custodian Agent | POST /apps/{app_id}/chat |
| Squad | POST /team-apps/{team_app_id}/chat |
Request body
| Field | Required | Description |
|---|---|---|
message | Yes | The user message. |
session_id | No | Continue a conversation. Omit to start one. |
model | No | Override the model for this request. |
temperature | No | 0–2, default 0.3. |
curl -X POST "https://platform.custodianlabs.io/v1/apps/custodian_4f2a91c3e5b7/chat" \
-H "X-API-Key: $CUSTODIAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What is your return policy?"}'
Response
{
"app_id": "custodian_4f2a91c3e5b7",
"session_id": "session_ab12cd34ef56",
"model": "gpt-4o",
"response": "You can return items within 30 days...",
"structured_output": null,
"retrieved_contexts": [],
"messages": []
}
Send session_id back on the next request to keep context. structured_output is
populated when the agent has a response_schema.
Squad response
Adds routing detail:
{
"team_app_id": "custodians_9b1e8f3a2c4d",
"session_id": "session_ff7755aa0001",
"response": "...",
"structured_output": { "verdict": "LOW" },
"selected_agent": "Researcher",
"handoff_path": ["Researcher", "Analyst", "Writer"],
"contributing_agents": ["Researcher", "Analyst", "Writer"]
}
| Field | |
|---|---|
selected_agent | First member to handle it. |
handoff_path | Call order. |
contributing_agents | Every member that contributed. |
With an SDK
app = Custodian(model="gpt-4o", system_prompt="You are helpful.").deploy()
app.chat("Hello!")
const app = await new Custodian({ model: "gpt-4o", systemPrompt: "You are helpful." }).deploy();
await app.chat("Hello!");