Teams API¶

The Teams API manages team ownership and membership within the Farm platform.

Base Path¶

/api/v1/teams

Endpoints¶

Method	Path	Description	Auth
`POST`	`/api/v1/teams`	Create a new team	Admin
`GET`	`/api/v1/teams`	List all teams	User
`GET`	`/api/v1/teams/:id`	Get team by ID	User
`PATCH`	`/api/v1/teams/:id`	Update a team	Admin
`DELETE`	`/api/v1/teams/:id`	Delete a team	Admin
`POST`	`/api/v1/teams/:id/members/:userId`	Add member to team	Admin
`DELETE`	`/api/v1/teams/:id/members/:userId`	Remove member from team	Admin
`GET`	`/api/v1/teams/:id/members`	List team members	User
`GET`	`/api/v1/teams/:id/components`	List team's components	User

Team Types¶

Teams are categorized by type:

Type	Description
`dev`	Development team
`infra`	Infrastructure / SRE team
`security`	Security team
`data`	Data engineering team
`platform`	Platform engineering team
`other`	Other team type

Create Team¶

POST /api/v1/teams
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "platform-engineering",
  "displayName": "Platform Engineering",
  "type": "platform",
  "description": "Core platform team",
  "contactEmail": "platform@example.com",
  "slackChannel": "#platform-eng"
}

Response (201)¶

{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "name": "platform-engineering",
  "displayName": "Platform Engineering",
  "type": "platform",
  "description": "Core platform team",
  "contactEmail": "platform@example.com",
  "slackChannel": "#platform-eng",
  "metadata": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

List All Teams¶

Supports pagination via skip and take query parameters (defaults: skip=0, take=20, max take=100).

GET /api/v1/teams?skip=0&take=20
Authorization: Bearer <token>

Paginated Response (200)¶

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "platform-engineering",
      "displayName": "Platform Engineering",
      "type": "platform"
    }
  ],
  "total": 5,
  "skip": 0,
  "take": 20
}

Get Team by ID¶

GET /api/v1/teams/:id
Authorization: Bearer <token>

Update Team¶

PATCH /api/v1/teams/:id
Content-Type: application/json
Authorization: Bearer <token>

{
  "description": "Updated description"
}

Delete Team¶

DELETE /api/v1/teams/:id
Authorization: Bearer <token>

Returns 204 No Content on success.

Member Management¶

Add Member¶

POST /api/v1/teams/:id/members/:userId
Authorization: Bearer <token>

Returns 201 Created with the updated team (including members).

Remove Member¶

DELETE /api/v1/teams/:id/members/:userId
Authorization: Bearer <token>

Returns 204 No Content on success.

List Members¶

GET /api/v1/teams/:id/members
Authorization: Bearer <token>

Returns an array of user objects belonging to the team.

Team Components¶

GET /api/v1/teams/:id/components
Authorization: Bearer <token>

Returns all catalog components owned by the team (matched by component.owner = team.name).

Component Ownership¶

Components can be assigned to a team via the teamId field:

POST /api/v1/catalog/components
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "my-service",
  "kind": "service",
  "owner": "platform-engineering",
  "teamId": "550e8400-e29b-41d4-a716-446655440010",
  "lifecycle": "production"
}

When a team is deleted, the teamId on associated components is set to NULL (components are not deleted).