---
title: "Retrieve a team"
method: GET
path: "/api/v1/teams/{team}"
---

# Retrieve a team

`GET /api/v1/teams/{team}`

Returns the full team object for the given `team` ID, including its current
member list and all associated threads.

The authenticated user must be a member of the team or hold a role that
grants visibility (org admin, app scope). When `app` is supplied, the
caller must hold the corresponding app scope.

## Path parameters

- `team` string, required

## 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
- `404` — Team not found

---

[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/versions/a8772b442f86/schema)