API Reference
Create team
POST /api/v1/teams — create a team of agents.
Creates a team. The body uses the same field names, and is checked by the same rules, as Studio's Team Builder.
POST /api/v1/teamsRequest body
| Field | Type | Required | Description |
|---|---|---|---|
name | string (1–128 chars) | Yes | |
coordination_mode | handoff | dynamic_delegation | parallel | plan_execute | Yes | See Coordination modes. |
lead_type | managed | member | Yes | A managed lead is a model of its own; a member lead is one of the agents. |
members | list of { agent_id, role?, sort_order?, delegate_eligible? } | Yes | The agents; at least two must be able to receive work. Every member counts except a promoted lead, which counts only when lead_member_delegate_eligible is true (a member's own delegate_eligible, default true, is stored but not counted). Each agent once. |
lead_llm_config_id | string (UUID) | When lead_type is managed | The LLM configuration the lead uses. |
lead_model_id | string | No | The lead's model on that configuration. |
lead_member_agent_id | string (UUID) | When lead_type is member | The agent that leads. Added to members if it is not there. |
lead_member_delegate_eligible | boolean | No | Whether the lead agent can also be delegated work. |
lead_member_can_answer_directly | boolean | No | Whether the lead agent may answer without delegating. |
max_iterations | integer 1–20 | When coordination_mode is plan_execute | The plan-and-execute loop's ceiling. |
project_id | string (UUID) | null | No | Org-scoped keys: a project your organization owns; omitted or null means your organization's default project. Every team belongs to a project. A project-scoped key always creates in its own project. |
description, goal, instructions, lead_instructions | string | No | Free text. instructions and lead_instructions reach the models. |
status | active | paused | draft | archived | No | |
determine_input_for_members, add_team_history_to_members, share_member_interactions, add_name_to_context, add_datetime_to_context, add_history_to_context | boolean | No | The behaviour toggles described in Teams. add_datetime_to_context tells the lead and every member the current date and time. |
num_history_runs | integer 0–100 | No | How many earlier runs of a session to include when add_history_to_context is on. |
budget_cap_json, policy_json | object | null | No | The team's budget cap and policy, as Studio stores them. |
Every agent and LLM configuration you name must belong to your organization.
Response
201 Created — the team, in the shape of Get team, with currentVersion: 1.
Errors
| Status | error | When |
|---|---|---|
400 | validation error | A field fails validation, or a rule above is broken — for example a managed lead with no lead_llm_config_id. |
422 | validation_error | An agent or LLM configuration is not in your organization (field names which), or the team has fewer than two agents that can receive work. |
422 | project_not_found | project_id is not a project of your organization. |
Example
curl -X POST https://api.elizon.ai/api/v1/teams \
-H "X-API-Key: elz_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Escalations",
"coordination_mode": "dynamic_delegation",
"lead_type": "managed",
"lead_llm_config_id": "8b1e...",
"lead_model_id": "gpt-4o",
"add_datetime_to_context": true,
"members": [{ "agent_id": "a1..." }, { "agent_id": "a2..." }]
}'