---
title: "Create a team"
method: POST
path: "/api/v1/teams"
---

# Create a team

`POST /api/v1/teams`

Creates a new team and returns the created team object. The authenticated
user becomes the team's owner.

When `app` is supplied, the request is scoped to that app and the caller
must hold the corresponding app scope. Omit `org` unless you want the team
pinned to a specific organization. A default chat thread is provisioned for
the team automatically after creation.

## Request body

- object
  - `acl` object — Access control configuration for the team. Controls who can discover and join the team.
    - `add` object[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `grants` object[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `remove` object[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
      - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
  - `description` string — Optional human-readable description of the team's purpose.
  - `metadata` object — Arbitrary key-value pairs you can attach to the team for your own use. Values must be strings.
  - `name` string, required — Display name for the team.
  - `org` string — Organization ID (`org_...`) to associate the team with. Omit to create the team without an org affiliation.

## Response `200`

Successful response

- Team — A team within an organization, used to group users and agents and scope resources like configs, agents, and tasks.
  - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
    - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
      - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
  - `app` string — ID of the developer application this team belongs to (`dap_...`). `null` if the team is not scoped to an app.
  - `badges` object — Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.
  - `created_at` string, date-time — When this team was created (ISO 8601).
  - `description` string — Human-readable description of the team's purpose. `null` if not set.
  - `id` string, required — Team ID (`tem_...`).
  - `membership_status` string — The authenticated viewer's role on this team. One of `"owner"`, `"admin"`, or `"member"`. `null` if the viewer is not a member.
  - `metadata` object — Arbitrary key-value metadata attached to this team. Returns an empty object when no metadata has been set.
  - `name` string — Display name of the team.
  - `org` string — ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.
  - `sandbox` string — ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.
  - `slug` string — URL-safe slug for the team, derived from the team name. `null` if not set.
  - `updated_at` string, date-time — When this team was last updated (ISO 8601).

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - app scope required
- `422` — Validation failed

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)