---
title: "Create or Update Team"
method: POST
path: "/v2/teams"
tags: ["Teams"]
---

# Create or Update Team

`POST /v2/teams`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/teams`
- Auth: HTTP bearer

Create a new team or update an existing one. Use this to set up team workspaces for collaboration. To create: provide a name (id is auto-generated). To update: provide the team_id (requires admin permissions). The creator automatically becomes team admin. Returns: team id, name, logo, and invite_link for sharing with others.

## Request body

- UpsertTeamRequest: Request body for creating or updating a team
  - `name` string, required
  - `team_id` string
  - `logo` string
  - `domain` string, nullable: Corporate email domain (e.g. "acme.com") used for domain-based team discovery

## Response `200`

Team created or updated successfully

- object
  - `data` UpsertTeamResponse, required: Response after creating or updating a team
    - `id` string, required
    - `name` string, required
    - `logo` string, nullable, required
    - `invite_link` string, required
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `404`: Team not found
- `409`: Free workspace limit reached (meta.code FREE_WORKSPACE_LIMIT)

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)