---
title: "List teams"
method: GET
path: "/api/v1/teams"
---

# List teams

`GET /api/v1/teams`

Returns a paginated list of teams visible to the authenticated user, ordered
by creation time descending. Use `membership` to narrow results to teams the
caller has joined or teams they are eligible to join based on their ACL
visibility.

Supports full-text search across team name and description via `search`, and
structured metadata filtering via `metadata`. When `app` is present, results
are scoped to that app and the caller must hold the corresponding app scope.

## Query parameters

- `membership` string
- `search` string
- `page_size` integer
- `page` integer
- `metadata` object — A recursive boolean expression tree for filtering records by their JSON metadata field. Each node is either a group (`and`, `or`, `not`) with nested `clauses`, or a leaf predicate (`eq`, `contains`, `exists`) that targets a specific path inside the metadata object. Leaf predicates use `path` (an array of key segments) to address nested values. Operator notes: - `eq` performs deep JSONB equality on the value at `path`. - `contains` checks whether the stored metadata structurally contains the given value; this is the only operator backed by the GIN index and is preferred for performance. - `exists` checks whether `path` is present in the metadata object; a key whose value is explicitly `null` still satisfies this predicate. - `and` and `or` accept two or more `clauses`; `not` accepts exactly one. The legacy flat shape (`type: "metadata"`, `key`, `value`) is still accepted and is treated as an `eq` predicate. Prefer the structured form for new integrations.
  - `clause` object — Single child expression node. Alternative to `clauses` when `operator` is `not`.
  - `clauses` object[] — Array of child expression nodes. Required for `and` and `or` (two or more items) and `not` (exactly one item).
  - `key` string — Deprecated. Top-level metadata key; equivalent to a single-element `path`. Use `path` instead.
  - `operator` 'and' | 'contains' | 'eq' | 'exists' | 'not' | 'or' — The boolean group operator (`and`, `or`, `not`) or leaf predicate operator (`eq`, `contains`, `exists`) for this node.
  - `path` string[] — Ordered key segments addressing a nested location inside the metadata object, e.g. `["collaborations", "org_123"]`.
  - `type` string — Deprecated. Legacy discriminator; `type: "metadata"` combined with `key`/`value` is treated as an `eq` predicate. Use `operator` instead.
  - `value` unknown

## Response `200`

Successful response

- object — Paginated list of teams matching the query.
  - `data` object[], required — Array of team objects for the current page.
    - `acl` object — Access control list governing visibility and join permissions for this team. `null` when no ACL restrictions are applied and the team inherits default access rules.
      - `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"`.
    - `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).
  - `has_next` boolean, required — `true` if there is a subsequent page of results.
  - `has_prev` boolean, required — `true` if there is a preceding page of results.
  - `page` integer, required — The current page number.
  - `page_size` integer, required — The number of results per page.
  - `total_entries` integer, required — Total number of teams matching the query across all pages.
  - `total_pages` integer, required — Total number of pages given the current `page_size`.

## Other responses

- `400` — Bad request - invalid metadata filter
- `401` — Unauthorized
- `403` — Forbidden - app scope required

---

[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)