> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Overview

> Create, list, update, and archive LangWatch teams programmatically. Designed for automated provisioning and cleanup of team structures.

## Intro

The Teams API lets you manage LangWatch teams via REST. Teams are organizational units that group projects and members together.

This API is designed for service-to-service automation (e.g. provisioning team structures for new departments, cleaning up orphaned teams from test runs), not for end-user access.

## Authentication

The Teams API requires an **organization-level API key** with `team:manage` permission (created in Settings > API Keys). Pass it as a Bearer token:

```http theme={null}
Authorization: Bearer sk-lw-<id>_<secret>
```

Project API keys (`X-Auth-Token`) cannot be used here, because they lack organization context.

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v1/teams` | List all teams in the organization |
| `POST` | `/api/v1/teams` | Create a new team |
| `GET` | `/api/v1/teams/{id}` | Get team details |
| `PATCH` | `/api/v1/teams/{id}` | Update a team |
| `DELETE` | `/api/v1/teams/{id}` | Archive a team (soft-delete) |
| `GET` | `/api/v1/teams/{id}/members` | List team members |
| `POST` | `/api/v1/teams/{id}/members` | Add a member to the team |
| `DELETE` | `/api/v1/teams/{id}/members/{userId}` | Remove a member from the team |
| `GET` | `/api/v1/teams/{id}/projects` | List projects in the team |

## Errors

Every refusal carries a stable `code`. Branch on that, not on the message.

| Code | Status | Meaning |
| - | - | - |
| `team_not_found` | 404 | No such team in this organization, or it is archived |
| `team_name_taken` | 409 | Another team here already uses that name |
| `team_member_already_added` | 409 | They already hold that role on the team |
| `team_membership_not_found` | 404 | They hold no role on this team |
| `user_not_in_organization` | 422 | The user is not a member of this organization |
| `personal_workspace_not_managed_here` | 403 | The team is somebody's personal workspace |

## Soft Delete

`DELETE` does not permanently remove a team. It sets an `archivedAt` timestamp, making the team invisible to list and get operations. Archived teams can still be referenced in historical data (e.g. past project associations).

## Typical Flow

1. Create an admin API key in Settings > API Keys with `team:manage` permission
2. Call `POST /api/v1/teams` with a team name
3. Use the returned team `id` when creating projects via the Projects API, or later move an existing project by updating its `teamId`

```bash theme={null}
# Create team
curl -X POST https://app.langwatch.ai/api/v1/teams \
  -H "Authorization: Bearer sk-lw-..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering"}'

# Use team ID to create a project
curl -X POST https://app.langwatch.ai/api/v1/projects \
  -H "Authorization: Bearer sk-lw-..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "teamId": "<team_id>", "language": "python", "framework": "langchain"}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.