# Teams and account

Who a token acts as, the teams it reaches, a team's settings, overview and notifications.

Source: https://docs.orbits.africa/api/teams

Call `GET /v1/me` first: it confirms the token works and lists the one team (and project, for a project-limited token) it reaches. Every other route is under `/v1/teams/{team}`, where `{team}` is the team's slug or its `team_` id. Members, invites, tokens and the team's security rules are managed in the dashboard: an API token can't reach them (see [Authentication](https://docs.orbits.africa/api/authentication)).

Endpoints:

- `GET /v1/me`: Current user
- `GET /v1/teams`: Teams the caller belongs to
- `GET /v1/teams/{team}`: Get a team
- `PATCH /v1/teams/{team}`: Rename, change slug, avatar, default region, or security rules
- `GET /v1/teams/{team}/overview`: Dashboard overview for a time range
- `GET /v1/teams/{team}/notifications`: Notifications for the caller in this team
- `POST /v1/teams/{team}/notifications`: Mark notifications read

## The team object



- `id` (string, required)
- `name` (string, required)
- `slug` (string, required)
- `avatar_url` (string or null): A path on this API (`/v1/teams/{id}/avatar?v=…`) for an uploaded avatar.
- `default_region` (string)
- `role` (string, required): One of `owner`, `admin`, `member`, `viewer`.
- `require_two_factor` (boolean): Members without two-factor are refused on this team's routes (403).
- `session_max_age_days` (integer): A member whose session started longer ago is refused on this team (403) until they sign in again. The settings page offers 1, 7 and 30: every session ends after 30 days anyway, so a longer limit never applies.
- `inviters` (string): `owners`: owners and admins invite. `members`: members may too (as member or viewer only). One of `owners`, `members`.
- `sign_in_methods` (array of string): How members may have signed in. A member whose session used another method (or one from before methods were recorded) is refused on this team (403) until they sign in again with one of these.
- `plan` (string, required): One of `free`, `pro`.
- `billing_alert` (null or BillingAlert): The owners' billing notice (see `GET .../billing` `banner`), so the app shell can show it without another call. Null for everyone else and most of the time.
  - `kind` (string, required): Always `downgraded`.
  - `at` (string)
  - `amount_ngn` (integer or null)
  - `charge` (string): One of `automatic`, `manual`.
  - `grace_ends_at` (string)
  - `ends_at` (string)
- `created_at` (string, required)
## Current user

```http
GET /v1/me
```

Current user, with their teams and each team's newest projects, so the app can render its shell from one call.

Token: any API token (`read` or `full`).

Example:

```sh
curl "https://api.theorbits.app/v1/me" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "email": "ada@example.com",
  "name": "my-app",
  "username": null,
  "avatar_url": "https://my-app.theorbits.app",
  "two_factor_enabled": false,
  "sign_in_methods": [
    "github"
  ],
  "time_zone": null,
  "product_updates": false,
  "session": {
    "method": "email",
    "started_at": "2026-11-10T09:30:00Z"
  },
  "token": {
    "id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "team_id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "access": "full",
    "project_id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "created_at": "2026-11-10T09:30:00Z"
  },
  "teams": [
    {
      "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "name": "My Team",
      "slug": "my-app",
      "avatar_url": "https://my-app.theorbits.app",
      "default_region": "abj-1",
      "role": "owner",
      "require_two_factor": false,
      "session_max_age_days": 1,
      "inviters": "owners",
      "sign_in_methods": [
        "email"
      ],
      "plan": "free",
      "billing_alert": {
        "kind": null,
        "at": null,
        "amount_ngn": null,
        "charge": null
      },
      "created_at": "2026-11-10T09:30:00Z",
      "project_count": 1,
      "projects": [
        {
          "id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
          "slug": "my-app",
          "name": "my-app",
          "free_address": "storefront.theorbits.app",
          "workload": null,
          "source": null,
          "source_kind": "git",
          "build": {
            "framework": null,
            "install_command": null,
            "build_command": null,
            "output_directory": null,
            "ignore_command": null,
            "changed_by": null,
            "changed_at": null
          },
          "framework_version": "15",
          "node_version": "22.x",
          "region": "abj-1",
          "status": "pending",
          "paused": false,
          "git": {
            "deploy_on_push": null,
            "preview_pull_requests": null,
            "comment_on_pull_requests": null
          },
          "preview_protection": "team_members",
          "production_url": "https://my-app.theorbits.app",
          "latest_deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
          "latest_deployment": null,
          "thumbnail_url": "https://my-app.theorbits.app",
          "thumbnail_color": "#7c3aed",
          "created_at": "2026-11-10T09:30:00Z",
          "updated_at": "2026-11-10T09:30:00Z"
        }
      ]
    }
  ]
}
```

