Squad API: Create, Update, List

Overview

The Squad API provides the three endpoints used to create, update, and list Squads — the multi-assistant call-routing resource described conceptually on the Squads & Handoffs page. All three endpoints live under /squad, and every request requires a Bearer token in the Authorization header.

POST https://api.sulus.ai/squad — creates a new squad.

Request headers:

Request body (application/json): a members array of squad member objects, plus an optional name field.

Response: 201 — returns the created Squad object.

Example creating a two-member squad:

curl -X POST https://api.sulus.ai/squad \
  -H "Authorization: Bearer $SULUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Routing Squad",
    "members": [
      {
        "assistant": {
          "name": "Router",
          "model": {
            "provider": "openai",
            "model": "gpt-4o",
            "messages": [{"role": "system", "content": "Classify inquiries and transfer accordingly."}]
          },
          "firstMessage": "Thanks for calling. How can I help?",
          "firstMessageMode": "assistant-speaks-first"
        }
      },
      {
        "assistant": {
          "name": "Specialist",
          "model": {
            "provider": "openai",
            "model": "gpt-4o",
            "messages": [{"role": "system", "content": "Domain specialist assistant."}]
          }
        }
      }
    ]
  }'

PATCH https://api.sulus.ai/squad/{id} — updates an existing squad.

Path parameters:

Request body: uses the same field shape as create (members, name). Only the fields included in the request body are updated — any field you omit is left unchanged.

Response: 200 — returns the updated Squad object.

curl -X PATCH https://api.sulus.ai/squad/<squad-id> \
  -H "Authorization: Bearer $SULUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Squad Name"
  }'

GET https://api.sulus.ai/squad — returns squads for your account, with optional filtering and pagination.

Query parameters:

Response: 200 — returns an array of Squad objects.

curl -X GET "https://api.sulus.ai/squad?limit=10&createdAtGt=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer $SULUS_API_KEY"

For the conceptual model behind Squads — how handoffs work, context engineering options, and system prompt guidance — see the Squads & Handoffs page. For a fully worked example that pairs this API with a real use case, see the Multilingual Support Squad Template page.

In summary: use POST /squad to create a squad, PATCH /squad/{id} to update specific fields, and GET /squad to list squads with timestamp-based filtering and pagination. All three endpoints authenticate via a Bearer token.