Teams

Manage organizational teams and their hierarchy. Teams represent groups of employees and contractors who work together, and they can be arranged in a tree structure with parent-child relationships.

Endpoints

Method	Path	Description
GET	/org/:orgId/teams	List teams
GET	/org/:orgId/teams/:id	Get team
POST	/org/:orgId/teams	Create team
PATCH	/org/:orgId/teams/:id	Update team
DELETE	/org/:orgId/teams/:id	Delete team

---

List Teams

GET /org/:orgId/teams

Returns a paginated list of teams in the organization.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Records per page (max 200)
search	string	—	Search by name or description
sortBy	string	name	Sort field
sortDir	string	asc	asc or desc
scenarioId	string	—	Scenario ID for what-if queries

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams?sortBy=name&limit=50" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2",
      "name": "Platform Engineering",
      "teamType": "engineering",
      "description": "Core infrastructure and developer tools team.",
      "parentTeamId": "clx1e2n3g4r5o0t6",
      "metadata": {},
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    },
    {
      "id": "clx1e2n3g4r5o0t6",
      "name": "Engineering",
      "teamType": "department",
      "description": "All engineering teams.",
      "parentTeamId": null,
      "metadata": {},
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 18,
    "hasNextPage": false
  }
}

---

Get Team

GET /org/:orgId/teams/:id

Returns a single team by ID.

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "Platform Engineering",
    "teamType": "engineering",
    "description": "Core infrastructure and developer tools team.",
    "parentTeamId": "clx1e2n3g4r5o0t6",
    "metadata": {},
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2025-11-20T14:00:00Z"
  }
}

---

Create Team

POST /org/:orgId/teams

Creates a new team.

Request Body

{
  "name": "Data Platform",
  "teamType": "engineering",
  "description": "Data infrastructure and analytics pipelines.",
  "parentTeamId": "clx1e2n3g4r5o0t6"
}

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Platform",
    "teamType": "engineering",
    "description": "Data infrastructure and analytics pipelines.",
    "parentTeamId": "clx1e2n3g4r5o0t6"
  }'

Example Response

{
  "data": {
    "id": "clx3d4e5f6g7h8i9",
    "name": "Data Platform",
    "teamType": "engineering",
    "description": "Data infrastructure and analytics pipelines.",
    "parentTeamId": "clx1e2n3g4r5o0t6",
    "metadata": {},
    "createdAt": "2026-03-11T09:40:00Z",
    "updatedAt": "2026-03-11T09:40:00Z"
  }
}

Status: 201 Created

---

Update Team

PATCH /org/:orgId/teams/:id

Updates one or more fields on an existing team. Only include the fields you want to change.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Platform & Infrastructure",
    "description": "Core infrastructure, developer tools, and cloud platform."
  }'

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "Platform & Infrastructure",
    "teamType": "engineering",
    "description": "Core infrastructure, developer tools, and cloud platform.",
    "parentTeamId": "clx1e2n3g4r5o0t6",
    "metadata": {},
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2026-03-11T09:45:00Z"
  }
}

---

Delete Team

DELETE /org/:orgId/teams/:id

Deletes a team. Teams with active employee or contractor allocations cannot be deleted until those allocations are removed or reassigned.

Example Request

curl -X DELETE "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/teams/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..."

Status: 204 No Content

---

Team Hierarchy

Teams support a single-parent hierarchy through the parentTeamId field. A team with parentTeamId: null is a top-level team. You can build the full tree client-side by following parentTeamId references.

Example hierarchy:

Engineering (parentTeamId: null)
  ├── Platform Engineering (parentTeamId: "clx1e2n3g4r5o0t6")
  ├── Product Engineering (parentTeamId: "clx1e2n3g4r5o0t6")
  │   ├── Payments Team (parentTeamId: "clx7p8r9o0d1")
  │   └── Growth Team (parentTeamId: "clx7p8r9o0d1")
  └── Data Platform (parentTeamId: "clx1e2n3g4r5o0t6")

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
name	string	Yes	Team name
teamType	string	No	Category (e.g., "engineering", "department", "squad")
description	string	No	Team description
parentTeamId	string	No	ID of the parent team (null = top-level)
metadata	object	No	Arbitrary JSON metadata (default: {})
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)