Errors:

- `401`: Missing or invalid credentials.
## Teams the caller belongs to

```http
GET /v1/teams
```

Teams the caller belongs to.

Token: any API token (`read` or `full`).

Query parameters:

- `limit` (integer): From 1 to 100. Defaults to `25`.
- `cursor` (string)

Example:

```sh
curl "https://api.theorbits.app/v1/teams" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "next_cursor": null,
  "items": [
    {
      "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "name": "My Team",
      "slug": "my-app",
      "avatar_url": "https://my-app.theorbits.app",
      "default_region": "abj-1",
      "role": "owner",
      "require_two_factor": false,
      "session_max_age_days": 1,
      "inviters": "owners",
      "sign_in_methods": [
        "email"
      ],
      "plan": "free",
      "billing_alert": {
        "kind": "upcoming",
        "at": "2026-11-10T09:30:00Z",
        "amount_ngn": null,
        "charge": "automatic"
      },
      "created_at": "2026-11-10T09:30:00Z"
    }
  ]
}
```

Errors:

## Get a team

```http
GET /v1/teams/{team}
```

Get a team.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "name": "My Team",
  "slug": "my-app",
  "avatar_url": "https://my-app.theorbits.app",
  "default_region": "abj-1",
  "role": "owner",
  "require_two_factor": false,
  "session_max_age_days": 1,
  "inviters": "owners",
  "sign_in_methods": [
    "email"
  ],
  "plan": "free",
  "billing_alert": {
    "kind": "upcoming",
    "at": "2026-11-10T09:30:00Z",
    "amount_ngn": null,
    "charge": "automatic"
  },
  "created_at": "2026-11-10T09:30:00Z",
  "notifications": {
    "deploy.failed": {
      "email": "ada@example.com",
      "slack": false
    },
    "deploy.live": {
      "email": "ada@example.com",
      "slack": false
    },
    "domain.attention": {
      "email": "ada@example.com",
      "slack": false
    },
    "member.joined": {
      "email": "ada@example.com",
      "slack": false
    },
    "weekly": {
      "email": "ada@example.com",
      "slack": false
    }
  },
  "members": [
    {
      "user": {
        "id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "email": "ada@example.com",
        "name": "my-app",
        "username": null,
        "avatar_url": "https://my-app.theorbits.app",
        "two_factor_enabled": false
      },
      "role": "owner",
      "status": "active",
      "invite_id": "invite-id",
      "joined_at": "2026-11-10T09:30:00Z",
      "last_active_at": "2026-11-10T09:30:00Z"
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Rename, change slug, avatar, default region, or security rules

```http
PATCH /v1/teams/{team}
```

Rename, change slug, avatar, default region, or security rules.

Changing the slug breaks old dashboard links. All settings require an owner or admin.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.

Body:

- `name` (string)
- `slug` (string)
- `avatar_url` (string or null)
- `default_region` (string): Abuja is the only region in v1. One of `abj-1`.
- `require_two_factor` (boolean)
- `session_max_age_days` (integer): From 1 to 365.
- `inviters` (string): One of `owners`, `members`.
- `sign_in_methods` (array of string): 422 when it leaves out the method the caller signed in with.
- `notifications` (object): Only the switches that change, as `{"deploy.live": {"email": true}}`; the rest stay. 422 on `notifications` for an unknown event or channel.

Example:

```sh
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Team",
    "slug": "my-app",
    "avatar_url": "https://my-app.theorbits.app",
    "default_region": "abj-1",
    "require_two_factor": false,
    "session_max_age_days": 1,
    "inviters": "owners",
    "sign_in_methods": [
      "email"
    ],
    "notifications": {}
  }'
```

Response `200`:

```json
{
  "id": "team_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "name": "My Team",
  "slug": "my-app",
  "avatar_url": "https://my-app.theorbits.app",
  "default_region": "abj-1",
  "role": "owner",
  "require_two_factor": false,
  "session_max_age_days": 1,
  "inviters": "owners",
  "sign_in_methods": [
    "email"
  ],
  "plan": "free",
  "billing_alert": {
    "kind": "upcoming",
    "at": "2026-11-10T09:30:00Z",
    "amount_ngn": null,
    "charge": "automatic"
  },
  "created_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `409`: The request conflicts with current state.
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Dashboard overview for a time range

```http
GET /v1/teams/{team}/overview
```

Dashboard overview for a time range, worked out when asked. `deployments.total` counts deployments started in the range, and `delta_vs_previous` compares it with the range before (the 24 hours, 7 or 30 days before that). `average_build_seconds` is the mean build of those that went ready, 0 when none did. `requests.total` counts requests to any of the team's deployments, production and previews, in the range; `month_to_date` since midnight on the 1st in Lagos. Both are 0 while the log store can't be reached. `projects.failing` and `needs_attention` are the projects whose latest deployment failed. `series` cuts the range into equal slices, oldest first (7 for `24h` and `7d`, 4 for `30d`), and gives each one's deployments, average ready build (0 when none) and requests, so `series.deployments` adds up to `deployments.total`.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `range` (string): One of `24h`, `7d`, `30d`. Defaults to `24h`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/overview" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "range": "range",
  "logs_available": false,
  "projects": {
    "total": 1,
    "failing": 1
  },
  "deployments": {
    "total": 1,
    "delta_vs_previous": 1
  },
  "average_build_seconds": 1,
  "requests": {
    "total": 1,
    "month_to_date": 1
  },
  "series": {
    "deployments": [
      1
    ],
    "average_build_seconds": [
      1
    ],
    "requests": [
      1
    ]
  },
  "needs_attention": [
    {
      "kind": "kind",
      "message": "message",
      "link": "link"
    }
  ]
}
```

Errors:

## Notifications for the caller in this team

```http
GET /v1/teams/{team}/notifications
```

The top bar's notifications: the team activity lines worth a nudge, newest first, with whether the caller has read each. They are a failed deployment (`deployment.failed`), a domain going live (`domain.live`) or stopping pointing at Orbits (`domain.misconfigured`), a certificate that couldn't be issued or isn't renewing (`domain.certificate.failed`), a member joining (`team.member.added`, but not the caller's own) and an alert firing (`alert.fired`). The list goes back 30 days, and no further than when the caller joined the team. `unread_count` counts the unread ones, up to 100, whatever the page.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `limit` (integer): From 1 to 50. Defaults to `20`.
- `cursor` (string)
- `unread` (boolean): Only the ones the caller hasn't read.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/notifications" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "next_cursor": null,
  "items": [
    {
      "id": "act_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "type": "deployment.failed",
      "title": "store failed to deploy",
      "detail": "Missing module 'mdsvex' · main",
      "link": "/teams/rsty-org/projects/store/deployments/dpl_1",
      "project": {
        "id": "id",
        "slug": "my-app",
        "name": "my-app"
      },
      "read": false,
      "created_at": "2026-11-10T09:30:00Z"
    }
  ],
  "unread_count": 1
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Mark notifications read

```http
POST /v1/teams/{team}/notifications
```

Marks notifications read for the caller only. Send `ids` (from `GET /v1/teams/{team}/notifications`) for some, or `all: true` for every one up to now; with `all`, `ids` is ignored. Ids of another team's notifications are ignored.

**Permissions:** Any team member, for their own notifications. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.

Body:

- `ids` (array of string): At most 100 items.
- `all` (boolean)

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/notifications" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "ids"
    ],
    "all": false
  }'
```

Response `204`: Marked.

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
