v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

List 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.

get/api/v1/teams

Query parameters

membershipstring

Filter teams by membership status. "joined" returns only teams the caller is a member of. "joinable" returns ACL-visible teams the caller has not yet joined. Omit to return all visible teams.

searchstring

Full-text search string matched against team name and description.

page_sizeinteger

Number of teams to return per page. Defaults to 25.

pageinteger

Page number to retrieve, starting at 1. Defaults to 1.

clauseobject

Single child expression node. Alternative to clauses when operator is not.

clausesobject[]

Array of child expression nodes. Required for and and or (two or more items) and not (exactly one item).

keystring

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.

pathstring[]

Ordered key segments addressing a nested location inside the metadata object, e.g. ["collaborations", "org_123"].

typestring

Deprecated. Legacy discriminator; type: "metadata" combined with key/value is treated as an eq predicate. Use operator instead.

{"stackTrail":"paths:/api/v1/teams:get:parameters:4:schema:properties:value","oasType":"schema","type":"unknown","description":"The JSON value to compare against the node at `path`. Required for `eq` and `contains` predicates; omitted for `exists`."}

Structured metadata filter expression. Only teams whose metadata satisfies the expression are returned.

Response

Successful response

has_nextboolean required

true if there is a subsequent page of results.

has_prevboolean required

true if there is a preceding page of results.

pageinteger required

The current page number.

page_sizeinteger required

The number of results per page.

total_entriesinteger required

Total number of teams matching the query across all pages.

total_pagesinteger required

Total number of pages given the current page_size.

Example response

{
  "data": [
    {
      "acl": {
        "add": [
          {
            "actions": [
              "read",
              "write"
            ],
            "principal": "string",
            "principal_type": "user"
          }
        ],
        "grants": [
          {
            "actions": [
              "read",
              "write"
            ],
            "principal": "string",
            "principal_type": "user"
          }
        ],
        "remove": [
          {
            "principal": "string",
            "principal_type": "user"
          }
        ]
      },
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "badges": {},
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "id": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "membership_status": "member",
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
      "slug": "example-slug",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "has_next": true,
  "has_prev": true,
  "page": 1,
  "page_size": 1,
  "total_entries": 1,
  "total_pages": 1
}