Chat with a Custodian

You can chat with a deployed Custodian (single app) or a Custodian Squad (multi-custodian app) over HTTP. Each has its own chat endpoint.

The fastest way to chat is with the Python SDK, which manages session state and model configuration for you. The raw HTTP endpoints below are equivalent and useful when you call Custodian Labs from another language or a backend service.

Chat with a single Custodian

Endpoint

POST /apps/{app_id}/chat

app_id is the deployed Custodian's ID (for example custodian_4f2a91c3e5b7).

Request body

Field	Type	Required	Description
message	string	Yes	The user message.
session_id	string	No	The chat session ID. Omit to start a new session.
model	string	No	Override the model for this request.
temperature	number	No	Sampling temperature between 0 and 2. Default 0.3.

Example

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,
  "research_sources": null,
  "retrieved_contexts": [],
  "messages": []
}

If the Custodian has a response_schema, the structured_output field contains the structured result.

Pass the returned session_id back in the next request to continue the conversation.

Chat with a Custodian Squad

Endpoint

POST /team-apps/{team_app_id}/chat

team_app_id is the deployed Custodian Squad's ID (for example custodians_9b1e8f3a2c4d).

Request body

Same fields as the single Custodian chat request.

Example

curl -X POST "https://platform.custodianlabs.io/v1/team-apps/custodians_9b1e8f3a2c4d/chat" \
  -H "X-API-Key: $CUSTODIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Build a profile for ACME Corp."
  }'

Response

A squad response includes which members handled the request:

{
  "team_app_id": "custodians_9b1e8f3a2c4d",
  "session_id": "session_ff7755aa0001",
  "response": "{\"report\": \"...\", \"verdict\": \"LOW\"}",
  "structured_output": {
    "report": "...",
    "verdict": "LOW"
  },
  "research_sources": null,
  "selected_agent": "Researcher",
  "handoff_path": ["Researcher", "Analyst", "Writer"],
  "contributing_agents": ["Researcher", "Analyst", "Writer"],
  "retrieved_contexts": [],
  "messages": []
}

Key squad fields:

Field	Description
selected_agent	The first member that handled the request.
handoff_path	The order members were called in.
contributing_agents	Every member that contributed.
structured_output	The final structured result, per the squad's response_schema (or the final member's schema).

Using the SDK instead

The Python SDK provides the same capability with less boilerplate:

from custodian_labs import Custodian

custodian = Custodian(model="gpt-4o", system_prompt="You are a helpful assistant.")
app = custodian.deploy()          # app.app_id looks like custodian_...
reply = app.chat("Hello!")

# For a squad:
from custodian_labs import Custodian, CustodianSquad
squad = CustodianSquad(custodians=[...])
squad_app = squad.deploy()
reply = squad_app.chat("Summarize the case and flag any risk.")

See Chat Sessions and Custodian Squads.