GET/groups

List groups

list_groups

group:read
A token needs the group:read scope: View groups and namespace usageGranted by mcp_agent, mcp_agent_write, read_api, write_api.Every operation this scope unlocks
Filtered across resources
x-gitmoap-isolation: {"kind":"cross_resource_filtered"}
Paginated
Pass the next_token a page returns to get the next one.

Without a parent, lists top-level groups; with parent_group_id or parent_group_path (not both), lists that group's subgroups. Newest first, and only the groups the caller can see — public ones without signing in — so a page can hold fewer than limit groups while more remain (at most 100 per page).

Parameters

Query

parent_group_idstringoptionalFilter by parent group ID (mutually exclusive with parent_group_path)
parent_group_pathstringoptionalFilter by parent group path (mutually exclusive with parent_group_id)
limitinteger · int32optionalMaximum number of items to return
next_tokenstringoptionalPagination token

Responses

200Groups listedapplication/json

itemsarray of RepositoryGroupView
- The RepositoryGroupView schema
- created_atstring
- created_byUserId (string · uuid)
- full_pathFullPath (string)
- group_idGroupId (string · uuid)
- group_nameEntityName (string)
- updated_atstring
- visibilityVisibilitypublicinternalprivate
- ancestor_group_idsarray of GroupId (string · uuid)optional
- avatarstring or nulloptional
- descriptionstring or nulloptional
- display_namestring or nulloptional
- parent_group_idGroupId (string · uuid) or nulloptional
- verified_domainsarray of Domain (string)optionalThe domains the organization has proven it controls, each through a DNS record. Only an organization — a top-level group — has any; omitted when it has none.
next_tokenstring or nulloptional

200 exampleSynthesized example

400Invalid request (both parent_group_id and parent_group_path provided)application/json

Error codes

BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

400 exampleSynthesized example

401Unauthenticated — no credential, or an invalid oneapplication/json

Error codes

UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

401 exampleSynthesized example

403Forbidden — the caller's access level or token scope is insufficientapplication/json

Error codes

FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

403 exampleSynthesized example

404The parent group named by `parent_group_path` does not existapplication/json

Error codes

NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

404 exampleSynthesized example

CLI

gitmoap groups list

--limitnumberoptionalMaximum number of items to return
--next-tokenstringoptionalPagination token
--parent-group-idstringoptionalFilter by parent group ID (mutually exclusive with parent_group_path)
--parent-group-pathstringoptionalFilter by parent group path (mutually exclusive with parent_group_id)

Used in these guides

Groups

Request

curl "https://api.gitmoap.com/groups" \
  -H "Authorization: Bearer $GITMOAP_TOKEN"

gitmoap groups list

import { createApiClient } from "@gitmoap/backend-types";

const client = createApiClient({
  baseUrl: "https://api.gitmoap.com",
  headers: { Authorization: `Bearer ${process.env.GITMOAP_TOKEN}` },
});

const { data, error } = await client.GET("/groups");

GET /groups HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN

⌘↵

Send to see the sandbox's answer. Nothing leaves your browser.