# Team API

The Uptizm API has 6 endpoints on this resource, one section each.

## List team members

`GET /team/members`

The members of the key's team with their roles.

- URL: `https://api.uptizm.com/v1/team/members`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `team:read`
- Tag: Team
- operationId: `v1.team.members.index`

### Response 200

Content type: `application/json`.

- `data` (array of TeamMemberResource, required)
  - `id` (string, required)
  - `name` (string, required)
  - `email` (string or null, required)
  - `role` (string, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Change a member's role

`PUT /team/members/{user}`

Changes a member's role. A key can never grant `admin`.

- URL: `https://api.uptizm.com/v1/team/members/{user}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `team:manage`
- Tag: Team
- operationId: `v1.team.members.update`

### Parameters

- `user` (path, string, required)

### Request body

Content type: `application/json`.

- `role` (string, one of `"admin"`, `"editor"`, `"member"`, required)

### Response 200

Content type: `application/json`.

- `data` (TeamMemberResource, required)
  - `id` (string, required)
  - `name` (string, required)
  - `email` (string or null, required)
  - `role` (string, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Remove a team member

`DELETE /team/members/{user}`

Removes a member from the team.

- URL: `https://api.uptizm.com/v1/team/members/{user}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `team:manage`
- Tag: Team
- operationId: `v1.team.members.destroy`

### Parameters

- `user` (path, string, required)

### Response 204

No body.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## List pending invitations

`GET /team/invitations`

The team's pending invitations.

- URL: `https://api.uptizm.com/v1/team/invitations`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `team:read`
- Tag: Team
- operationId: `v1.team.invitations.index`

### Response 200

Content type: `application/json`.

- `data` (array of string, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Invite a member

`POST /team/invitations`

Invites an email address to the team. A key can never invite with role `admin`.

- URL: `https://api.uptizm.com/v1/team/invitations`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `team:manage`
- Tag: Team
- operationId: `v1.team.invitations.store`

### Parameters

- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `email` (string, email, max length 255, required)
- `role` (string, one of `"admin"`, `"editor"`, `"member"`, required)

### Response 201

Content type: `application/json`.

- `data` (JsonResource, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Cancel an invitation

`DELETE /team/invitations/{invitation}`

Cancels a pending invitation.

- URL: `https://api.uptizm.com/v1/team/invitations/{invitation}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `team:manage`
- Tag: Team
- operationId: `v1.team.invitations.destroy`

### Parameters

- `invitation` (path, string, required)

### Response 204

No body.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md