Groups

Creating a group automatically adds the creator as owner. The owner can't leave via /leave — they must transfer ownership or delete the group first.

Source: apps/api/src/routes/client/groups.ts.

Endpoints

Method	Path	Description
POST	`/client/groups`	Create a group (caller becomes owner).
GET	`/client/groups/mine`	Groups the caller is a member of.
GET	`/client/groups/search`	Search public groups by name (ILIKE, escaped).
POST	`/client/groups/:groupId/join`	Join a public group.
POST	`/client/groups/:groupId/leave`	Leave a group (owner cannot).
GET	`/client/groups/:groupId/members`	List members with user display info.

POST /client/groups

Request (`CreateGroupInput`)

Field	Type	Required	Default
`name`	string	yes	—
`description`	string	no	null
`avatar_url`	string	no	null
`is_public`	boolean	no	true
`max_members`	number	no	100
`metadata`	object	no	`{}`

Response 201

Group row. The caller is inserted into group_members with role = 'owner' in the same tx.

Try it:

POST/client/groups

client auth

curl -X POST 'https://api.amba.dev/client/groups'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/groups' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /client/groups/mine

Response 200

{ "data": [{ "role": "owner", "groups": { "id": "…", "name": "…" } }] }

Try it:

GET/client/groups/mine

client auth

curl -X GET 'https://api.amba.dev/client/groups/mine'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/groups/mine' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

GET /client/groups/search

Query

Param	Default	Description
`q`	`""`	Name search (ILIKE, metacharacters escaped).
`limit`	20
`offset`	0

Response 200

{ "data": [{ "id": "…", "name": "…" }], "total": 42, "offset": 0, "limit": 20 }

Try it:

GET/client/groups/search

client auth

curl -X GET 'https://api.amba.dev/client/groups/search'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/groups/search' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/groups/:groupId/join

Response 201

Group member row.

Errors

404 NOT_FOUND — group doesn't exist.
403 NOT_PUBLIC — group is not public.
409 GROUP_FULL — group has hit max_members.
500 JOIN_FAILED.

Try it:

POST/client/groups/%7B%7BgroupId%7D%7D/join

client auth

curl -X POST 'https://api.amba.dev/client/groups/%7B%7BgroupId%7D%7D/join'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/groups/{groupId}/join' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/groups/:groupId/leave

Response 200

{ "data": { "left": true } }

Errors

400 OWNER_CANNOT_LEAVE.
500 LEAVE_FAILED.

Try it:

POST/client/groups/%7B%7BgroupId%7D%7D/leave

client auth

curl -X POST 'https://api.amba.dev/client/groups/%7B%7BgroupId%7D%7D/leave'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/groups/{groupId}/leave' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /client/groups/:groupId/members

{
  "data": [
    {
      "group_id": "…",
      "app_user_id": "…",
      "role": "owner",
      "joined_at": "…",
      "app_users": { "id": "…", "display_name": "…", "avatar_url": "…" }
    }
  ]
}

Try it:

GET/client/groups/%7B%7BgroupId%7D%7D/members

client auth

curl -X GET 'https://api.amba.dev/client/groups/%7B%7BgroupId%7D%7D/members'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/groups/{groupId}/members' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

On this page