OrbitsDocs
esc
    Open Orbits
    API reference · TeamTeams

    Teams and account

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

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

    The team object

    Fields

    • idstringrequired
    • namestringrequired
    • slugstringrequired
    • avatar_urlstring or null

      A path on this API (/v1/teams/{id}/avatar?v=…) for an uploaded avatar.

    • default_regionstring
    • rolestringrequired

      One of owner, admin, member, viewer.

    • require_two_factorboolean

      Members without two-factor are refused on this team's routes (403).

    • session_max_age_daysinteger

      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.

    • invitersstring

      owners: owners and admins invite. members: members may too (as member or viewer only).

      One of owners, members.

    • sign_in_methodsarray 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.

    • planstringrequired

      One of free, pro.

    • billing_alertnull 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.

      Show 6 child fields
      • kindstringrequired

        Always downgraded.

      • atstring
      • amount_ngninteger or null
      • chargestring

        One of automatic, manual.

      • grace_ends_atstring
      • ends_atstring
    • created_atstringrequired

    Current user

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

    GET/v1/me
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Response 200

    The signed-in user with their teams, each with its newest projects.
    • idstringrequired
    • emailstringrequired
    • namestringrequired
    • usernamestring or null

      Their handle: unique, lowercase letters, numbers and dashes. Null until they set one.

    • avatar_urlstring or null

      A path on this API (/v1/users/{id}/avatar?v=…) for an uploaded photo, or an absolute URL from a sign-in provider.

    • two_factor_enabledboolean

      Whether the person has two-factor on. On a team member it is as of their last visit.

    • sign_in_methodsarray of string

      The OAuth providers linked to this account. Email link is always available and is not listed here.

    • time_zonestring or null

      Their IANA time zone for clocks and dates. Null until they set one.

    • product_updatesboolean

      Whether they opted in to product-update emails.

    • sessionobject

      This session, as a team's sign-in method and session length rules see it.

      Show 2 child fields
      • methodstring or null

        api_token when the bearer is an API token. Null for a session from before methods were recorded.

        One of email, github, gitlab, bitbucket, api_token.

      • started_atstring or null

        When the session signed in, or when the API token was made.

    • tokenobject

      Only when the bearer is an API token (orb_live_…), what it may do. Absent for a session.

      Show 5 child fields
      • idstringrequired
      • team_idstringrequired

        The one team the token acts in.

      • accessstringrequired

        One of full, read.

      • project_idstring or nullrequired

        The one project the token is limited to, or null for every project of the team.

      • created_atstringrequired
    • teamsarray of objectrequired

      The teams the caller belongs to (all of GET /v1/teams), each with a preview of its projects.

      Show 15 child fields
      • idstringrequired
      • namestringrequired
      • slugstringrequired
      • avatar_urlstring or null

        A path on this API (/v1/teams/{id}/avatar?v=…) for an uploaded avatar.

      • default_regionstring
      • rolestringrequired

        One of owner, admin, member, viewer.

      • require_two_factorboolean

        Members without two-factor are refused on this team's routes (403).

      • session_max_age_daysinteger

        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.

      • invitersstring

        owners: owners and admins invite. members: members may too (as member or viewer only).

        One of owners, members.

      • sign_in_methodsarray 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.

      • planstringrequired

        One of free, pro.

      • billing_alertnull 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.

        Show 6 child fields
        • kindstringrequired

          Always downgraded.

        • atstring
        • amount_ngninteger or null
        • chargestring

          One of automatic, manual.

        • grace_ends_atstring
        • ends_atstring
      • created_atstringrequired
      • project_countintegerrequired

        All projects in the team.

      • projectsarray of Projectrequired

        The newest 20 projects, in the order of GET /v1/teams/{team}/projects. Compare with project_count, and call that endpoint for the rest.

        Show 22 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
        • free_addressstringrequired

          Host name, <slug>.theorbits.app.

        • workloadWorkloadrequired
          Show 14 child fields
          • typestringrequired

            Always container.

          • output_directorystring
          • spa_fallbackboolean

            Defaults to false.

          • frameworkstring
          • memory_mbinteger

            At least 128.

          • timeout_secondsinteger

            At least 1.

          • commandarray of string
          • replicasinteger

            At least 1. Defaults to 1.

          • schedulestring or null

            Cron expression for scheduled jobs; null for a continuous worker.

          • portinteger

            From 1 to 65535.

          • health_check_pathstring

            Defaults to /.

          • start_commandarray of string
          • imagestring or null

            Prebuilt image reference. Mutually exclusive with dockerfile_path.

          • dockerfile_pathstring or null
        • sourcenull or Source
          Show 4 child fields
          • providerstringrequired

            One of github, gitlab, bitbucket, gitbucket.

          • repositorystringrequired
          • production_branchstringrequired

            Defaults to main.

          • root_directorystring

            Defaults to ./.

        • source_kindstring

          upload: deployed by dropping files (POST .../uploads); source is null and there is no repository.

          One of git, upload. Defaults to git.

        • buildBuildConfig
          Show 7 child fields
          • frameworkstring or null
          • install_commandstring or null

            null means detected default.

          • build_commandstring or null
          • output_directorystring or null
          • ignore_commandstring or null

            The ignored build step: run after cloning, in the repository (the commit and the one before it), as the build runs; exit 0 skips building this commit (the deployment ends canceled, saying why), anything else builds it. Two minutes at most, then it builds. It sees ORBITS_GIT_COMMIT_SHA, ORBITS_GIT_COMMIT_REF and ORBITS_ENV, and their VERCEL_* names. Example: git diff --quiet HEAD^ HEAD -- ./apps/storefront.

          • changed_byobject or null

            Who last changed a build setting ("Changed by Tunde Bakare yesterday").

            Show 2 child fields
            • idstring
            • namestring
          • changed_atstring or null
        • framework_versionstring or null

          Shown next to the framework on the overview header, e.g. 15.

        • node_versionstring
        • regionstringrequired
        • statusstringrequired

          What the project cards and the project switcher show. pending means nothing has been deployed yet. building, ready and failed follow the latest deployment (a canceled latest one falls back to production: ready, or pending if nothing served yet).

          One of pending, building, ready, failed, paused.

        • pausedboolean
        • gitGitSettingsrequired
          Show 3 child fields
          • deploy_on_pushbooleanrequired

            Pushes to the production branch go to production; other branches get a preview.

          • preview_pull_requestsbooleanrequired

            Each pull request gets its own address.

          • comment_on_pull_requestsbooleanrequired

            Post the preview link on the pull request and update it on every push.

        • preview_protectionstring

          Who may open previews (production stays public). password: the edge asks for the project's preview password and remembers it for 12 hours.

          One of none, team_members, password. Defaults to team_members.

        • production_urlstring or null
        • latest_deployment_idstring or null
        • latest_deploymentnull or LatestDeployment
          Show 8 child fields
          • idstringrequired
          • statestringrequired

            queued waits for a builder; the screens show it as building.

            One of queued, building, ready, failed, canceled.

          • branchstring or null
          • commit_shastring or null
          • commit_messagestring or null
          • authorobject or null
            Show 2 child fields
            • namestring
            • avatar_urlstring or null
          • failure_reasonstring or null
          • created_atstringrequired
        • thumbnail_urlstring or null

          API path of the screenshot of what production serves, for the project card (the screenshot_url of that deployment). Null until production has one. Fetch it with the session, like any API call.

        • thumbnail_colorstring or null

          The screenshot's most common strong colour, which the project card glows in. Null without a screenshot, or when the page is all black, white and grey.

        • created_atstringrequired
        • updated_atstring

    Errors

    • 401Missing or invalid credentials.

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/me" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
            }
          ]
        }
      ]
    }

    Teams the caller belongs to

    Teams the caller belongs to.

    GET/v1/teams
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Query parameters

    • limitinteger

      From 1 to 100. Defaults to 25.

    • cursorstring

    Response 200

    Teams.
    • next_cursorstring or null
    • itemsarray of Teamrequired
      Show 13 child fields
      • idstringrequired
      • namestringrequired
      • slugstringrequired
      • avatar_urlstring or null

        A path on this API (/v1/teams/{id}/avatar?v=…) for an uploaded avatar.

      • default_regionstring
      • rolestringrequired

        One of owner, admin, member, viewer.

      • require_two_factorboolean

        Members without two-factor are refused on this team's routes (403).

      • session_max_age_daysinteger

        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.

      • invitersstring

        owners: owners and admins invite. members: members may too (as member or viewer only).

        One of owners, members.

      • sign_in_methodsarray 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.

      • planstringrequired

        One of free, pro.

      • billing_alertnull 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.

        Show 6 child fields
        • kindstringrequired

          Always downgraded.

        • atstring
        • amount_ngninteger or null
        • chargestring

          One of automatic, manual.

        • grace_ends_atstring
        • ends_atstring
      • created_atstringrequired

    Errors

      Every code is explained in Errors.

      curl "https://api.theorbits.app/v1/teams" \
        -H "Authorization: Bearer $ORBITS_TOKEN"
      Response 200
      {
        "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"
          }
        ]
      }

      Get a team

      Get a team.

      GET/v1/teams/{team}
      Read or full tokenReturns200OK

      Headers

      • Authorizationstringrequired

        Bearer and your API token: Bearer orb_live_….

      Path parameters

      • teamstringrequired

        Team slug or team_ id.

      Response 200

      The team, with its members and pending email invites.
      • idstringrequired
      • namestringrequired
      • slugstringrequired
      • avatar_urlstring or null

        A path on this API (/v1/teams/{id}/avatar?v=…) for an uploaded avatar.

      • default_regionstring
      • rolestringrequired

        One of owner, admin, member, viewer.

      • require_two_factorboolean

        Members without two-factor are refused on this team's routes (403).

      • session_max_age_daysinteger

        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.

      • invitersstring

        owners: owners and admins invite. members: members may too (as member or viewer only).

        One of owners, members.

      • sign_in_methodsarray 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.

      • planstringrequired

        One of free, pro.

      • billing_alertnull 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.

        Show 6 child fields
        • kindstringrequired

          Always downgraded.

        • atstring
        • amount_ngninteger or null
        • chargestring

          One of automatic, manual.

        • grace_ends_atstring
        • ends_atstring
      • created_atstringrequired
      • notificationsNotificationRules

        Settings > Notifications: one switch per event and channel. Email goes to everyone who can deploy (owners, admins and members). A Slack switch decides whether that event goes to Slack; the Slack integration's page decides the channel (PATCH /v1/teams/{team}/integrations/slack). deploy.failed: a production or preview build fails. deploy.live: a production deploy goes live (off until turned on). domain.attention: a domain's DNS stops pointing at Orbits, its certificate can't be issued, or one within 14 days of expiring hasn't renewed; email goes to everyone who can deploy. A domain still not set up an hour after adding it also gets its own DNS email, to whoever added it (the same switch turns it off). member.joined: someone joins (not told to themselves). weekly: Mondays at 9:00 Lagos, the past Monday to Sunday across the team's projects; on Slack it is a short post (visitors, deploys, build time) in the channel picked for deploy.live, or any channel the Slack page has.

        Show 5 child fields
        • deploy.failedNotificationSwitchesrequired
          Show 2 child fields
          • emailbooleanrequired
          • slackbooleanrequired
        • deploy.liveNotificationSwitchesrequired
          Show 2 child fields
          • emailbooleanrequired
          • slackbooleanrequired
        • domain.attentionNotificationSwitchesrequired
          Show 2 child fields
          • emailbooleanrequired
          • slackbooleanrequired
        • member.joinedNotificationSwitchesrequired
          Show 2 child fields
          • emailbooleanrequired
          • slackbooleanrequired
        • weeklyNotificationSwitchesrequired
          Show 2 child fields
          • emailbooleanrequired
          • slackbooleanrequired
      • membersarray of Memberrequired

        Active members, then pending email invites (status: invited). Same rows as GET /v1/teams/{team}/members without q.

        Show 6 child fields
        • userUserrequired
          Show 6 child fields
          • idstringrequired
          • emailstringrequired
          • namestringrequired
          • usernamestring or null

            Their handle: unique, lowercase letters, numbers and dashes. Null until they set one.

          • avatar_urlstring or null

            A path on this API (/v1/users/{id}/avatar?v=…) for an uploaded photo, or an absolute URL from a sign-in provider.

          • two_factor_enabledboolean

            Whether the person has two-factor on. On a team member it is as of their last visit.

        • rolestringrequired

          One of owner, admin, member, viewer.

        • statusstringrequired

          One of active, invited.

        • invite_idstring

          Present only for invited rows; use it for resend and revoke operations.

        • joined_atstring or null
        • last_active_atstring or null

          When the person last used this team with their session (not an API token), accurate to the minute. Null for a pending invite and for anyone who hasn't used the team since this was recorded; show it as "Never" only for an active member who really hasn't.

      Errors

      • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

      Every code is explained in Errors.

      curl "https://api.theorbits.app/v1/teams/my-team" \
        -H "Authorization: Bearer $ORBITS_TOKEN"
      Response 200
      {
        "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"
          }
        ]
      }

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

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

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

      PATCH/v1/teams/{team}
      Full tokenReturns200OK

      Headers

      • Authorizationstringrequired

        Bearer and your API token: Bearer orb_live_….

      Path parameters

      • teamstringrequired

        Team slug or team_ id.

      Body

      application/json
      • namestring
      • slugstring
      • avatar_urlstring or null
      • default_regionstring

        Abuja is the only region in v1.

        One of abj-1.

      • require_two_factorboolean
      • session_max_age_daysinteger

        From 1 to 365.

      • invitersstring

        One of owners, members.

      • sign_in_methodsarray of string

        422 when it leaves out the method the caller signed in with.

      • notificationsobject

        Only the switches that change, as {"deploy.live": {"email": true}}; the rest stay. 422 on notifications for an unknown event or channel.

      Response 200

      Updated.
      • idstringrequired
      • namestringrequired
      • slugstringrequired
      • avatar_urlstring or null

        A path on this API (/v1/teams/{id}/avatar?v=…) for an uploaded avatar.

      • default_regionstring
      • rolestringrequired

        One of owner, admin, member, viewer.

      • require_two_factorboolean

        Members without two-factor are refused on this team's routes (403).

      • session_max_age_daysinteger

        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.

      • invitersstring

        owners: owners and admins invite. members: members may too (as member or viewer only).

        One of owners, members.

      • sign_in_methodsarray 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.

      • planstringrequired

        One of free, pro.

      • billing_alertnull 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.

        Show 6 child fields
        • kindstringrequired

          Always downgraded.

        • atstring
        • amount_ngninteger or null
        • chargestring

          One of automatic, manual.

        • grace_ends_atstring
        • ends_atstring
      • created_atstringrequired

      Errors

      • 403Authenticated but not allowed in this team.
      • 409The request conflicts with current state.
      • 422Validation failed, or the Idempotency-Key was reused with a different body.

      Every code is explained in Errors.

      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
      {
        "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"
      }

      Dashboard overview for a time range

      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.

      GET/v1/teams/{team}/overview
      Read or full tokenReturns200OK

      Headers

      • Authorizationstringrequired

        Bearer and your API token: Bearer orb_live_….

      Path parameters

      • teamstringrequired

        Team slug or team_ id.

      Query parameters

      • rangestring

        One of 24h, 7d, 30d. Defaults to 24h.

      Response 200

      Aggregated figures and recent items.
      • rangestringrequired
      • logs_availablebooleanrequired

        False while the log store can't be reached: requests and series.requests are then zeros, not a quiet day. Show them as unavailable.

      • projectsobjectrequired
        Show 2 child fields
        • totalinteger
        • failinginteger
      • deploymentsobjectrequired
        Show 2 child fields
        • totalinteger
        • delta_vs_previousinteger
      • average_build_secondsnumber
      • requestsobjectrequired
        Show 2 child fields
        • totalinteger
        • month_to_dateinteger
      • seriesobject

        The range in equal slices, oldest first.

        Show 3 child fields
        • deploymentsarray of integerrequired
        • average_build_secondsarray of numberrequired
        • requestsarray of integerrequired
      • needs_attentionarray of object
        Show 3 child fields
        • kindstringrequired
        • messagestringrequired
        • linkstring

      Errors

        Every code is explained in Errors.

        curl "https://api.theorbits.app/v1/teams/my-team/overview" \
          -H "Authorization: Bearer $ORBITS_TOKEN"
        Response 200
        {
          "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"
            }
          ]
        }

        Notifications for the caller in this team

        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.

        GET/v1/teams/{team}/notifications
        Read or full tokenReturns200OK

        Headers

        • Authorizationstringrequired

          Bearer and your API token: Bearer orb_live_….

        Path parameters

        • teamstringrequired

          Team slug or team_ id.

        Query parameters

        • limitinteger

          From 1 to 50. Defaults to 20.

        • cursorstring
        • unreadboolean

          Only the ones the caller hasn't read.

        Response 200

        Notifications.
        • next_cursorstring or null
        • itemsarray of Notificationrequired
          Show 8 child fields
          • idstringrequired
          • typestringrequired

            The event it came from.

            One of deployment.failed, domain.live, domain.misconfigured, domain.certificate.failed, team.member.added, alert.fired.

          • titlestringrequired
          • detailstring or nullrequired

            The second line: a failed deploy's reason and branch (just On main for one recorded before reasons were kept), who invited a new member, or what to do about a domain.

          • linkstring or nullrequired

            A path of this API to open as the app's own page; null when there's nowhere to go.

          • projectnull or objectrequired
            Show 3 child fields
            • idstringrequired
            • slugstringrequired
            • namestringrequired
          • readbooleanrequired
          • created_atstringrequired
        • unread_countintegerrequired

          The caller's unread notifications, up to 100.

          At most 100.

        Errors

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

        Every code is explained in Errors.

        curl "https://api.theorbits.app/v1/teams/my-team/notifications" \
          -H "Authorization: Bearer $ORBITS_TOKEN"
        Response 200
        {
          "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
        }

        Mark notifications read

        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.

        POST/v1/teams/{team}/notifications
        Full tokenNeeds Idempotency-KeyReturns204No Content

        Headers

        • Authorizationstringrequired

          Bearer and your API token: Bearer orb_live_….

        • Idempotency-Keystringrequired

          A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

          From 8 to 128 characters.

        Path parameters

        • teamstringrequired

          Team slug or team_ id.

        Body

        application/json
        • idsarray of string

          At most 100 items.

        • allboolean

        Response 204

        Marked. No body.

        Errors

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

        Every code is explained in Errors.

        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
          }'
        HTTP/1.1 204 No Content

        Was this page helpful?

        Updated