# The Orbits API contract, for API tokens. Guides and reference: https://docs.orbits.africa/api
openapi: 3.1.0
info:
  title: Orbits API
  version: 0.1.0-draft
  description: |-
    The Orbits API: projects, deployments, environment variables, domains and DNS, logs, analytics, flags, workflows, alerts, usage and billing, for an API token (`orb_live_…`, made in the dashboard under Team › Settings › API tokens). Send it as `Authorization: Bearer <token>`. Guides and reference: https://docs.orbits.africa/api.

    Operations whose summary ends in "(planned)" are not available yet.

    Rate limits
    - Over a limit the API answers `429` with `Retry-After` (whole seconds) and a problem document; wait that long.
      Limits are token buckets: a short burst, then a steady rate.
    - Signed-in requests are limited per person (1,200 a minute, bursts of 400) and per API token (300 a minute,
      bursts of 100), not per address, so many people behind one server don't affect each other. A token has its own
      budget, apart from its person's.
    - Sign-in and account routes (`/v1/auth/...`, `/v1/me/...`, invite lookups) are limited per address (300 a minute),
      and asking for a sign-in email 30 a minute per address and 5 in a row per email address, then one every three
      minutes, whether or not the address has an account. An address that sends many bearer tokens the API refuses
      (300 a minute) waits, even with a good one.
    - A team has one budget of its own too (6,000 a minute), spent by its members and its API tokens together, so a
      `429` on a team's route can be the team's budget rather than the caller's (`RateLimit-Scope: team`).
    - Not limited here: webhooks from Git providers, the preview and flags SDK calls from deployed apps.
    - Every signed-in answer carries the caller's own budget, and every `429` the budget that ran out:
      `RateLimit-Limit` (the bucket's size: how many requests can be made at once), `RateLimit-Remaining` (whole
      requests left), `RateLimit-Reset` (seconds until it is full again) and `RateLimit-Scope` (`user`, `token`,
      `team`, `address` or `email`). A `429` also has `Retry-After`, the seconds until one request is allowed.

    API tokens
    - A token belongs to one team and acts as the person who made it, so it stops working when they leave the team
      (or when the team turns two-factor on and they have it off). It is a CLI or CI credential, not a login.
    - `read` tokens may only send `GET` and `HEAD`, and never read environment variable values. `full` tokens may
      send anything below, except what is listed next. A token limited to one project reaches only that project's routes,
      plus `GET /v1/teams/{team}`, `GET /v1/teams/{team}/projects` and `GET /v1/teams/{team}/deployments`, which list
      only that project.
    - It can call `GET /v1/me`, `GET /v1/teams`, `GET /v1/templates`, `GET /v1/operations/{id}` and
      `/v1/teams/{team}/...` for its own team. Anything else is 403 ("API tokens can't ..."): sign-in and account
      routes (`/v1/auth/...`, `/v1/me/...`), creating teams, accepting invites, token management, deleting the team,
      the team's security rules (two-factor, sign-in methods, session length, who can invite), members and invites,
      moving a project to another team, and Git or notification integrations (the list at
      `GET /v1/teams/{team}/integrations` is fine).
    - 401: the token is wrong, revoked or expired. A team's sign-in method and session-length rules don't apply to
      tokens; its two-factor rule applies to the person the token acts as.

    Conventions
    - REST/JSON, routes scoped as `/teams/{team}/...`. `{team}` accepts the slug or the `team_` id.
    - Public ids carry a prefix: `usr_`, `team_`, `prj_`, `dpl_`, `dom_`, `rec_`, `tok_`, `op_`.
    - Errors are RFC 9457 `application/problem+json`.
    - Every POST takes an `Idempotency-Key`. A replay with the same key and body returns the first result;
      the same key with a different body returns 422. A POST that doesn't list the `Idempotency-Key` parameter
      ignores it, and so does one whose description says so.
    - Anything slow returns `202` with an Operation (or the new Deployment). Clients poll or follow events.
    - Lists use cursor pagination: `limit` and `cursor` in, `items` and `next_cursor` out.
    - Timestamps are RFC 3339 UTC.
servers:
  - url: https://api.theorbits.app/v1
    description: Production.
  - url: https://stagingapi.theorbits.app/v1
    description: Staging.
security:
  - bearerAuth: []
tags:
  - name: Auth
  - name: Teams
  - name: Billing
  - name: Projects
  - name: Deployments
  - name: Logs
  - name: Insights
    description: Analytics and Speed Insights, from the beacons the edge's scripts send, loaded by @useorbits/analytics and @useorbits/speed-insights.
  - name: Flags
    description: Feature flags, and what @useorbits/flags reads them with.
  - name: Workflows
    description: Durable workflows an app defines with @useorbits/workflows, and their runs.
  - name: Sandboxes
    description: On-demand dev machines for a project — clone the repo, run a dev server, seed data — with an interactive terminal.
  - name: Alerts
  - name: Environment variables
  - name: Domains
  - name: DNS
  - name: Integrations
  - name: Usage and activity
paths:
  /me:
    get:
      tags:
        - Auth
      operationId: getCurrentUser
      summary: Current user
      description: Current user, with their teams and each team's newest projects, so the app can render its shell from one call.
      responses:
        "200":
          description: The signed-in user with their teams, each with its newest projects.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Me"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /teams:
    get:
      tags:
        - Teams
      operationId: listTeams
      summary: Teams the caller belongs to
      description: Teams the caller belongs to.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Teams.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamPage"
  /teams/{team}:
    parameters:
      - $ref: "#/components/parameters/Team"
    get:
      tags:
        - Teams
      operationId: getTeam
      summary: Get a team
      description: Get a team.
      responses:
        "200":
          description: The team, with its members and pending email invites.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamDetail"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags:
        - Teams
      operationId: updateTeam
      summary: Rename, change slug, avatar, default region, or security rules
      description: |-
        Rename, change slug, avatar, default region, or security rules.

        Changing the slug breaks old dashboard links. All settings require an owner or admin.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TeamUpdate"
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Team"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/overview:
    get:
      tags:
        - Teams
      operationId: getTeamOverview
      summary: Dashboard overview for a time range
      description: 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`.
      parameters:
        - $ref: "#/components/parameters/Team"
        - name: range
          in: query
          schema:
            type: string
            enum:
              - 24h
              - 7d
              - 30d
            default: 24h
      responses:
        "200":
          description: Aggregated figures and recent items.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamOverview"
  /teams/{team}/notifications:
    get:
      tags:
        - Teams
      operationId: listNotifications
      summary: Notifications for the caller in this team
      description: |-
        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.
      parameters:
        - $ref: "#/components/parameters/Team"
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - $ref: "#/components/parameters/Cursor"
        - name: unread
          in: query
          schema:
            type: boolean
          description: Only the ones the caller hasn't read.
      responses:
        "200":
          description: Notifications.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    post:
      tags:
        - Teams
      operationId: markNotificationsRead
      summary: Mark notifications read
      description: |-
        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.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  maxItems: 100
                  items:
                    type: string
                all:
                  type: boolean
      responses:
        "204":
          description: Marked.
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /plans:
    get:
      tags:
        - Billing
      operationId: listPlans
      security: []
      summary: The plans and their prices
      description: |-
        Orbits has two plans. **Free** is unlimited projects, with apps that scale to zero, and without server functions, sandboxes and Analytics or Speed Insights. **Pro** is `usd_cents: 500` a month and has all of them. `ngn` is the Naira amount charged for the price: the USD price at `rate` (a rate Orbits sets, `USD → NGN`), rounded up to a whole ₦100. It is `null` until the server has a rate set (then Pro can't be bought yet). The amount a payment is actually taken for is locked on the invoice when checkout starts, so show `ngn` as "about" only if you need to hedge; `POST .../billing/checkout` refuses with 409 if the amount you showed no longer matches.

        `features` describe the plan, not the team, and are the same whether or not limits are being enforced yet (`enforced` on `GET /v1/teams/{team}/billing` says whether they are).
      responses:
        "200":
          description: The plans.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                  - rate
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Plan"
                  rate:
                    type:
                      - string
                      - "null"
                    description: The USD → NGN rate in use, as a decimal string, or null when none is set.
                    examples:
                      - "1600"
  /teams/{team}/billing:
    parameters:
      - $ref: "#/components/parameters/Team"
    get:
      tags:
        - Billing
      operationId: getBilling
      summary: The team's plan and billing state
      description: |-
        What the Settings Plan card and the Billing page show: the plan, whether it is `active`, `past_due` (a payment failed and the team is in its grace period) or `free`, the current period, what the next charge will be, what the plan allows, and (for owners) the card on file. `enforced` is false while Orbits has not switched plan limits on: every feature works for every team and `entitlements` all say true, although `plan` still says what the team is on.

        **Permissions:** Any team member sees the plan; the card is shown to owners only. A non-member gets 404.
      responses:
        "200":
          description: The billing state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Billing"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/billing/invoices:
    parameters:
      - $ref: "#/components/parameters/Team"
    get:
      tags:
        - Billing
      operationId: listInvoices
      summary: The team's invoices
      description: |-
        The Invoices list: payments made for Pro, newest first. Payments that were started and never paid are not listed. `limit` is 1 to 100 (default 25); there is no cursor yet.

        **Permissions:** Team owners only; other members get 403.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        "200":
          description: The invoices.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Invoice"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/billing/invoices/{invoice}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - name: invoice
        in: path
        required: true
        schema:
          type: string
        description: An `id` from `GET .../billing/invoices`.
    get:
      tags:
        - Billing
      operationId: getInvoice
      summary: One invoice, as a receipt
      description: |-
        The invoice with who paid, for which team, what for, and the card (brand and last four) it was paid with. There is no PDF; the dashboard renders the receipt.

        **Permissions:** Team owners only. An invoice of another team is 404.
      responses:
        "200":
          description: The receipt.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Receipt"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /templates:
    get:
      tags:
        - Projects
      operationId: listTemplates
      summary: Starter templates for a new project
      description: |-
        The "Start from a template" catalog on the New project screens, read from [the-orbits/templates](https://github.com/the-orbits/templates) (its `catalog.json`, cached for five minutes). A template added there appears here without a backend change.

        `workload` and `node_version`, when present, are what a project created from the template gets; `optional_env` lists variables the template reads when they are set. If the templates repository cannot be reached and nothing is cached, the list built into the service is served instead.

        **Permissions:** Any signed-in user.
      responses:
        "200":
          description: Templates.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Template"
  /teams/{team}/projects:
    get:
      tags:
        - Projects
      operationId: listProjects
      summary: List projects
      description: |-
        The projects of a team, for the project cards on the team overview and for the project switcher.

        Fields that come from deployments (`status`, `latest_deployment`, `thumbnail_url`) are `pending` or null until the deployment pipeline exists. Paused projects report `status: paused`.

        Sorting: `last_deploy` (default) puts the most recently deployed first, then projects with no deployment by `created_at`.

        An API token limited to one project may call this too: the list then holds only that project (still subject to `q` and `repository`), with `next_cursor: null`.

        **Permissions:** Any team member, including viewers. A non-member gets 404, the same as an unknown team.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: q
          in: query
          schema:
            type: string
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - last_deploy
              - name
              - created
            default: last_deploy
        - name: repository
          in: query
          description: Only projects imported from this repository, e.g. `shadyventures/storefront`.
          schema:
            type: string
      responses:
        "200":
          description: Projects.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectPage"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags:
        - Projects
      operationId: createProject
      summary: Create a project from a repository or a template
      description: |-
        Create a project: the Deploy button on the New project > Configure screens.

        `name` becomes the free address, `<slug>.theorbits.app`, where `slug` is the name in lower case with hyphens (or the `slug` you send). It must be unique across all teams: 409 means ask for another name.

        `workload` is optional. When omitted it is derived from `build.framework`: `nextjs`, `sveltekit`, `nuxt`, `remix`, `reactrouter`, `solidstart` and `tanstack-start` become a `function`, `node`, `elysia` and `dolphjs` an `app`, and everything else `static`.

        For a GitHub `source`, Orbits asks the Git service whether the team's GitHub connection can see the repository. 422 with `source.repository` means it cannot (not found, or not installed on that repository); 422 with `source.provider` means GitHub is not connected to the team. If that check cannot be completed the answer is 503 and nothing is created; retry.

        With a `template` instead, Orbits creates a private repository named after the project's slug in the team's connected GitHub account, commits the template's files into it, and creates the project from it with the template's `workload` and `node_version`; the first deployment is queued as for an import. Every variable in the template's `required_env` must be sent in `env` (422 on `env` otherwise), and the address must be free before the repository is created. In a personal GitHub account the caller must have approved Orbits first (`GET /v1/teams/{team}/integrations/github/approval`). 409 covers a taken address, a repository of that name already in the account, GitHub not connected, a personal account not yet approved, and an organisation whose installation has not yet accepted the Orbits app's Administration and Contents permissions; its `detail` says which. 503 means GitHub could not be reached.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectCreate"
      responses:
        "202":
          description: Project created. With a `source`, its first production deployment is queued too and shows as `latest_deployment`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          description: The repository could not be verified, or GitHub could not be reached to create one; nothing was created. Retry.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /teams/{team}/projects/{project}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Projects
      operationId: getProject
      summary: Get a project
      description: |-
        One project, for the project overview header and for the Settings form.

        **Permissions:** Any team member. A non-member, or a project in another team, gets 404.
      responses:
        "200":
          description: The project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags:
        - Projects
      operationId: updateProject
      summary: Change project settings
      description: |-
        Change project settings. Settings save as the user makes them (the Settings screen shows "All changes saved"), so send only the fields that changed.

        Changes apply from the next deployment; existing deployments keep the snapshot taken when they were built. Renaming (`name`) also changes `slug` and the free address. The workload type cannot change after creation (422).

        `build` and `git` are merged field by field: omit a field to keep it, send `null` in `build` to go back to the detected default. `preview_password` is write-only and only valid with `preview_protection: password`.

        **Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectUpdate"
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - Projects
      operationId: deleteProject
      summary: Delete a project
      description: |-
        Delete a project (Settings > Delete project). The record is removed and an Operation is returned; downstream cleanup will be tracked by the same Operation once those services exist.

        **Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404.
      responses:
        "202":
          description: Deletion accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Operation"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/deletion-impact:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Projects
      operationId: getProjectDeletionImpact
      summary: What deleting a project removes
      description: |-
        The numbers on the Delete modal: "126 deployments and their build logs, 11 environment variables, 5 flags and their history, 4 domains are detached".

        **Permissions:** Owner or admin, like the delete itself. A non-member gets 404.
      responses:
        "200":
          description: Counts of what is removed or detached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDeletionImpact"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/pause:
    post:
      tags:
        - Projects
      operationId: pauseProject
      summary: Pause or resume a project
      description: |-
        Pause or resume a project (the Paused toggle in Settings > Advanced). While paused, its production, preview and custom-domain addresses answer 503 with Orbits' paused page, its apps stop, and nothing deploys; domains, data and the builds production can come back to stay. Resuming serves production again within moments.

        The response is the updated Project (`paused` and `status: paused`), not an Operation: the toggle needs an immediate answer, and the runtime effect is reported through `status`.

        **Permissions:** Owner or admin. Members and viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Project"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - paused
              properties:
                paused:
                  type: boolean
      responses:
        "200":
          description: The updated project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/deployments:
    get:
      tags:
        - Deployments
      operationId: listTeamDeployments
      summary: Deployments across the team's projects
      description: |-
        The team's Deployments page: every deployment across its projects, newest first, with the facets for its filters (Project, Environment, Status, Author) and "38 this week".

        An API token limited to one project may call this too: the deployments, `projects`, `authors`, `total` and `this_week` then cover only that project, and a `project` filter naming another project returns an empty list.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: q
          in: query
          schema:
            type: string
          description: Matches the commit message, branch, sha or author.
        - name: project
          in: query
          schema:
            type: string
          description: Project slug or `prj_` id.
        - name: environment
          in: query
          schema:
            $ref: "#/components/schemas/DeploymentEnvironment"
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/DeploymentState"
        - name: author
          in: query
          schema:
            type: string
          description: An `authors[].name`.
      responses:
        "200":
          description: Deployments, newest first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamDeploymentPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/branch-addresses:
    get:
      tags:
        - Domains
      operationId: listBranchAddresses
      summary: A project's branch addresses
      description: |-
        The branch rows on a project's Domains page ("Follows the branch"): one address per branch with a ready preview, serving that branch's newest ready preview. The address is `<project>-git-<branch>.theorbits.app` (`orders-git-feat-apple-pay.theorbits.app`), one label under the free addresses' domain so their certificate covers it; a long branch is shortened and given a short hash. Show `host` as it is rather than building it.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Project"
      responses:
        "200":
          description: The project's branches with a ready preview, the most recently deployed first.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      required:
                        - branch
                        - host
                        - url
                        - deployment_id
                        - deployed_at
                      properties:
                        branch:
                          type: string
                          examples:
                            - feat/apple-pay
                        host:
                          type: string
                          examples:
                            - orders-git-feat-apple-pay.theorbits.app
                        url:
                          type: string
                          format: uri
                        deployment_id:
                          type: string
                          pattern: ^dpl_
                        deployed_at:
                          type: string
                          format: date-time
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/deployments:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Deployments
      operationId: listProjectDeployments
      summary: A project's deployments
      description: |-
        The project's Deployments page: every build, newest first, with the filters (search, Env, Status, Branch, "Production only") and what the inspector shows when nothing is picked (`current`, the deployment production serves, and its `domains`).

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: q
          in: query
          schema:
            type: string
          description: Matches the commit message, branch, sha or author.
        - name: environment
          in: query
          schema:
            $ref: "#/components/schemas/DeploymentEnvironment"
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/DeploymentState"
        - name: branch
          in: query
          schema:
            type: string
        - name: live
          in: query
          schema:
            type: boolean
          description: Only deployments that have served production.
      responses:
        "200":
          description: Deployments, newest first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDeploymentPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    post:
      tags:
        - Deployments
      operationId: createDeployment
      summary: Deploy a branch now
      description: |-
        Queues a build of a branch's newest commit, for a deploy started by hand (the CLI's `orbits deploy`). The production branch deploys to production; any other branch to preview. Pushes and the first deploy of a new project are queued by Orbits itself and need no call. Returns at once with the queued deployment; follow it with `GET .../deployments/{deployment}` and its logs.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                branch:
                  type: string
                  minLength: 1
                  maxLength: 255
                  examples:
                    - main
      responses:
        "202":
          description: Queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deployment"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/uploads:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    post:
      tags:
        - Deployments
      operationId: startSourceUpload
      summary: Start dropping a site or app
      description: |-
        The drag and drop deploy: the person drops a folder (or a `.zip`) on the project, and the browser sends it to storage on a presigned URL, so the files never pass through the API. The archive is the project's **source code**, in place of a Git clone: Orbits unpacks it, detects the framework, installs, builds and publishes or runs it like any other deployment, for any kind of project. Only projects created with `source_kind: upload` take drops.

        What goes in the archive: the project's files, with `package.json`, source and config. Anything named `node_modules`, `.git`, `.next`, `__MACOSX` or `.DS_Store`, at any depth, is left out, and a single top-level folder is stripped, so zipping the folder or its contents both work. Limits: the zip may be up to `max_bytes` (100 MiB, 104,857,600 bytes); unpacked it may be up to 500 MiB and 20,000 entries, where the folders the zip lists count as well as its files (what is left out doesn't count); links and special files are refused. The build reports a breach on the Cloning step.

        Starting signs a PUT URL for the zip (valid ten minutes). At most 5 unfinished uploads per team.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - size
              properties:
                size:
                  type: integer
                  minimum: 1
                  maximum: 104857600
                  description: The zip's size in bytes. The URL accepts a file of exactly this length.
                filename:
                  type: string
                  maxLength: 255
                  description: Shown as the deployment's message, e.g. `Uploaded site.zip`.
                  examples:
                    - site.zip
      responses:
        "201":
          description: A URL to send the zip to.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceUpload"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`not_an_upload_project` (the project deploys from Git) or `too_many_uploads` (finish or cancel the others)."
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/projects/{project}/uploads/{upload}/complete:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: upload
        in: path
        required: true
        schema:
          type: string
        description: The `id` from `POST .../uploads`.
    post:
      tags:
        - Deployments
      operationId: completeSourceUpload
      summary: Deploy a dropped archive
      description: |-
        Say the browser has sent the zip. Orbits checks that it arrived whole and is a zip, then queues a production deployment that builds it (`trigger: manual`, the message is `Uploaded <filename>`). Returns at once; follow the deployment and its logs as for any build. The archive is kept, with the project's four previous ones, so Redeploy can rebuild it.

        If the file hasn't arrived yet this is 409 `upload_incomplete`: wait a second and call again. Completing an upload twice returns the same deployment.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: The deployment, queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deployment"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: "`upload_incomplete` (not arrived yet) or `upload_expired` (start again)."
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/projects/{project}/uploads/{upload}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: upload
        in: path
        required: true
        schema:
          type: string
        description: The `id` from `POST .../uploads`.
    delete:
      tags:
        - Deployments
      operationId: cancelSourceUpload
      summary: Cancel a drop
      description: |-
        Abandons an upload that was started and not completed; the file, if it arrived, is removed. Cancelling one that is gone or already completed is a no-op (the deployment it made is unaffected). Not needed for an upload that simply expires.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      responses:
        "204":
          description: Cancelled.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/production:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    post:
      tags:
        - Deployments
      operationId: setProductionDeployment
      summary: Set what production serves
      description: |-
        Points production at a deployment that served production before, and sets whether pushes may replace it. It is the Undo of a rollback (send back the rollback answer's `undo`), and with the current deployment and `auto_deploy_paused: false` it lifts a rollback's pause. No rebuild.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - deployment_id
                - auto_deploy_paused
              properties:
                deployment_id:
                  type: string
                  pattern: ^dpl_
                auto_deploy_paused:
                  type: boolean
      responses:
        "200":
          description: Production now serves it.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductionChange"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/deployments/{deployment}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    get:
      tags:
        - Deployments
      operationId: getDeployment
      summary: A deployment and its build steps
      description: |-
        The deployment page and the inspector: the header, the details grid (status, environment, duration, created, branch, commit, region, framework), production's domains when it is the current deployment, the six build steps with their state and seconds, and why a failed build stopped. The log lines themselves come from `GET .../logs`.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The deployment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeploymentDetail"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/deployments/{deployment}/logs:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    get:
      tags:
        - Deployments
      operationId: listDeploymentLogs
      summary: Build log lines
      description: |-
        The build log, oldest line first. Each line names its step, so the deployment page can group lines under Queued, Cloning repository, Installing packages, Building, Uploading and Going live. A build keeps at most 5000 lines.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: after
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Return lines after this `n`.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 2000
            default: 500
      responses:
        "200":
          description: Log lines.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeploymentLogPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/deployments/{deployment}/logs/stream:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    get:
      tags:
        - Deployments
      operationId: streamDeploymentLogs
      summary: Follow a build live (server-sent events)
      description: |-
        The live build log, pushed as server-sent events (`text/event-stream`), for New project · Deploying, a building deployment and Follow output. Lines arrive under a second after the build prints them. Events:

        - `line` (its `id` is the line's `n`): `{"n", "at", "step", "tone", "text"}`, oldest first.
        - `steps`: the six steps, as in the deployment's `steps`, whenever one changes.
        - `done`: `{"state", "failure", "duration_seconds"}` once the build has ended and every line has been sent. The stream then closes, unless the deployment just went ready.
        - `screenshot`: `{"screenshot_url"}`, the same URL the deployment's `screenshot_url` gives. The builder takes the screenshot a few seconds after the deployment is ready, so after `done` the stream stays open for up to 2 minutes and sends this when it is saved, then closes. Refresh the deployment (or its thumbnail) on it. It is not sent for a failed or canceled build, a worker, a deployment that already had its screenshot, or one that finished more than 2 minutes ago.
        - A `: keep-alive` comment every 15 s while nothing happens.

        The stream closes after 30 minutes or when a proxy cuts it (staging's after 5); reconnect with `Last-Event-ID` set to the last line `id` received (EventSource does this by itself) and it carries on with the next line, without gaps or repeats. A finished deployment answers with any remaining lines, its steps and `done` at once.

        **Permissions:** Any team member. A non-member gets 404 (a problem document, not a stream).
      parameters:
        - name: Last-Event-ID
          in: header
          schema:
            type: string
          description: The last line `id` received; the stream starts after it.
        - name: after
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: The same as Last-Event-ID, for a first connection that already has lines.
      responses:
        "200":
          description: The event stream.
          content:
            text/event-stream:
              schema:
                type: string
                description: "Server-sent events: `line`, `steps`, `done`, `screenshot`, and `: keep-alive` comments."
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/deployments/{deployment}/screenshot:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    get:
      tags:
        - Deployments
      operationId: getDeploymentScreenshot
      summary: A deployment's screenshot
      description: |-
        The image for the deployment inspector, the deployment page, New project's Preview box and the project card: the first screen (1280x800) of the deployment's home page, as a JPEG, taken by the builder a few seconds after the deployment became ready. It never changes once taken, so it is sent with `Cache-Control: private, max-age=604800, immutable`.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The JPEG.
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/logs:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Logs
      operationId: listRuntimeLogs
      summary: Runtime logs
      description: |-
        The Logs page: every request the edge sent to one of the project's deployments (`source: requests`), and every line its deployments printed while running (`source: functions`), newest first. Build logs are on each deployment (`GET .../deployments/{deployment}/logs`). Entries are kept for 7 days.

        A request has `status`, `method`, `path` and `duration_ms`, and no `message`. An output line has `message` and `stream`, and null `status`, `method`, `path` and `duration_ms`. Requests and output lines are not linked: an app's output is whatever it printed, whichever request it was serving. Client IP addresses are stored masked (`102.89.x.x`), and query strings are not stored.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: q
          in: query
          schema:
            type: string
            maxLength: 200
          description: Matches a path or message (any case), or exactly a request ID, status or method. A request ID on its own (32 hex characters, as the edge makes them) matches only that request.
        - name: source
          in: query
          schema:
            type: string
            enum:
              - requests
              - functions
        - name: level
          in: query
          schema:
            type: string
            enum:
              - info
              - warning
              - error
          description: A request is `error` for 5xx and `warning` for 4xx. An output line is `warning` when it mentions a warning, and `error` when it was written to stderr or mentions an error.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - 2xx
              - 3xx
              - 4xx
              - 5xx
          description: Requests only; output lines never match.
        - name: range
          in: query
          schema:
            type: string
            enum:
              - 1h
              - 24h
              - 7d
            default: 1h
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
        - name: cursor
          in: query
          schema:
            type: string
          description: "`next_cursor` from the previous page."
      responses:
        "200":
          description: One page of entries, and how many match.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeLogPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/projects/{project}/logs/{log}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: log
        in: path
        required: true
        schema:
          type: string
        description: A `log_` id from `GET .../logs`.
    get:
      tags:
        - Logs
      operationId: getRuntimeLog
      summary: One runtime log entry
      description: |-
        One entry for the Logs inspector, when the one in the URL is not on the current page. 404 once it is older than 7 days.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The entry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeLog"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/projects/{project}/observability:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Logs
      operationId: getObservability
      summary: Production's requests, errors and latency
      description: |-
        The Observability page: production's traffic over a range, from the runtime logs (the edge's requests to the project's production builds, at its address or a build's own). Requests and server errors (5xx) per bucket with p75 and p99 response times, totals with p50, p75 and p99 against the period before, the busiest routes, requests by status class and by region, and the routes for the Route filter. Times are milliseconds from the edge receiving a request to its last byte. Routes group a path's ids (`/products/8412` is `/products/[id]`) and a static folder's files (`/_next/*`). Percentiles are exact. Buckets are 12 x 5 minutes (`1h`), 24 x an hour (`24h`) or 7 x a day (`7d`), on Lagos's clock; the last is the one still filling.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: range
          in: query
          schema:
            type: string
            enum:
              - 1h
              - 6h
              - 24h
              - 7d
            default: 24h
          description: "Buckets: 12 x 5 minutes, 12 x 30 minutes (the project overview's health), 24 x an hour, 7 x a day."
        - name: route
          in: query
          schema:
            type: string
            maxLength: 500
          description: A route from `all_routes`.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - 2xx
              - 3xx
              - 4xx
              - 5xx
          description: Narrows everything but `statuses`.
        - name: region
          in: query
          schema:
            type: string
          description: A region code; `abj-1` is the only one with traffic.
      responses:
        "200":
          description: The page's numbers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Observability"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/projects/{project}/analytics:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Insights
      operationId: getAnalytics
      summary: A project's visitors and page views
      description: |-
        The Analytics page: page views the project's visitors' browsers sent with `@useorbits/analytics` (the edge's `/_orbits/analytics.js`, which sends beacons to `/_orbits/e` on the project's own host), to its production deployments only (not a preview's), over a range against the span before it. `buckets` are the range's hours (`24h`) or Lagos days (`7d`, `30d`), the last one still filling; `previous_buckets` are the span before, in the same order. A visitor is counted once a Lagos day: nothing identifies them across days, and neither their address nor their browser is kept. A bounce is a visitor with one page view. `pages` are by the route the framework named (`/blog/[slug]`, from the Next.js, SvelteKit and Astro components), or else the path with its ids grouped (`/products/8412` is `/products/[id]`). `referrers` are other sites' hosts; `host: null` is a visit nobody linked to. `countries` is empty until the edge looks them up. `events` are custom events (`track()`), most sent first. Lists keep their top ten.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: range
          in: query
          schema:
            $ref: "#/components/schemas/InsightsRange"
      responses:
        "200":
          description: "The page's numbers, or `{ \"enabled\": false }`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Analytics"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
    put:
      tags:
        - Insights
      operationId: setAnalytics
      summary: Turn Analytics on or off
      description: |-
        The Analytics page's Enable switch. While it's off, production's hosts don't serve `/_orbits/analytics.js` and page views and events aren't logged; the edge picks a change up within seconds.

        Turning it **on** needs Pro: a team on Free gets 402 `plan_required` (feature `analytics`). Turning it off is always allowed.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InsightsSwitch"
      responses:
        "200":
          description: The switch as it now is.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InsightsSwitch"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/analytics/event:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Insights
      operationId: getAnalyticsEvent
      summary: One custom event and its properties
      description: |-
        A custom event from the Analytics page's `events` (sent with `track(name, properties)`) over a range, production only: how often it was sent, by how many visitors, and its properties, ten at most, each with its ten commonest values. A value that isn't a string is shown as its JSON (`3`, `true`, `null`).

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: range
          in: query
          schema:
            $ref: "#/components/schemas/InsightsRange"
      responses:
        "200":
          description: 'The event, or `{ "enabled": false }`.'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsEvent"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/projects/{project}/speed-insights:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Insights
      operationId: getSpeedInsights
      summary: A project's Web Vitals from real visits
      description: |-
        The Speed Insights page: Web Vitals the project's visitors' browsers measured and sent with `@useorbits/speed-insights` (the edge's `/_orbits/speed-insights.js`) from its production deployments, on one kind of device (`mobile` counts tablets), at the 75th percentile. LCP, INP, FCP and TTFB are milliseconds, CLS a unitless score. `score` is 0 to 100 from the p75s there are, as Lighthouse scores each metric (90 at its good line, 50 at its median) weighted FCP 15%, LCP 30%, INP 30% and CLS 25%; TTFB is shown but not scored; null without any. `lcp` is LCP's p75 by bucket (null where none was measured). `routes` are the most visited, ten at most, by the route the framework named or the path with its ids grouped, with each vital's p75 or null. `targets` are the elements (CSS selectors) most often behind LCP, INP and CLS, five each, with how often and their p75. `connections` are LCP samples by the connection they were measured on.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: range
          in: query
          schema:
            $ref: "#/components/schemas/InsightsRange"
        - name: device
          in: query
          schema:
            type: string
            enum:
              - mobile
              - desktop
            default: mobile
      responses:
        "200":
          description: "The page's numbers, or `{ \"enabled\": false }`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpeedInsights"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
    put:
      tags:
        - Insights
      operationId: setSpeedInsights
      summary: Turn Speed Insights on or off
      description: |-
        The Speed Insights page's Enable switch. While it's off, production's hosts don't serve `/_orbits/speed-insights.js` and vitals aren't logged; the edge picks a change up within seconds.

        Turning it **on** needs Pro: a team on Free gets 402 `plan_required` (feature `speed_insights`). Turning it off is always allowed.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InsightsSwitch"
      responses:
        "200":
          description: The switch as it now is.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InsightsSwitch"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/flags:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Flags
      operationId: listFlags
      summary: A project's feature flags
      description: |-
        The Flags page: every flag, newest first, with each environment's setting. `q` matches the key or description, `type` narrows to one type; `total` counts them all, for "3 of 5 flags".

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: q
          in: query
          schema:
            type: string
            maxLength: 100
        - name: type
          in: query
          schema:
            $ref: "#/components/schemas/FlagType"
      responses:
        "200":
          description: The flags.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlagList"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    post:
      tags:
        - Flags
      operationId: createFlag
      summary: Create a flag
      description: |-
        A boolean flag starts off in each environment unless `environments.<name>.on` says otherwise, at 100% rollout and with no rules. A string or number flag needs `environments.<name>.value` for all three. Keys are lowercase letters, digits and single dashes, unique in the project.

        **Permissions:** Owners, admins and members. Viewers get 403.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - key
                - type
              properties:
                key:
                  type: string
                  maxLength: 48
                  pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
                  examples:
                    - new-checkout
                description:
                  type: string
                  maxLength: 120
                type:
                  $ref: "#/components/schemas/FlagType"
                environments:
                  type: object
                  properties:
                    production:
                      $ref: "#/components/schemas/FlagEnvironmentInput"
                    preview:
                      $ref: "#/components/schemas/FlagEnvironmentInput"
                    development:
                      $ref: "#/components/schemas/FlagEnvironmentInput"
      responses:
        "201":
          description: The new flag.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Flag"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/flag-keys:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Flags
      operationId: getFlagKeys
      summary: Each environment's ORBITS_FLAGS key
      description: |-
        Deployments get their environment's key as `ORBITS_FLAGS` (and the API's address as `ORBITS_API_URL`) without asking. These are for code that runs elsewhere: put `development`'s in `.env.local` to read Development's flags locally. A key reads its environment's flags and reports checks, nothing else.

        **Permissions:** Owners, admins and members. Viewers get 403.
      responses:
        "200":
          description: The keys.
          content:
            application/json:
              schema:
                type: object
                required:
                  - production
                  - preview
                  - development
                properties:
                  production:
                    type: string
                    examples:
                      - ofl_cHJqXzE6cHJvZHVjdGlvbg.k3W…
                  preview:
                    type: string
                  development:
                    type: string
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/flags/{flag}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: flag
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Flags
      operationId: getFlag
      summary: A flag, its history and who it was checked for
      description: |-
        The flag's page. `history` is newest first, 50 at most, each line written as the page says it. `seen` is each environment's last 24 hours as the SDK reported them: `people` the ids it was checked for, `checks` every check, with or without one.

        **Permissions:** Any team member.
      responses:
        "200":
          description: The flag.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlagDetail"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags:
        - Flags
      operationId: updateFlag
      summary: Change a flag's description
      description: |-
        The key and type never change; make another flag for that.

        **Permissions:** Owners, admins and members.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  maxLength: 120
      responses:
        "200":
          description: The flag.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Flag"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - Flags
      operationId: deleteFlag
      summary: Delete a flag
      description: |-
        The SDK stops getting it on its next refresh, and code checking it gets the default it passed.

        **Permissions:** Owners, admins and members.
      responses:
        "204":
          description: Deleted.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: flag
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/FlagEnvironmentName"
    put:
      tags:
        - Flags
      operationId: setFlagEnvironment
      summary: Switch a flag, set its rollout or its value in one environment
      description: |-
        A boolean flag takes `on` and `rollout` (1–100, the share of ids it's on for); a string or number flag takes `value`. Fields left out stay as they are. Deployments see the change within seconds, without a redeploy.

        **Permissions:** Owners, admins and members.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                on:
                  type: boolean
                rollout:
                  type: integer
                  minimum: 1
                  maximum: 100
                value:
                  type:
                    - string
                    - number
      responses:
        "200":
          description: The flag.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Flag"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: flag
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/FlagEnvironmentName"
    post:
      tags:
        - Flags
      operationId: addFlagRule
      summary: Add a targeting rule
      description: |-
        Rules are checked in order before the environment's switch: the first that matches decides, `serve` being on or off for a boolean flag and the value for the others. `attribute` names what the app passes to `flag()` (`email`, `id`, `plan`, `user.country`); `one_of` takes several values, every other operator one; comparisons ignore case, and an attribute the app didn't pass matches nothing. 20 rules at most.

        **Permissions:** Owners, admins and members.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - attribute
                - operator
                - values
                - serve
              properties:
                attribute:
                  type: string
                  maxLength: 64
                  examples:
                    - email
                operator:
                  $ref: "#/components/schemas/FlagRuleOperator"
                values:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                    maxLength: 200
                  examples:
                    - - "@kudi.ng"
                serve:
                  type:
                    - boolean
                    - string
                    - number
      responses:
        "201":
          description: The flag.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Flag"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: flag
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/FlagEnvironmentName"
      - name: rule
        in: path
        required: true
        schema:
          type: string
    patch:
      tags:
        - Flags
      operationId: updateFlagRule
      summary: Change what a rule serves
      description: "**Permissions:** Owners, admins and members."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - serve
              properties:
                serve:
                  type:
                    - boolean
                    - string
                    - number
      responses:
        "200":
          description: The flag.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Flag"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - Flags
      operationId: removeFlagRule
      summary: Remove a rule
      description: "**Permissions:** Owners, admins and members."
      responses:
        "204":
          description: Removed.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/workflows:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Workflows
      operationId: getWorkflows
      summary: A project's workflows and recent runs
      description: |-
        The Workflows page. `workflows` are what the production deployment's `@useorbits/workflows` lists, read once it went live: each with its trigger as the page says it ("Every 15 minutes", "When order.paid happens"), its last run, and the share of its finished runs in the last 7 days that succeeded (null without any). `runs` are the 50 newest, each with its steps.

        A run's steps are the `step()`, `sleep()` and `waitFor()` calls it reached, in order. A step `running` with an `error` failed an attempt and is waiting for its retry (`next_at`). Steps the workflow took on its last successful run that this run hasn't reached are listed after them: `waiting` while it runs, `skipped` once it failed or was canceled.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The workflows and runs.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowsPage"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/workflows/{workflow}/runs:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: workflow
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Workflows
      operationId: runWorkflow
      summary: Run a workflow now
      description: |-
        Starts a run on the production deployment with `input` (any JSON, 256 KB at most), as Run now does. The builder picks it up within seconds.

        **Permissions:** Owners, admins and members. Viewers get 403. 404 when the production deployment doesn't list the workflow; 409 without a production deployment.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  description: Any JSON.
      responses:
        "201":
          description: The run.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/workflows/runs/{run}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: run
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Workflows
      operationId: getWorkflowRun
      summary: One run and its steps
      description: "**Permissions:** Any team member."
      responses:
        "200":
          description: The run.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/workflows/runs/{run}/cancel:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: run
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Workflows
      operationId: cancelWorkflowRun
      summary: Cancel a running run
      description: |-
        The app isn't called for it again; a step already running finishes, and its result is dropped. 409 for a run that isn't running.

        **Permissions:** Owners, admins and members.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: The run.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/workflows/runs/{run}/retry:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: run
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Workflows
      operationId: retryWorkflowRun
      summary: Retry a failed run from the step that failed
      description: |-
        The steps before the failed one keep their results; the failed one runs again with a fresh set of attempts, and the run goes on from there. 409 for a run that didn't fail.

        **Permissions:** Owners, admins and members.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: The run.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/sandboxes:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Sandboxes
      operationId: listSandboxes
      summary: A project's sandboxes
      description: |-
        The Sandboxes page: every sandbox, the live ones first and then by most recently started. `running` counts the live ones (starting or running) and `limit` is the most a team may run at once, for "2 of 3 running" and to disable Create at the cap. `as_of` is the server's clock, for the page's relative times. The page polls this while any sandbox is `starting`.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The sandboxes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxPage"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags:
        - Sandboxes
      operationId: createSandbox
      summary: Start a sandbox
      description: |-
        Provisions a machine and boots it: `state` is `starting`, then `running` once it is up (poll `GET .../sandboxes`). `clone` checks out the project's repository at `main`; `env` copies the Preview environment variables in. `size` caps CPU, memory and disk; `stop_after` is the idle minutes before it suspends itself. Names are lowercase letters, digits and single dashes, unique among the project's live sandboxes.

        A team runs at most `SandboxPage.limit` sandboxes at once; past that this returns 409 and the page offers to stop one first.

        **Runtime (v1):** a sandbox is a Docker container on the build host, capped by cgroups, with the terminal backed by `docker exec`. Stronger isolation (Firecracker microVMs) is a later swap that does not change this contract.

        **Permissions:** Owners, admins and members. Viewers get 403.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxCreate"
      responses:
        "201":
          description: The new sandbox, starting.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/sandboxes/{sandbox}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: sandbox
        in: path
        required: true
        description: The sandbox's name.
        schema:
          type: string
    get:
      tags:
        - Sandboxes
      operationId: getSandbox
      summary: A sandbox, its usage and open ports
      description: |-
        The sandbox's page: its `usage` against the size's ceiling, the `terminal` output so far, and the `ports` it listens on (port 3000, team-only, in v1). Use `{sandbox}` from `GET .../sandboxes`.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The sandbox.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxDetail"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags:
        - Sandboxes
      operationId: deleteSandbox
      summary: Delete a sandbox
      description: |-
        Terminates the machine and frees its disk. Irreversible; unlike stop, nothing is kept.

        **Permissions:** Owners, admins and members. Viewers get 403.
      responses:
        "204":
          description: Deleted.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/sandboxes/{sandbox}/stop:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: sandbox
        in: path
        required: true
        description: The sandbox's name.
        schema:
          type: string
    post:
      tags:
        - Sandboxes
      operationId: stopSandbox
      summary: Suspend a sandbox
      description: |-
        Suspends the sandbox: CPU and memory are released, the disk is kept, and `start` resumes it with the work intact. The idle auto-stop does the same, so a timeout never loses work. `state` becomes `stopped`. Already stopped is a no-op 200.

        **Permissions:** Owners, admins and members. Viewers get 403.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: The suspended sandbox.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/sandboxes/{sandbox}/start:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: sandbox
        in: path
        required: true
        description: The sandbox's name.
        schema:
          type: string
    post:
      tags:
        - Sandboxes
      operationId: startSandbox
      summary: Resume a sandbox
      description: |-
        Resumes a stopped sandbox from its kept disk: `state` is `starting`, then `running` (poll `GET .../sandboxes`). Counts against the team's live limit, so this returns 409 when the team is already at `SandboxPage.limit`. Already running is a no-op 200.

        **Permissions:** Owners, admins and members. Viewers get 403.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: The sandbox, starting.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/sandboxes/{sandbox}/terminal-ticket:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: sandbox
        in: path
        required: true
        description: The sandbox's name.
        schema:
          type: string
    post:
      tags:
        - Sandboxes
      operationId: createSandboxTerminalTicket
      summary: A ticket to open the sandbox's terminal
      description: |-
        A WebSocket opened by a browser can't carry the session or a bearer, so the terminal (`GET .../sandboxes/{sandbox}/terminal`) takes this ticket in its `ticket` query parameter instead. The ticket (`sbt_…`) admits the caller to this one sandbox's terminal for 60 seconds: get one right before opening the socket. It is signed, not stored, so it can't be revoked before it expires. Takes no body. The answer is never cached and the call ignores `Idempotency-Key`, so every call mints a new ticket.

        No plan check of its own: the sandbox must be `running` (else 409), and only Pro can start one.

        **Permissions:** Any team member, viewers included. A session or a `full` API token may call it (a token limited to one project only for that project); a `read` token gets 403, because this is a POST. A non-member gets 404.
      responses:
        "200":
          description: The ticket.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxTerminalTicket"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/alerts:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Alerts
      operationId: listAlerts
      summary: A project's alert rules and their state
      description: |-
        The Alerts card on Observability: every rule of the project, oldest first, with its state. A rule watches production's requests (the same traffic as Observability) and is checked every minute, at :30, over its last `window_minutes` whole minutes. It fires as soon as its value is past the line (above `threshold`, or below it for `direction: below`), and resolves after 3 checks in a row back on the right side. `error-rate`, `p75` and `p99` need 20 requests in the window to say anything: under that a rule can't fire, and `last_value` is null. A firing rule counts such a check toward resolving, unless what few requests there were are still past the line, and resolves with `reason: quiet` when the last of the 3 is one. `webhook_configured` says whether `webhook` can be offered as a channel.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The rules.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertPage"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags:
        - Alerts
      operationId: createAlert
      summary: Create an alert rule
      description: |-
        The Create alert form. The rule starts `ok` and is first checked at the next :30. 422 names the field: a name already used in the project, `direction: below` for anything but `requests`, an `error-rate` threshold of 100 or more, a route that doesn't start with `/` or has a `*` anywhere but the end, or `webhook` in `channels` while the team has no webhook (`webhook_configured` on the list).

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AlertCreate"
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Alert"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/alerts/preview:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    post:
      tags:
        - Alerts
      operationId: previewAlert
      summary: How much traffic a draft rule would see
      description: |-
        For the Create and Edit forms. `median_requests` is the median number of requests a window of this size held over the last 24 hours on these routes (minutes without traffic count as none). When it is under `minimum_requests` (20 for `error-rate`, `p75` and `p99`; 0 for `requests`), warn under the window field, for example "These routes get about 6 requests in 1 minute. The rule won't fire until a window has 20. Try 5 or 10 minutes." It is a warning: the form can still be saved. `value` is what the rule would measure now, or null with too little traffic.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AlertPreviewRequest"
      responses:
        "200":
          description: The traffic and the value now.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertPreview"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/projects/{project}/alerts/{alert}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: alert
        in: path
        required: true
        schema:
          type: string
        description: An `alr_` id from `GET .../alerts`.
    patch:
      tags:
        - Alerts
      operationId: updateAlert
      summary: Change or switch an alert rule
      description: |-
        The rule's switch, and the Edit dialog. Send only what changes. Any change, switching it off or on included, starts the rule again from `ok`. A rule that was firing first resolves, so a receiver sees its incident close: `reason: changed` for an edit, `off` when switched off. Changing `metric` away from `requests` sets `direction` to `above` unless one is sent. 422 as for create.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AlertUpdate"
      responses:
        "200":
          description: The rule as saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Alert"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - Alerts
      operationId: deleteAlert
      summary: Delete an alert rule
      description: |-
        Deletes the rule and its history. A rule that was firing sends `alert.resolved` with `reason: deleted` first.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      responses:
        "204":
          description: Deleted.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/alerts/{alert}/events:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: alert
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Alerts
      operationId: listAlertEvents
      summary: When a rule fired and resolved
      description: |-
        A rule's history, newest first, kept 90 days, with how each notification went (`deliveries`: one per channel, `pending` while it is still being tried, up to 5 times over about 30 minutes).

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        "200":
          description: One page of events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertEventPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/alert-channels:
    parameters:
      - $ref: "#/components/parameters/Team"
    get:
      tags:
        - Alerts
      operationId: getAlertChannels
      summary: The team's alert webhook
      description: |-
        The webhook every rule with the `webhook` channel sends to, one per team, or null. The secret is never shown again after it is made; `secret_last4` identifies it.

        **Permissions:** Owner or admin of the team. Members and viewers get 403 (the list's `webhook_configured` tells them whether one is set). A non-member gets 404.
      responses:
        "200":
          description: The webhook, or null.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertChannels"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/alert-channels/webhook:
    parameters:
      - $ref: "#/components/parameters/Team"
    put:
      tags:
        - Alerts
      operationId: setAlertWebhook
      summary: Set the team's alert webhook
      description: |-
        Sets the URL (https only). The first time, or with `rotate_secret`, a new secret is made and returned in `secret`, this once; the old one stops working at once. Otherwise `secret` is null and the secret is kept.

        Every request Orbits sends is a JSON `POST` with `X-Signature-256: sha256=<hex>` (HMAC-SHA256 of the raw body with the secret), `X-Delivery-Id` (the same on every retry of one notification) and `X-Orbits-Event` (`alert.fired`, `alert.resolved` or `alert.test`). The body is an AlertWebhookPayload. A 2xx answer is delivered; anything else, or no answer in 10 seconds, is tried again. Redirects aren't followed, and addresses that aren't on the public internet are refused. The webhook-receiver template verifies these as they are.

        **Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AlertWebhookSet"
      responses:
        "200":
          description: Saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertWebhookSaved"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - Alerts
      operationId: deleteAlertWebhook
      summary: Remove the team's alert webhook
      description: |-
        Notifications still waiting for the webhook fail with "The team has no webhook".

        **Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404.
      responses:
        "204":
          description: Removed.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/alert-channels/webhook/test:
    parameters:
      - $ref: "#/components/parameters/Team"
    post:
      tags:
        - Alerts
      operationId: testAlertWebhook
      summary: Send a test event to the webhook
      description: |-
        Sends a signed `alert.test` now and says how it went: `delivered` for a 2xx answer, otherwise the receiver's `status` (null when nothing answered) and an `error` to show. 404 when the team has no webhook.

        **Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: How the test went.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertWebhookTest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/deployments/{deployment}/redeploy:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    post:
      tags:
        - Deployments
      operationId: redeployDeployment
      summary: Build the same commit again
      description: |-
        The Redeploy modal: builds this deployment's commit again in the same environment, as a new deployment. A production redeploy takes over production when it is ready; until then production keeps serving the current build. A deployment that failed before its commit was known rebuilds its branch's newest commit. A dropped upload is rebuilt from its stored archive; only the project's last 5 are kept, and an older one is 409 `source_expired` (drop the site again).

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                use_cache:
                  type: boolean
                  default: true
      responses:
        "202":
          description: The new deployment, queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deployment"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/deployments/{deployment}/promote:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    post:
      tags:
        - Deployments
      operationId: promoteDeployment
      summary: Promote to production
      description: |-
        The Promote modal: rebuilds a ready deployment's commit with production's environment variables, as a new production deployment that goes live when it is ready. The current version stays live until then. Promoting also lifts a rollback's pause on auto-deploy.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: The new production deployment, queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deployment"
        "402":
          $ref: "#/components/responses/PlanRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/deployments/{deployment}/rollback:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    post:
      tags:
        - Deployments
      operationId: rollbackDeployment
      summary: Roll production back
      description: |-
        Points production at an earlier production build straight away, with no rebuild, and pauses auto-deploy so the next push does not replace it (pushes still build; they just do not go live). The answer's `undo` restores what production served before, through `POST .../projects/{project}/production`.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Production now serves it, and auto-deploy is paused.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ProductionChange"
                  - type: object
                    required:
                      - undo
                    properties:
                      undo:
                        type: object
                        required:
                          - deployment_id
                          - auto_deploy_paused
                        description: Send as the body of `POST .../projects/{project}/production` to undo.
                        properties:
                          deployment_id:
                            type:
                              - string
                              - "null"
                          auto_deploy_paused:
                            type: boolean
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/deployments/{deployment}/cancel:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - $ref: "#/components/parameters/Deployment"
    post:
      tags:
        - Deployments
      operationId: cancelDeployment
      summary: Cancel a build
      description: |-
        "Cancel deployment": a queued deployment is canceled at once; a building one is stopped by its builder within a few seconds (the answer still says `building`; poll until it says `canceled`). Nothing it built goes live.

        **Permissions:** Owner, admin or member. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Canceled, or being stopped.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deployment"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/env:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    get:
      tags:
        - Environment variables
      operationId: listEnvVars
      summary: List variables
      description: |-
        The Environment variables page: one row per `key`, with the environments it applies to. Values are encrypted at rest. A row's `value` is returned only for a variable that is not `sensitive` and whose key is meant for the browser (it starts with `NEXT_PUBLIC_`, `NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`, `REACT_APP_` or `EXPO_PUBLIC_`, or ends with `_PUBLIC_KEY`); every other `value` is `null` and the page shows dots. A `sensitive` variable can never be read back by anyone (the dialog says "Nobody can read it back, only replace it"), so show no eye icon, Reveal value or Copy value for it. For any other variable, "Reveal value" and "Copy value" call `POST /v1/teams/{team}/projects/{project}/env/{key}/reveal`.

        `total` is the number of variables that match the filters ("10 variables"). `last_changed` feeds the pull dialog ("Last changed yesterday by Shady Asaolu"); it is `null` when there are none. `redeploy` drives the blue banner ("You changed 1 variable. Redeploy so production picks it up."): `required` is true when something changed since the project's latest deployment and `changed` counts those variables; each row's `pending_redeploy` marks the ones to highlight (the "New" tag). Until deployments exist, `redeploy.required` is always false.

        **Permissions:** Any team member, including viewers. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: environment
          in: query
          description: Only variables that apply to this environment.
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: q
          in: query
          description: Substring of the key.
          schema:
            type: string
      responses:
        "200":
          description: Variables.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvVarPage"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags:
        - Environment variables
      operationId: createEnvVars
      summary: Add variables, or import a .env file
      description: |-
        Saves one or more variables. The Add variable dialog sends one with the default `on_conflict: fail`: a key that already exists is 409 and nothing is saved (use Edit instead). The Import .env dialog sends every parsed line with `on_conflict: replace`, which replaces the value and environments of keys that already exist, as its warning says ("Importing replaces its value in the environments you pick"). The dialog parses the file in the browser; show the conflicts from the list you already loaded. `sensitive` defaults to true, as the Sensitive checkbox does.

        A project can have at most 1,000 variables. An import that would go over (replacing existing keys adds none) is 422 on `variables` and saves nothing. The request body is at most 1 MiB, which the gateway enforces on every request (413), so a very large import must be split.

        The new values apply to deployments created afterwards; `redeploy_required` says whether the banner should show.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnvVarCreate"
      responses:
        "201":
          description: Saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvVarBatchResult"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/projects/{project}/env/{key}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: key
        in: path
        required: true
        schema:
          type: string
    patch:
      tags:
        - Environment variables
      operationId: updateEnvVar
      summary: Change a value or its environments
      description: |-
        The Edit dialog: the key is read-only ("To rename a key, add a new one and delete this one"). Send `value` only when the user typed a new one; leave it out to change just the environments. Send `environments` only when the checkboxes changed. At least one of them is required. Whether a variable is `sensitive` cannot be changed here.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnvVarUpdate"
      responses:
        "200":
          description: Saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvVarChange"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - Environment variables
      operationId: deleteEnvVar
      summary: Delete a variable
      description: |-
        The Delete dialog ("Type STRIPE_SECRET_KEY to confirm"; the typed confirmation is checked in the browser). The variable is hidden at once but its encrypted value is kept until `restorable_until` (10 minutes), so the toast's Undo can call `POST /v1/teams/{team}/projects/{project}/env/{key}/restore`. Deployments created after the delete no longer get it.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      responses:
        "200":
          description: Deleted, and restorable until `restorable_until`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvVarDeleted"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/projects/{project}/env/{key}/restore:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: key
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Environment variables
      operationId: restoreEnvVar
      summary: Undo a delete
      description: |-
        The Undo button on the "deleted" toast. It brings the variable back with the value and environments it had. 404 means the 10 minutes have passed (or it was never deleted); 409 means a variable with that key exists again.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Restored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvVarChange"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/env/{key}/reveal:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
      - name: key
        in: path
        required: true
        schema:
          type: string
    post:
      tags:
        - Environment variables
      operationId: revealEnvVar
      summary: Reveal a value
      description: |-
        "Reveal value" and "Copy value" (and the eye icon) on a row. It is a POST because every reveal is recorded as a `project.env.revealed` event with who asked and which key, never the value. A `sensitive` variable answers 409: it can never be read back. The response is never cached or replayed: this call ignores `Idempotency-Key`, so every call reads the value again and is recorded.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      responses:
        "200":
          description: The value.
          headers:
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvVarValue"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/projects/{project}/env/pull:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Project"
    post:
      tags:
        - Environment variables
      operationId: pullEnvVars
      summary: Download values for local development (`orbits env pull`)
      description: |-
        What `orbits env pull` calls to write `.env.local`. It returns the values of every variable that applies to `environment`, except `sensitive` ones, which nobody can read back: their keys are listed in `skipped_sensitive` so the CLI can tell the user. Every pull is recorded as a `project.env.pulled` event. The response is never cached or replayed: this call ignores `Idempotency-Key`, so every call reads the values again and is recorded. The dashboard only shows the pull dialog; it does not call this endpoint.

        **Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - environment
              properties:
                environment:
                  $ref: "#/components/schemas/EnvironmentName"
      responses:
        "200":
          description: Values for the environment.
          headers:
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvVarPull"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/domains:
    get:
      tags:
        - Domains
      operationId: listDomains
      summary: The team's domains
      description: |-
        The team's Domains and DNS page: every domain the team added, newest first, with the page's counts and the projects for its filter. A project's Domains page is this list with `project` set. Teams have a handful of domains, so the list isn't paged.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - name: q
          in: query
          schema:
            type: string
            maxLength: 253
          description: Part of a domain's name or its project's name.
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/DomainState"
        - name: dns
          in: query
          schema:
            $ref: "#/components/schemas/DnsMode"
        - name: project
          in: query
          schema:
            type: string
          description: A project's `id` or `slug`.
      responses:
        "200":
          description: The team's domains that match.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomainList"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
    post:
      tags:
        - Domains
      operationId: addDomain
      summary: Add a domain
      description: |-
        The Add domain dialog, on the team's Domains and DNS page or a project's Domains page. The domain starts `pending`. With `dns: external`, show `required_record` for the team to add at its DNS provider. With `dns: orbits`, the domain becomes a zone of its own: show `nameservers.names` for the team to set at its registrar (an apex, `host: "@"`) or to add as NS records for that name at its parent's DNS (a subdomain such as `dns-test.example.com`); Orbits then serves the whole zone, keeps the records its projects need, and the team manages the rest (`.../records`). A name inside a zone the team already has on Orbits DNS is on Orbits DNS too, whatever `dns` says: its record is created for it. Zones never nest: a zone around one already on Orbits DNS is refused (422 `dns`), and so is one inside or around another team's (409 `domain`). Orbits looks for it every minute (and at once with `POST .../checks`), issues the certificate once it's found, then serves the project on it. The person who added it gets an email when it's live, and another if DNS still isn't there an hour later.

        A domain the team already has that serves nothing (a zone moved to Orbits DNS before any project was picked) can be typed into a project's Add domain dialog like a new one: this call links it (200) instead of refusing it. `GET .../domains/preview` says beforehand what adding a name would do, for the dialog's note.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  maxLength: 253
                  examples:
                    - shop.shadyventures.ng
                  description: "As typed: a scheme, path or trailing dot comes off, and it is lowercased."
                dns:
                  $ref: "#/components/schemas/DnsMode"
                project:
                  type:
                    - string
                    - "null"
                  description: A project's `id` or `slug`.
                branch:
                  type:
                    - string
                    - "null"
                  maxLength: 128
                  description: Serve this branch's newest ready preview instead of production. Needs `project`.
                to:
                  type:
                    - string
                    - "null"
                  maxLength: 253
                  description: Redirect every request (308, same path) to this hostname instead of serving.
      responses:
        "200":
          description: "The team already had this domain and it served nothing (a zone moved to Orbits DNS before a project was picked, say): it now serves what the request asks, as `PATCH .../domains/{domain}` would. `dns` is ignored; the domain keeps its own."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Domain"
        "201":
          description: Added, `pending` until its record is found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Domain"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: This team already has the domain and it serves something already, or the request names nothing for it to serve; or another team has it (`errors[0].field` is `domain`).
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/domains/preview:
    get:
      tags:
        - Domains
      operationId: previewDomain
      summary: What adding a domain would do
      description: |-
        The Add domain dialogs' note, as the person types: whether the name would use outside DNS (one record to add, `required_record`), sit inside one of the team's Orbits DNS zones (`zone`, Orbits adds the record), or become a zone of its own (`nameservers`); and whether the team has it already (`existing`, which Add links to the project when it serves nothing). Nothing is saved. Checks the same rules as Add, with the same errors.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - name: domain
          in: query
          required: true
          schema:
            type: string
            maxLength: 253
        - name: dns
          in: query
          schema:
            $ref: "#/components/schemas/DnsMode"
      responses:
        "200":
          description: What Add would do.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomainPreview"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Another team has the domain, or a zone of another team's holds or sits inside it (`errors[0].field` is `domain`).
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/domains/{domain}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Domain"
    get:
      tags:
        - Domains
      operationId: getDomain
      summary: A domain
      description: |-
        A domain's page: its state, the record it needs and what the last check found, the hostname card (which project and branch it serves, or where it redirects) and its certificate. While it's `pending`, refresh the page every few seconds or call `POST .../checks`.

        **Permissions:** Any team member. A non-member, or a domain of another team, gets 404.
      responses:
        "200":
          description: The domain.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Domain"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags:
        - Domains
      operationId: updateDomain
      summary: Change what a domain serves
      description: |-
        The hostname card's Change: point the domain at another project, a branch, production again, a redirect, or nothing (`project: null` leaves it "Not in use"). Send only what changes; `null` clears a field. The name and DNS mode don't change: remove the domain and add it again.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  type:
                    - string
                    - "null"
                branch:
                  type:
                    - string
                    - "null"
                  maxLength: 128
                to:
                  type:
                    - string
                    - "null"
                  maxLength: 253
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Domain"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - Domains
      operationId: removeDomain
      summary: Remove a domain
      description: |-
        Remove domain, after the dialog's confirmation. The project stops answering on it within a minute and its certificate is deleted. The record at the team's DNS provider stays until they delete it there.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      responses:
        "204":
          description: Removed.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/domains/{domain}/checks:
    post:
      tags:
        - Domains
      operationId: checkDomain
      summary: Look for the domain's DNS now
      description: |-
        Check now. Orbits looks up the domain's DNS at once and answers with the domain as it stands, `checked_at` included. A domain checked in the last 10 seconds isn't looked up again; the answer is the same. Orbits also checks by itself every minute while a domain waits, and every 10 minutes once it's valid. A certificate follows within about a minute of DNS being found.

        **Permissions:** Any team member: checking changes nothing the team chose. A non-member gets 404.

        This call ignores `Idempotency-Key`.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Domain"
      responses:
        "200":
          description: The domain after the check.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Domain"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/Unavailable"
  /teams/{team}/domains/{domain}/records:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Domain"
    get:
      tags:
        - DNS
      operationId: listDnsRecords
      summary: A zone's records
      description: |-
        The DNS records table on an Orbits DNS domain's page: every record the zone serves, the team's own and the ones Orbits manages for its projects (`used_by.kind: project`, `managed: true`, locked: they change from that project's Domains page). Email records (`used_by.kind: email`) came with Email setup and stay editable. The zone also has its SOA and NS records, which aren't listed.

        **Permissions:** Any team member. A non-member gets 404.
      responses:
        "200":
          description: The zone's records, by name then type.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DnsRecordList"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags:
        - DNS
      operationId: addDnsRecord
      summary: Add a record
      description: |-
        Add a DNS record. It's served within about a minute. A name Orbits manages for a project (the apex and `www` of a zone in use, a subdomain added as a domain) can't take another record there: add the domain from the project's Domains page instead. A CNAME can't share its name with any other record, and can't sit at `@`.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DnsRecordInput"
      responses:
        "201":
          description: Added.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DnsRecord"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/domains/{domain}/records/{record}:
    parameters:
      - $ref: "#/components/parameters/Team"
      - $ref: "#/components/parameters/Domain"
      - name: record
        in: path
        required: true
        schema:
          type: string
          pattern: ^rec_
    put:
      tags:
        - DNS
      operationId: replaceDnsRecord
      summary: Edit a record
      description: |-
        The record menu's Edit: the record is replaced by what's sent, under the same rules as adding one. Records Orbits manages for a project can't be edited (409).

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DnsRecordInput"
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DnsRecord"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Invalid"
    delete:
      tags:
        - DNS
      operationId: deleteDnsRecord
      summary: Delete a record
      description: |-
        The record menu's Delete, after its confirmation. Records Orbits manages for a project can't be deleted (409): remove the domain from the project instead.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      responses:
        "204":
          description: Deleted.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /teams/{team}/domains/{domain}/zone-imports:
    post:
      tags:
        - DNS
      operationId: importZoneFile
      summary: Import a BIND zone file
      description: |-
        Import zone file. Send the pasted or dropped file with `dry_run: true` to show "4 records found: 1 new, 3 already here", then again without it to add the new ones. Records already in the zone (same type, name and value) are left as they are. Lines Orbits can't use (SOA, NS, records for another domain, types it doesn't host, names Orbits manages for a project) are counted in `skipped`, not guessed at.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Domain"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - zone
              properties:
                zone:
                  type: string
                  maxLength: 200000
                  description: The zone file as text.
                dry_run:
                  type: boolean
                  default: false
      responses:
        "200":
          description: What the file holds, and what was (or would be) added.
          content:
            application/json:
              schema:
                type: object
                required:
                  - found
                  - added
                  - existing
                  - skipped
                  - records
                properties:
                  found:
                    type: integer
                    description: Records in the file Orbits can use.
                  added:
                    type: integer
                  existing:
                    type: integer
                    description: Already in the zone.
                  skipped:
                    type: integer
                    description: Lines Orbits can't use.
                  records:
                    type: array
                    items:
                      $ref: "#/components/schemas/DnsRecordInput"
                    description: The ones added (or to be added).
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/domains/{domain}/email:
    get:
      tags:
        - DNS
      operationId: getEmailSetup
      summary: The Email setup dialog
      description: |-
        Set up email for a zone: the provider set up now (the Active badge), how many of the zone's records came with it or are mail records ("Already set up · 5 records"), and for each provider the records Setup would add, less any that would clash with the team's own or Orbits' (for "Adds 5 MX records and SPF"). `other` is "Something else" and adds nothing. A name inside a zone answers with its zone's.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Domain"
      responses:
        "200":
          description: The dialog's state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailSetup"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      tags:
        - DNS
      operationId: setEmailProvider
      summary: Set up email for a zone
      description: |-
        Email setup: the zone's MX and SPF records for one provider, in place of the last provider's (records added by Email setup, `used_by.kind: email`). DMARC and the team's other TXT records stay. DKIM keys belong to the team's mail account, so they're added as records afterwards. `other` ("Something else") clears the provider and keeps every record, for the team to manage.

        **Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - $ref: "#/components/parameters/Domain"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - provider
              properties:
                provider:
                  type: string
                  enum:
                    - zoho
                    - google
                    - microsoft
                    - other
      responses:
        "200":
          description: The zone's records after the change.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DnsRecordList"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /teams/{team}/integrations:
    get:
      tags:
        - Integrations
      operationId: listIntegrations
      summary: Catalog with installed state
      description: |-
        The Integrations page: the Browse tab cards (name, description, Installed or Install) and the Installed tab rows (name, a one-line summary, scope, when it was installed, by whom).

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
      responses:
        "200":
          description: Catalog.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Integration"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          description: The Git providers' state could not be read.
  /teams/{team}/usage:
    get:
      tags:
        - Usage and activity
      operationId: getUsage
      summary: A month of the team's usage, by day and by project
      description: |-
        The team's Usage page and its CSV, a project's Usage page (its `by_project` row), and the overview's usage panel. Days are Lagos days. `requests`, `bandwidth_bytes` (bytes the edge sent, headers included) and `log_lines` come from a daily rollup of the runtime logs kept 400 days; bandwidth is counted from when the edge started recording it, so earlier requests count 0 bytes. `build_minutes` (start to finish of each build, failed ones included) and `deployments` count deployments by the day they were created, back to the team's first. `function_runs` counts requests to projects with a `function` workload (also in `requests`): each is a call to the function, though functions run as one long-lived server until a per-call runtime ships. Figures for today are as of the call.

        `previous` is the same days of the month before, for "+18% on September", or null when the team had no deployments before this month. `months` lists every month from the team's first deployment to now, newest first.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - name: month
          in: query
          schema:
            type: string
            pattern: ^\d{4}-(0[1-9]|1[0-2])$
          description: Defaults to this month. A month still to come is 422.
      responses:
        "200":
          description: The month's usage.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Usage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /teams/{team}/activity:
    get:
      tags:
        - Usage and activity
      operationId: listActivity
      summary: Team activity feed
      description: |-
        The team's Activity page and its export: what happened across the team, newest first, one sentence each. Deployments (a preview started, production deployed, promoted or rolled back, a build failed), environment variables (added, updated, removed, restored, revealed, pulled), projects (created, renamed, settings changed, paused, deleted, moved in), members (joined, left, role changed), team settings and integrations (GitHub connected or disconnected). Invites and domains aren't in it yet. Lines are written from the platform's events a moment after they happen, kept 90 days, and read as they did then: a project or member renamed since keeps its old name in older lines.

        **Permissions:** Any team member. A non-member gets 404.
      parameters:
        - $ref: "#/components/parameters/Team"
        - name: q
          in: query
          schema:
            type: string
            maxLength: 200
          description: Matches the sentence, the actor's name or the project's name, in any case.
        - name: actor
          in: query
          schema:
            type: string
          description: A person's `id` from `people`.
        - name: project
          in: query
          schema:
            type: string
          description: A project's `id` or `slug`.
        - name: type
          in: query
          schema:
            type: string
            examples:
              - deployments
              - variables,projects
          description: One `ActivityCategory`, or several separated by commas.
        - name: since
          in: query
          schema:
            type: string
            format: date-time
          description: Oldest line to return; defaults to 7 days ago, and is clamped to 90 days ago.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          schema:
            type: string
          description: "`next_cursor` from the previous page."
      responses:
        "200":
          description: One page of lines, newest first, and how many match.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivityPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Invalid"
  /operations/{operation}:
    get:
      tags:
        - Usage and activity
      operationId: getOperation
      summary: Poll an asynchronous operation
      description: |-
        Poll an asynchronous operation.

        **Permissions:** The starter of the operation or an owner or admin of the team it ran in.
      parameters:
        - name: operation
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Operation"
        "404":
          $ref: "#/components/responses/NotFound"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Opaque session token or team API token. No long-lived JWTs are issued to browsers.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 128
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
    Team:
      name: team
      in: path
      required: true
      description: Team slug or `team_` id.
      schema:
        type: string
    Project:
      name: project
      in: path
      required: true
      description: Project slug or `prj_` id.
      schema:
        type: string
    Deployment:
      name: deployment
      in: path
      required: true
      schema:
        type: string
        pattern: ^dpl_
    Domain:
      name: domain
      in: path
      required: true
      description: The domain's name, or its `dom_` id.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      headers:
        WWW-Authenticate:
          description: 'From the gateway: `Bearer realm="orbits"`, plus `error="invalid_token"` when a bearer was sent and refused (wrong, revoked or expired).'
          schema:
            type: string
            examples:
              - Bearer realm="orbits", error="invalid_token"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Forbidden:
      description: Authenticated but not allowed in this team.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    NotFound:
      description: Not found, or not visible to the caller (the two are indistinguishable on purpose).
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Conflict:
      description: The request conflicts with current state.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Invalid:
      description: Validation failed, or the Idempotency-Key was reused with a different body.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    Unavailable:
      description: A store this endpoint reads is unreachable. Try again shortly.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    PlanRequired:
      description: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    Problem:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        request_id:
          type: string
        code:
          type: string
          description: "A stable reason, where one is defined: `plan_required` (402); `price_changed` and `already_pro` (409) and `billing_unavailable` (503) from billing."
        required_plan:
          type: string
          enum:
            - pro
          description: "On a 402: the plan that includes what was asked for."
        feature:
          type: string
          enum:
            - functions
            - sandboxes
            - analytics
            - speed_insights
          description: "On a 402: what the plan lacks."
        errors:
          type: array
          items:
            type: object
            required:
              - field
              - message
            properties:
              field:
                type: string
              message:
                type: string
    Invoice:
      type: object
      required:
        - id
        - kind
        - status
        - usd_cents
        - ngn_amount
        - fx_rate
        - period
        - reference
        - method
        - paid_at
        - created_at
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
            - initial
            - renewal
            - manual
          description: A first purchase, an automatic renewal, or a payment made by hand while already Pro or past due.
        status:
          type: string
          enum:
            - open
            - paid
            - failed
            - void
        usd_cents:
          type: integer
          description: The dollar price.
        ngn_amount:
          type: integer
          description: "Whole Naira charged: the dollar price at `fx_rate`, rounded up to a whole ₦100, locked when the invoice was made."
        fx_rate:
          type: string
          description: The USD → NGN rate it was converted at.
        period:
          type:
            - object
            - "null"
          description: The month it paid for; null until it is paid.
          required:
            - start
            - end
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        reference:
          type: string
        method:
          type:
            - string
            - "null"
          enum:
            - card
            - bank_transfer
            - other
            - null
          description: How it was paid; null until it is.
        paid_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
    Receipt:
      allOf:
        - $ref: "#/components/schemas/Invoice"
        - type: object
          required:
            - team
            - payer_email
            - description
            - card
          properties:
            team:
              type: object
              required:
                - id
                - slug
                - name
              properties:
                id:
                  type: string
                slug:
                  type: string
                name:
                  type: string
            payer_email:
              type:
                - string
                - "null"
              format: email
            description:
              type: string
              examples:
                - Orbits Pro
                - one month
            card:
              type:
                - object
                - "null"
              description: The card it was paid with; null when it is unpaid or was paid by bank transfer.
              required:
                - last4
              properties:
                brand:
                  type:
                    - string
                    - "null"
                last4:
                  type: string
                exp:
                  type:
                    - string
                    - "null"
    SourceUpload:
      type: object
      required:
        - id
        - method
        - url
        - headers
        - expires_at
        - max_bytes
      properties:
        id:
          type: string
          description: Pass it to `.../uploads/{upload}/complete`.
          examples:
            - upl_0192f3a6-0c1d-7a55-9a52-6f1f0f0f0f0f
        method:
          type: string
          const: PUT
        url:
          type: string
          format: uri
          description: A presigned storage URL. Treat it as a secret until it is used; it expires.
        headers:
          type: object
          additionalProperties:
            type: string
          description: Send exactly these headers with the file, and none besides (they are covered by the signature).
        expires_at:
          type: string
          format: date-time
        max_bytes:
          type: integer
          description: The largest zip accepted.
    Slug:
      type: string
      pattern: ^[a-z0-9]([a-z0-9-]{1,38})[a-z0-9]$
    Role:
      type: string
      enum:
        - owner
        - admin
        - member
        - viewer
    EnvironmentName:
      type: string
      enum:
        - production
        - preview
        - development
    Page:
      type: object
      properties:
        next_cursor:
          type:
            - string
            - "null"
    Operation:
      type: object
      required:
        - id
        - kind
        - state
        - created_at
      properties:
        id:
          type: string
          pattern: ^op_
        kind:
          type: string
          examples:
            - team.delete
            - project.transfer
            - domain.remove
        state:
          type: string
          enum:
            - pending
            - running
            - succeeded
            - failed
        resource:
          type: string
        created_at:
          type: string
          format: date-time
        finished_at:
          type:
            - string
            - "null"
          format: date-time
        error:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/Problem"
    User:
      type: object
      required:
        - id
        - email
        - name
      properties:
        id:
          type: string
          pattern: ^usr_
        email:
          type: string
          format: email
        name:
          type: string
        username:
          type:
            - string
            - "null"
          description: "Their handle: unique, lowercase letters, numbers and dashes. Null until they set one."
        avatar_url:
          type:
            - string
            - "null"
          format: uri-reference
          description: 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_enabled:
          type: boolean
          description: Whether the person has two-factor on. On a team member it is as of their last visit.
    Team:
      type: object
      required:
        - id
        - name
        - slug
        - role
        - plan
        - created_at
      properties:
        id:
          type: string
          pattern: ^team_
        name:
          type: string
        slug:
          $ref: "#/components/schemas/Slug"
        avatar_url:
          type:
            - string
            - "null"
          format: uri-reference
          description: A path on this API (`/v1/teams/{id}/avatar?v=…`) for an uploaded avatar.
        default_region:
          type: string
          examples:
            - abj-1
        role:
          $ref: "#/components/schemas/Role"
        require_two_factor:
          type: boolean
          description: Members without two-factor are refused on this team's routes (403).
        session_max_age_days:
          type: integer
          description: "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:
          type: string
          enum:
            - owners
            - members
          description: "`owners`: owners and admins invite. `members`: members may too (as member or viewer only)."
        sign_in_methods:
          type: array
          items:
            type: string
            enum:
              - email
              - github
              - gitlab
              - bitbucket
          description: 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:
          $ref: "#/components/schemas/PlanId"
        billing_alert:
          description: 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.
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/BillingAlert"
        created_at:
          type: string
          format: date-time
    PlanId:
      type: string
      enum:
        - free
        - pro
    PlanFeatures:
      type: object
      required:
        - unlimited_projects
        - functions
        - sandboxes
        - analytics
        - speed_insights
        - sleeps_when_idle
      properties:
        unlimited_projects:
          type: boolean
        functions:
          type: boolean
          description: The `function` workload type. On Free the same frameworks (Next.js, SvelteKit, Nuxt, Remix...) run as ordinary apps.
        sandboxes:
          type: boolean
        analytics:
          type: boolean
        speed_insights:
          type: boolean
        sleeps_when_idle:
          type: boolean
          description: "Apps scale to zero when idle (Free). Not running yet: Free apps stay on until that ships."
    Plan:
      type: object
      required:
        - id
        - name
        - usd_cents
        - ngn
        - features
      properties:
        id:
          $ref: "#/components/schemas/PlanId"
        name:
          type: string
          examples:
            - Pro
        usd_cents:
          type: integer
          examples:
            - 500
        ngn:
          type:
            - integer
            - "null"
          description: Whole Naira at the current rate, rounded up to a whole ₦100; 0 for Free; null while no rate is set.
          examples:
            - 8000
        features:
          $ref: "#/components/schemas/PlanFeatures"
    BillingAlert:
      description: "What the owners' banner says about the team's plan. `upcoming`: the renewal is within three days (`charge` says whether Orbits charges the card itself or the owner must pay). `payment_failed`: the last payment did not go through and Pro runs on until `grace_ends_at`; offer to pay now. `canceling`: Pro ends at `ends_at`; offer to keep it. `downgraded`: the team was put back on Free (shown for 30 days); offer to upgrade. `amount_ngn` is the price locked on the renewal invoice once it exists, else today's."
      oneOf:
        - type: object
          required:
            - kind
            - at
            - amount_ngn
            - charge
          properties:
            kind:
              type: string
              const: upcoming
            at:
              type: string
              format: date-time
            amount_ngn:
              type:
                - integer
                - "null"
            charge:
              type: string
              enum:
                - automatic
                - manual
        - type: object
          required:
            - kind
            - grace_ends_at
            - amount_ngn
          properties:
            kind:
              type: string
              const: payment_failed
            grace_ends_at:
              type: string
              format: date-time
            amount_ngn:
              type:
                - integer
                - "null"
        - type: object
          required:
            - kind
            - ends_at
          properties:
            kind:
              type: string
              const: canceling
            ends_at:
              type: string
              format: date-time
        - type: object
          required:
            - kind
            - at
          properties:
            kind:
              type: string
              const: downgraded
            at:
              type: string
              format: date-time
    Billing:
      type: object
      required:
        - plan
        - status
        - source
        - enforced
        - current_period
        - cancel_at_period_end
        - grace_ends_at
        - price
        - next_charge
        - entitlements
        - card
        - can_manage
        - banner
      properties:
        plan:
          $ref: "#/components/schemas/PlanId"
        status:
          type: string
          enum:
            - free
            - active
            - past_due
          description: "`past_due`: Pro, but the period has ended unpaid and the team is in its grace period."
        source:
          type:
            - string
            - "null"
          enum:
            - flutterwave
            - comp
            - null
          description: "`comp`: Pro granted by Orbits, nothing to pay. Null on Free."
        enforced:
          type: boolean
          description: Whether plan limits are switched on. When false every feature works for every team.
        current_period:
          oneOf:
            - type: "null"
            - type: object
              required:
                - start
                - end
              properties:
                start:
                  type: string
                  format: date-time
                end:
                  type:
                    - string
                    - "null"
                  format: date-time
                  description: Null for a plan with no end (`comp`).
        cancel_at_period_end:
          type: boolean
        grace_ends_at:
          type:
            - string
            - "null"
          format: date-time
        price:
          type: object
          description: Pro's price today, for the upgrade button.
          required:
            - usd_cents
            - ngn
            - rate
          properties:
            usd_cents:
              type: integer
            ngn:
              type:
                - integer
                - "null"
            rate:
              type:
                - string
                - "null"
        next_charge:
          oneOf:
            - type: "null"
            - type: object
              required:
                - usd_cents
                - ngn
              properties:
                usd_cents:
                  type: integer
                ngn:
                  type:
                    - integer
                    - "null"
        entitlements:
          type: object
          required:
            - functions
            - sandboxes
            - analytics
            - speed_insights
            - sleeps_when_idle
          description: What this team may do now. All true (and `sleeps_when_idle` false) while `enforced` is false.
          properties:
            functions:
              type: boolean
            sandboxes:
              type: boolean
            analytics:
              type: boolean
            speed_insights:
              type: boolean
            sleeps_when_idle:
              type: boolean
        card:
          oneOf:
            - type: "null"
            - type: object
              required:
                - brand
                - last4
                - exp
              description: The card on file, for owners only. Never the card number.
              properties:
                brand:
                  type:
                    - string
                    - "null"
                last4:
                  type: string
                  examples:
                    - "4471"
                exp:
                  type:
                    - string
                    - "null"
                  examples:
                    - 09/28
        can_manage:
          type: boolean
          description: True for owners, who may change billing.
        banner:
          description: The owners' notice about the plan, or null. Always null for members.
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/BillingAlert"
    Me:
      allOf:
        - $ref: "#/components/schemas/User"
        - type: object
          required:
            - teams
          properties:
            sign_in_methods:
              type: array
              description: The OAuth providers linked to this account. Email link is always available and is not listed here.
              items:
                type: string
                enum:
                  - github
                  - gitlab
                  - bitbucket
            time_zone:
              type:
                - string
                - "null"
              description: Their IANA time zone for clocks and dates. Null until they set one.
            product_updates:
              type: boolean
              description: Whether they opted in to product-update emails.
            session:
              type: object
              description: This session, as a team's sign-in method and session length rules see it.
              properties:
                method:
                  type:
                    - string
                    - "null"
                  enum:
                    - email
                    - github
                    - gitlab
                    - bitbucket
                    - api_token
                    - null
                  description: "`api_token` when the bearer is an API token. Null for a session from before methods were recorded."
                started_at:
                  type:
                    - string
                    - "null"
                  format: date-time
                  description: When the session signed in, or when the API token was made.
            token:
              type: object
              description: Only when the bearer is an API token (`orb_live_…`), what it may do. Absent for a session.
              required:
                - id
                - team_id
                - access
                - project_id
                - created_at
              properties:
                id:
                  type: string
                team_id:
                  type: string
                  description: The one team the token acts in.
                access:
                  type: string
                  enum:
                    - full
                    - read
                project_id:
                  type:
                    - string
                    - "null"
                  description: The one project the token is limited to, or null for every project of the team.
                created_at:
                  type: string
                  format: date-time
            teams:
              type: array
              description: The teams the caller belongs to (all of `GET /v1/teams`), each with a preview of its projects.
              items:
                allOf:
                  - $ref: "#/components/schemas/Team"
                  - type: object
                    required:
                      - project_count
                      - projects
                    properties:
                      project_count:
                        type: integer
                        description: All projects in the team.
                      projects:
                        type: array
                        description: The newest 20 projects, in the order of `GET /v1/teams/{team}/projects`. Compare with `project_count`, and call that endpoint for the rest.
                        items:
                          $ref: "#/components/schemas/Project"
    TeamDetail:
      allOf:
        - $ref: "#/components/schemas/Team"
        - type: object
          required:
            - members
          properties:
            notifications:
              $ref: "#/components/schemas/NotificationRules"
            members:
              type: array
              description: "Active members, then pending email invites (`status: invited`). Same rows as `GET /v1/teams/{team}/members` without `q`."
              items:
                $ref: "#/components/schemas/Member"
    TeamUpdate:
      type: object
      properties:
        name:
          type: string
        slug:
          $ref: "#/components/schemas/Slug"
        avatar_url:
          type:
            - string
            - "null"
          format: uri
        default_region:
          type: string
          enum:
            - abj-1
          description: Abuja is the only region in v1.
        require_two_factor:
          type: boolean
        session_max_age_days:
          type: integer
          minimum: 1
          maximum: 365
        inviters:
          type: string
          enum:
            - owners
            - members
        sign_in_methods:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - email
              - github
              - gitlab
              - bitbucket
          description: 422 when it leaves out the method the caller signed in with.
        notifications:
          type: object
          description: 'Only the switches that change, as `{"deploy.live": {"email": true}}`; the rest stay. 422 on `notifications` for an unknown event or channel.'
          additionalProperties:
            type: object
            properties:
              email:
                type: boolean
              slack:
                type: boolean
    NotificationRules:
      type: object
      description: |-
        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.
      required:
        - deploy.failed
        - deploy.live
        - domain.attention
        - member.joined
        - weekly
      properties:
        deploy.failed:
          $ref: "#/components/schemas/NotificationSwitches"
        deploy.live:
          $ref: "#/components/schemas/NotificationSwitches"
        domain.attention:
          $ref: "#/components/schemas/NotificationSwitches"
        member.joined:
          $ref: "#/components/schemas/NotificationSwitches"
        weekly:
          $ref: "#/components/schemas/NotificationSwitches"
    NotificationSwitches:
      type: object
      required:
        - email
        - slack
      properties:
        email:
          type: boolean
        slack:
          type: boolean
    TeamPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Team"
    TeamOverview:
      type: object
      required:
        - range
        - projects
        - deployments
        - requests
        - logs_available
      properties:
        range:
          type: string
        logs_available:
          type: boolean
          description: "False while the log store can't be reached: `requests` and `series.requests` are then zeros, not a quiet day. Show them as unavailable."
        projects:
          type: object
          properties:
            total:
              type: integer
            failing:
              type: integer
        deployments:
          type: object
          properties:
            total:
              type: integer
            delta_vs_previous:
              type: integer
        average_build_seconds:
          type: number
        requests:
          type: object
          properties:
            total:
              type: integer
            month_to_date:
              type: integer
        series:
          type: object
          description: The range in equal slices, oldest first.
          required:
            - deployments
            - average_build_seconds
            - requests
          properties:
            deployments:
              type: array
              items:
                type: integer
            average_build_seconds:
              type: array
              items:
                type: number
            requests:
              type: array
              items:
                type: integer
        needs_attention:
          type: array
          items:
            type: object
            required:
              - kind
              - message
            properties:
              kind:
                type: string
              message:
                type: string
              link:
                type: string
    Notification:
      type: object
      required:
        - id
        - type
        - title
        - detail
        - link
        - project
        - read
        - created_at
      properties:
        id:
          type: string
          pattern: ^act_
        type:
          type: string
          enum:
            - deployment.failed
            - domain.live
            - domain.misconfigured
            - domain.certificate.failed
            - team.member.added
            - alert.fired
          description: The event it came from.
        title:
          type: string
          examples:
            - store failed to deploy
            - shop.example.ng is live with HTTPS
        detail:
          type:
            - string
            - "null"
          examples:
            - Missing module 'mdsvex' · main
            - Check its DNS record
            - Invited by Tunde
          description: "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."
        link:
          type:
            - string
            - "null"
          examples:
            - /teams/rsty-org/projects/store/deployments/dpl_1
          description: A path of this API to open as the app's own page; null when there's nowhere to go.
        project:
          oneOf:
            - type: "null"
            - type: object
              required:
                - id
                - slug
                - name
              properties:
                id:
                  type: string
                slug:
                  type: string
                name:
                  type: string
        read:
          type: boolean
        created_at:
          type: string
          format: date-time
    NotificationPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - items
            - unread_count
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Notification"
            unread_count:
              type: integer
              maximum: 100
              description: The caller's unread notifications, up to 100.
    Member:
      type: object
      required:
        - user
        - role
        - status
      properties:
        user:
          $ref: "#/components/schemas/User"
        role:
          $ref: "#/components/schemas/Role"
        status:
          type: string
          enum:
            - active
            - invited
        invite_id:
          type: string
          description: Present only for invited rows; use it for resend and revoke operations.
        joined_at:
          type:
            - string
            - "null"
          format: date-time
        last_active_at:
          type:
            - string
            - "null"
          format: date-time
          description: 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.
    StaticWorkload:
      type: object
      required:
        - type
      properties:
        type:
          const: static
        output_directory:
          type: string
          examples:
            - dist
        spa_fallback:
          type: boolean
          default: false
    FunctionWorkload:
      type: object
      required:
        - type
      properties:
        type:
          const: function
        framework:
          type: string
          examples:
            - nextjs
        memory_mb:
          type: integer
          minimum: 128
        timeout_seconds:
          type: integer
          minimum: 1
    WorkerWorkload:
      type: object
      required:
        - type
        - command
      properties:
        type:
          const: worker
        command:
          type: array
          items:
            type: string
          minItems: 1
        replicas:
          type: integer
          minimum: 1
          default: 1
        schedule:
          type:
            - string
            - "null"
          description: Cron expression for scheduled jobs; null for a continuous worker.
    AppWorkload:
      type: object
      required:
        - type
        - port
      properties:
        type:
          const: app
        port:
          type: integer
          minimum: 1
          maximum: 65535
        health_check_path:
          type: string
          default: /
        replicas:
          type: integer
          minimum: 1
          default: 1
        start_command:
          type:
            - array
            - "null"
          items:
            type: string
    ContainerWorkload:
      type: object
      required:
        - type
        - port
      properties:
        type:
          const: container
        image:
          type:
            - string
            - "null"
          description: Prebuilt image reference. Mutually exclusive with `dockerfile_path`.
        dockerfile_path:
          type:
            - string
            - "null"
        port:
          type: integer
          minimum: 1
          maximum: 65535
        replicas:
          type: integer
          minimum: 1
          default: 1
    Workload:
      oneOf:
        - $ref: "#/components/schemas/StaticWorkload"
        - $ref: "#/components/schemas/FunctionWorkload"
        - $ref: "#/components/schemas/WorkerWorkload"
        - $ref: "#/components/schemas/AppWorkload"
        - $ref: "#/components/schemas/ContainerWorkload"
      discriminator:
        propertyName: type
        mapping:
          static: "#/components/schemas/StaticWorkload"
          function: "#/components/schemas/FunctionWorkload"
          worker: "#/components/schemas/WorkerWorkload"
          app: "#/components/schemas/AppWorkload"
          container: "#/components/schemas/ContainerWorkload"
    Source:
      type: object
      required:
        - provider
        - repository
        - production_branch
      properties:
        provider:
          type: string
          enum:
            - github
            - gitlab
            - bitbucket
            - gitbucket
        repository:
          type: string
          examples:
            - shadyventures/storefront
        production_branch:
          type: string
          default: main
        root_directory:
          type: string
          default: ./
    BuildConfig:
      type: object
      properties:
        framework:
          type:
            - string
            - "null"
        install_command:
          type:
            - string
            - "null"
          description: null means detected default.
        build_command:
          type:
            - string
            - "null"
        output_directory:
          type:
            - string
            - "null"
        ignore_command:
          type:
            - string
            - "null"
          description: "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_by:
          type:
            - object
            - "null"
          readOnly: true
          description: Who last changed a build setting ("Changed by Tunde Bakare yesterday").
          properties:
            id:
              type: string
            name:
              type: string
        changed_at:
          type:
            - string
            - "null"
          format: date-time
          readOnly: true
    ProjectStatus:
      type: string
      description: |-
        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).
      enum:
        - pending
        - building
        - ready
        - failed
        - paused
    GitSettings:
      type: object
      required:
        - deploy_on_push
        - preview_pull_requests
        - comment_on_pull_requests
      properties:
        deploy_on_push:
          type: boolean
          description: Pushes to the production branch go to production; other branches get a preview.
        preview_pull_requests:
          type: boolean
          description: Each pull request gets its own address.
        comment_on_pull_requests:
          type: boolean
          description: Post the preview link on the pull request and update it on every push.
    LatestDeployment:
      type: object
      description: The newest deployment, as shown on a project card. Null until the project has one.
      required:
        - id
        - state
        - created_at
      properties:
        id:
          type: string
          pattern: ^dpl_
        state:
          $ref: "#/components/schemas/DeploymentState"
        branch:
          type:
            - string
            - "null"
        commit_sha:
          type:
            - string
            - "null"
        commit_message:
          type:
            - string
            - "null"
          examples:
            - Update checkout copy
        author:
          type:
            - object
            - "null"
          properties:
            name:
              type: string
            avatar_url:
              type:
                - string
                - "null"
        failure_reason:
          type:
            - string
            - "null"
          examples:
            - Missing module 'mdsvex'
        created_at:
          type: string
          format: date-time
    Project:
      type: object
      required:
        - id
        - slug
        - name
        - workload
        - region
        - status
        - free_address
        - git
        - created_at
      properties:
        id:
          type: string
          pattern: ^prj_
        slug:
          $ref: "#/components/schemas/Slug"
        name:
          type: string
        free_address:
          type: string
          description: Host name, `<slug>.theorbits.app`.
          examples:
            - storefront.theorbits.app
        workload:
          $ref: "#/components/schemas/Workload"
        source:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/Source"
        source_kind:
          type: string
          enum:
            - git
            - upload
          default: git
          description: "`upload`: deployed by dropping files (`POST .../uploads`); `source` is null and there is no repository."
        build:
          $ref: "#/components/schemas/BuildConfig"
        framework_version:
          type:
            - string
            - "null"
          description: Shown next to the framework on the overview header, e.g. `15`.
          examples:
            - "15"
        node_version:
          type: string
          examples:
            - 22.x
        region:
          type: string
          examples:
            - abj-1
        status:
          $ref: "#/components/schemas/ProjectStatus"
        paused:
          type: boolean
        git:
          $ref: "#/components/schemas/GitSettings"
        preview_protection:
          type: string
          enum:
            - none
            - team_members
            - password
          default: team_members
          description: "Who may open previews (production stays public). `password`: the edge asks for the project's preview password and remembers it for 12 hours."
        production_url:
          type:
            - string
            - "null"
          format: uri
        latest_deployment_id:
          type:
            - string
            - "null"
        latest_deployment:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/LatestDeployment"
        thumbnail_url:
          type:
            - string
            - "null"
          format: uri-reference
          description: 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_color:
          type:
            - string
            - "null"
          pattern: ^#[0-9a-f]{6}$
          description: 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.
          examples:
            - "#7c3aed"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ProjectCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Also the source of the slug and free address, e.g. `checkout-v2`.
        slug:
          $ref: "#/components/schemas/Slug"
        workload:
          $ref: "#/components/schemas/Workload"
        source:
          $ref: "#/components/schemas/Source"
        template:
          type: string
          description: "Template `key` from `GET /v1/templates`. Mutually exclusive with `source`: Orbits creates the repository in the team's GitHub account."
        source_kind:
          type: string
          enum:
            - git
            - upload
          description: Default `git`. `upload` creates a project with no repository, deployed by dropping files (`POST /teams/{team}/projects/{project}/uploads`); no deployment is queued until the first drop. Not with `source` or `template`.
        build:
          $ref: "#/components/schemas/BuildConfig"
        region:
          type: string
          default: abj-1
        env:
          type: array
          maxItems: 500
          description: Environment variables from the Configure step (Used by Production and Preview). They are saved with the project in one step; field errors come back as `env[0].key`.
          items:
            $ref: "#/components/schemas/EnvVarInput"
    ProjectUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        workload:
          $ref: "#/components/schemas/Workload"
        source:
          $ref: "#/components/schemas/Source"
        build:
          $ref: "#/components/schemas/BuildConfig"
        git:
          $ref: "#/components/schemas/GitSettingsUpdate"
        node_version:
          type: string
          examples:
            - 22.x
        preview_protection:
          type: string
          enum:
            - none
            - team_members
            - password
        preview_password:
          type: string
          writeOnly: true
          minLength: 8
          description: Only with `preview_protection` `password`.
        region:
          type: string
    GitSettingsUpdate:
      type: object
      properties:
        deploy_on_push:
          type: boolean
        preview_pull_requests:
          type: boolean
        comment_on_pull_requests:
          type: boolean
    ProjectDeletionImpact:
      type: object
      required:
        - deployments
        - environment_variables
        - flags
        - domains
      properties:
        deployments:
          type: integer
          description: Deployments and their build logs.
        environment_variables:
          type: integer
        flags:
          type: integer
          description: Feature flags and their history.
        domains:
          type: integer
          description: Detached, not deleted; they stay in Domains and DNS.
    Template:
      type: object
      required:
        - key
        - name
        - description
        - category
        - framework
        - framework_label
        - required_env
        - optional_env
      properties:
        key:
          type: string
          examples:
            - store
        name:
          type: string
          examples:
            - Store
        description:
          type: string
          examples:
            - Product pages, cart, checkout
        category:
          type: string
          enum:
            - commerce
            - content
            - apps
            - apis
        framework:
          type: string
          examples:
            - nextjs
        framework_label:
          type: string
          examples:
            - Next.js
        required_env:
          type: array
          description: Variables the template can't start without; send each in `env` when creating the project.
          items:
            $ref: "#/components/schemas/TemplateEnvVar"
        optional_env:
          type: array
          description: Variables the template reads when they are set.
          items:
            $ref: "#/components/schemas/TemplateEnvVar"
        workload:
          description: How a project from this template runs. Absent means the framework's default.
          type: object
          additionalProperties: true
          examples:
            - type: app
              port: 3000
              health_check_path: /health
        node_version:
          type: string
          description: The Node.js version a project from this template gets, when it needs newer than the default.
          examples:
            - 24.x
    TemplateEnvVar:
      type: object
      required:
        - key
      properties:
        key:
          type: string
          examples:
            - PAYSTACK_SECRET_KEY
        hint:
          type:
            - string
            - "null"
          examples:
            - From Paystack, Settings → API Keys.
    ProjectPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Project"
    DeploymentState:
      type: string
      description: "`queued` waits for a builder; the screens show it as building."
      enum:
        - queued
        - building
        - ready
        - failed
        - canceled
    DeploymentEnvironment:
      type: string
      description: Where a deployment runs. `development` is only the local `orbits dev` target and an environment-variable scope.
      enum:
        - production
        - preview
    DeploymentStepKey:
      type: string
      description: The build log's fixed steps, in order. The screens label them Queued, Cloning repository, Installing packages, Building, Uploading and Going live.
      enum:
        - queued
        - cloning
        - installing
        - building
        - uploading
        - going_live
    DeploymentProject:
      type: object
      required:
        - id
        - slug
        - name
      properties:
        id:
          type: string
          pattern: ^prj_
        slug:
          type: string
        name:
          type: string
    Deployment:
      type: object
      required:
        - id
        - project
        - environment
        - state
        - trigger
        - branch
        - sha
        - message
        - author
        - created_by
        - url
        - current
        - went_live
        - redeploy_of
        - promoted_from
        - pull_request
        - use_cache
        - created_at
        - started_at
        - finished_at
        - duration_seconds
        - screenshot_url
        - warnings
      properties:
        id:
          type: string
          pattern: ^dpl_
        project:
          $ref: "#/components/schemas/DeploymentProject"
        environment:
          $ref: "#/components/schemas/DeploymentEnvironment"
        state:
          $ref: "#/components/schemas/DeploymentState"
        trigger:
          type: string
          description: "`git` a push, `manual` deployed by hand, `redeploy`, `promote`, `create` the first deploy of a new project."
          enum:
            - git
            - manual
            - redeploy
            - promote
            - create
        branch:
          type: string
          examples:
            - main
        sha:
          type:
            - string
            - "null"
          description: The full commit sha; null until the builder has cloned a branch head. The screens show its first 7 characters.
        message:
          type:
            - string
            - "null"
          description: The commit message's first line.
          examples:
            - Update checkout copy
        author:
          oneOf:
            - type: "null"
            - type: object
              required:
                - name
              properties:
                name:
                  type: string
                  examples:
                    - Shady Asaolu
        created_by:
          description: Who asked for it; null for a push.
          oneOf:
            - type: "null"
            - type: object
              required:
                - id
                - name
              properties:
                id:
                  type: string
                name:
                  type: string
        url:
          type:
            - string
            - "null"
          format: uri
          description: This deployment's own address, `https://<slug>-<sha7>.<domain>`; null until its sha is known. It answers while the deployment is production or the newest ready preview of its branch.
          examples:
            - https://storefront-a1f9c2e.theorbits.app
        current:
          type: boolean
          description: Production serves it now.
        went_live:
          type: boolean
          description: Production served it at some point.
        redeploy_of:
          type:
            - string
            - "null"
          description: The commit sha a redeploy rebuilt.
        promoted_from:
          type:
            - string
            - "null"
          description: The `dpl_` id of the deployment a promote rebuilt.
        pull_request:
          type:
            - integer
            - "null"
          description: The open pull request of the branch, for a preview.
        use_cache:
          type: boolean
        created_at:
          type: string
          format: date-time
        started_at:
          type:
            - string
            - "null"
          format: date-time
        finished_at:
          type:
            - string
            - "null"
          format: date-time
        duration_seconds:
          type:
            - integer
            - "null"
          description: From start to finish; null while it runs (count up from `started_at`).
        screenshot_url:
          type:
            - string
            - "null"
          format: uri-reference
          description: API path of the deployment's first screen (1280x800 JPEG), `GET /v1/teams/{team}/projects/{project}/deployments/{deployment}/screenshot`. Null until the builder has taken it, a few seconds after the deployment becomes ready; failed and canceled deployments never get one.
          examples:
            - /v1/teams/team_d6ecdb07-bdbd-47fa-af1f-1ea403f71e7b/projects/prj_c95dbb97-9f5a-4dc5-839c-200896eb0587/deployments/dpl_8725d680-7b4a-4699-8682-d1ea0649206a/screenshot
        warnings:
          type: array
          description: "What this deployment may be missing, for its page; empty when nothing is. `missing_env`: public variables the code reads (`import.meta.env.VITE_*`, `process.env.NEXT_PUBLIC_*`, `REACT_APP_*`, `PUBLIC_*`) that weren't set for this environment, nor in a committed `.env` or `.env.production`, when it built; they're baked into the build, so adding them takes a redeploy. Code may have a fallback, so it's a warning, not a failure. `page`: what the browser that takes the screenshot saw on the first load, a few seconds after the deployment became ready: the page's uncaught errors (up to three) and whether its first screen came out blank."
          items:
            $ref: "#/components/schemas/DeploymentWarning"
    DeploymentWarning:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - missing_env
            - page
        message:
          type: string
          examples:
            - VITE_SUPABASE_ANON_KEY and VITE_SUPABASE_URL are used in the code but not set for Production. The build bakes them in, so this deployment runs without them.
            - "The page threw an error as it loaded and came out blank: Error: supabaseUrl is required."
        keys:
          type: array
          items:
            type: string
          description: "`missing_env`: the variable names, sorted."
        errors:
          type: array
          items:
            type: string
          description: "`page`: the uncaught errors, first three."
        blank:
          type: boolean
          description: "`page`: the first screen had nothing on it."
    DeploymentStep:
      type: object
      required:
        - key
        - state
        - started_at
        - finished_at
        - seconds
      properties:
        key:
          $ref: "#/components/schemas/DeploymentStepKey"
        state:
          type: string
          enum:
            - pending
            - running
            - done
            - failed
            - skipped
        started_at:
          type:
            - string
            - "null"
          format: date-time
        finished_at:
          type:
            - string
            - "null"
          format: date-time
        seconds:
          type:
            - integer
            - "null"
          description: Null until the step ends.
    DeploymentFailure:
      type: object
      description: Why the build stopped, from the build's own output.
      required:
        - title
        - message
        - step
        - line
      properties:
        title:
          type: string
          examples:
            - Type error in lib/cart.ts, line 42
        message:
          type: string
          examples:
            - Property 'total' does not exist on type 'Cart'.
        step:
          $ref: "#/components/schemas/DeploymentStepKey"
        line:
          type:
            - integer
            - "null"
          description: The log line `n` that "Jump to error" scrolls to.
    ProjectDomain:
      type: object
      required:
        - name
        - state
        - custom
      properties:
        name:
          type: string
          examples:
            - storefront.theorbits.app
        state:
          type: string
          enum:
            - valid
            - pending
            - misconfigured
        custom:
          type: boolean
    DeploymentDetail:
      allOf:
        - $ref: "#/components/schemas/Deployment"
        - type: object
          required:
            - framework
            - region
            - domains
            - steps
            - failure
            - log_lines
            - open_graph
          properties:
            framework:
              type:
                - string
                - "null"
              description: As the builder detected it.
              examples:
                - Next.js 16
            region:
              type: string
              examples:
                - abj-1
            domains:
              type: array
              description: Production's domains, when this is what they serve; otherwise empty. The team's domains serving the project's production (working ones first), then its free address.
              items:
                $ref: "#/components/schemas/ProjectDomain"
            steps:
              type: array
              items:
                $ref: "#/components/schemas/DeploymentStep"
            failure:
              oneOf:
                - type: "null"
                - $ref: "#/components/schemas/DeploymentFailure"
            log_lines:
              type: integer
              description: How many log lines the build has.
            open_graph:
              description: The home page's link-preview tags. Null until the builder has read them (a second or two after the deployment is ready), for a worker, and when the page could not be read (it answered an error, or redirected to another host).
              oneOf:
                - type: "null"
                - $ref: "#/components/schemas/DeploymentOpenGraph"
    DeploymentOpenGraph:
      type: object
      description: "A deployment's home page as a link bot reads it: one plain GET of `/` with no JavaScript, following redirects on the same host, reading the first megabyte. Tags set by JavaScript after the page loads are not here, as link bots don't see them either. URLs are absolute (resolved against the deployment's `url`) and http(s) only; a value that isn't one is null. A page that isn't HTML (an API) has every field null."
      required:
        - title
        - description
        - image
        - image_was_relative
        - url
        - site_name
        - twitter_card
        - twitter_title
        - twitter_description
        - twitter_image
        - favicon
        - fetched_at
      properties:
        title:
          type:
            - string
            - "null"
          description: "`og:title`, else `<title>`."
          examples:
            - Fifteen Seconds
        description:
          type:
            - string
            - "null"
          description: '`og:description`, else `<meta name="description">`.'
        image:
          type:
            - string
            - "null"
          format: uri
          description: "`og:image` (or `og:image:url`, `og:image:secure_url`). The dashboard loads it from its host; the API does not fetch it."
          examples:
            - https://fifteen-seconds-85234cf.theorbits.app/og.png
        image_was_relative:
          type: boolean
          description: The page wrote `og:image` as a relative URL. Some link bots don't resolve it, so the image may not show.
        url:
          type:
            - string
            - "null"
          format: uri
          description: '`og:url`, else `<link rel="canonical">`.'
        site_name:
          type:
            - string
            - "null"
          description: "`og:site_name`."
        twitter_card:
          type:
            - string
            - "null"
          description: "`twitter:card` as written (`summary`, `summary_large_image`, …). Null means X shows a small summary card."
          examples:
            - summary_large_image
        twitter_title:
          type:
            - string
            - "null"
          description: "`twitter:title`; X uses it over `title`."
        twitter_description:
          type:
            - string
            - "null"
          description: "`twitter:description`; X uses it over `description`."
        twitter_image:
          type:
            - string
            - "null"
          format: uri
          description: "`twitter:image`; X uses it over `image`."
        favicon:
          type:
            - string
            - "null"
          format: uri
          description: '`<link rel="icon">`. Null when the page declares none; most sites still serve `/favicon.ico`.'
        fetched_at:
          type: string
          format: date-time
          description: When the builder read the page.
    DeploymentLogLine:
      type: object
      required:
        - n
        - at
        - step
        - tone
        - text
      properties:
        n:
          type: integer
          description: Line number, from 1.
        at:
          type: string
          format: date-time
        step:
          $ref: "#/components/schemas/DeploymentStepKey"
        tone:
          type: string
          enum:
            - plain
            - good
            - bad
          description: Green for success lines, red for errors.
        text:
          type: string
    DeploymentLogPage:
      type: object
      required:
        - items
        - next_after
        - done
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/DeploymentLogLine"
        next_after:
          type: integer
          description: Send as `after` to get the next lines.
        done:
          type: boolean
          description: The build has finished and every line has been returned.
    RuntimeLog:
      type: object
      required:
        - id
        - at
        - source
        - level
        - status
        - method
        - path
        - duration_ms
        - message
        - stream
        - request_id
        - host
        - region
        - deployment
        - headers
      properties:
        id:
          type: string
          examples:
            - log_019a16dc-3a1f-7c2e-9b1d-2f4e8a6b0c11
        at:
          type: string
          format: date-time
          description: With milliseconds.
        source:
          type: string
          enum:
            - requests
            - functions
        level:
          type: string
          enum:
            - info
            - warning
            - error
        status:
          type:
            - integer
            - "null"
          description: A request's HTTP status.
        method:
          type:
            - string
            - "null"
          examples:
            - GET
        path:
          type:
            - string
            - "null"
          description: Without the query string.
          examples:
            - /checkout
        duration_ms:
          type:
            - integer
            - "null"
          description: From the edge receiving the request to the last byte of the answer.
        message:
          type:
            - string
            - "null"
          description: An output line, without colour codes; at most 8192 characters.
        stream:
          type:
            - string
            - "null"
          enum:
            - stdout
            - stderr
            - null
        request_id:
          type:
            - string
            - "null"
          description: The edge's ID for a request, also sent to the app as `X-Request-Id`.
        host:
          type:
            - string
            - "null"
          examples:
            - shop.theorbits.app
        region:
          type: string
          examples:
            - abj-1
        deployment:
          type:
            - object
            - "null"
          required:
            - id
            - sha
          properties:
            id:
              type: string
            sha:
              type:
                - string
                - "null"
        headers:
          type: array
          description: "Some request headers, as `[name, value]` pairs: user-agent, accept, content-type, referer, and x-forwarded-for masked. Cookies and authorization are never stored."
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2
    ObservabilityTotals:
      type: object
      required:
        - requests
        - errors
        - p50_ms
        - p75_ms
        - p99_ms
      properties:
        requests:
          type: integer
        errors:
          type: integer
          description: Responses with a 5xx status.
        p50_ms:
          type: integer
        p75_ms:
          type: integer
        p99_ms:
          type: integer
    InsightsRange:
      type: string
      enum:
        - 24h
        - 7d
        - 30d
      default: 7d
    InsightsSwitch:
      type: object
      required:
        - enabled
      properties:
        enabled:
          type: boolean
    InsightsVisits:
      type: object
      required:
        - visitors
        - pageviews
        - bounce_rate
        - views_per_visit
      properties:
        visitors:
          type: integer
        pageviews:
          type: integer
        bounce_rate:
          type:
            - number
            - "null"
          description: Share of visitors with one page view, 0 to 1; null without visitors.
        views_per_visit:
          type:
            - number
            - "null"
    Analytics:
      oneOf:
        - type: object
          required:
            - enabled
          properties:
            enabled:
              type: boolean
              const: false
            locked:
              type: boolean
              const: true
              description: Present when the team's plan doesn't include this page (Free). Show the upgrade state; nothing is read, and what was collected is kept for when the team is on Pro.
        - type: object
          required:
            - enabled
            - range
            - buckets
            - previous_buckets
            - totals
            - previous
            - pages
            - referrers
            - countries
            - devices
            - events
          properties:
            enabled:
              type: boolean
              const: true
            range:
              $ref: "#/components/schemas/InsightsRange"
            buckets:
              type: array
              items:
                type: object
                required:
                  - start
                  - visitors
                  - pageviews
                properties:
                  start:
                    type: string
                    format: date-time
                  visitors:
                    type: integer
                  pageviews:
                    type: integer
            previous_buckets:
              type: array
              items:
                type: object
                required:
                  - start
                  - visitors
                  - pageviews
                properties:
                  start:
                    type: string
                    format: date-time
                  visitors:
                    type: integer
                  pageviews:
                    type: integer
            totals:
              $ref: "#/components/schemas/InsightsVisits"
            previous:
              $ref: "#/components/schemas/InsightsVisits"
            pages:
              type: array
              items:
                type: object
                required:
                  - route
                  - visitors
                  - pageviews
                properties:
                  route:
                    type: string
                    examples:
                      - /products/[id]
                  visitors:
                    type: integer
                  pageviews:
                    type: integer
            referrers:
              type: array
              items:
                type: object
                required:
                  - host
                  - visitors
                properties:
                  host:
                    type:
                      - string
                      - "null"
                    examples:
                      - instagram.com
                  visitors:
                    type: integer
            countries:
              type: array
              items:
                type: object
                required:
                  - country
                  - visitors
                properties:
                  country:
                    type: string
                    description: ISO 3166-1 alpha-2.
                    examples:
                      - NG
                  visitors:
                    type: integer
            devices:
              type: array
              items:
                type: object
                required:
                  - device
                  - visitors
                properties:
                  device:
                    type: string
                    enum:
                      - desktop
                      - mobile
                      - tablet
                  visitors:
                    type: integer
            events:
              type: array
              items:
                type: object
                required:
                  - name
                  - visitors
                  - count
                properties:
                  name:
                    type: string
                    examples:
                      - Signed up
                  visitors:
                    type: integer
                  count:
                    type: integer
    AnalyticsEvent:
      oneOf:
        - type: object
          required:
            - enabled
          properties:
            enabled:
              type: boolean
              const: false
        - type: object
          required:
            - enabled
            - range
            - name
            - count
            - visitors
            - properties
          properties:
            enabled:
              type: boolean
              const: true
            range:
              $ref: "#/components/schemas/InsightsRange"
            name:
              type: string
            count:
              type: integer
            visitors:
              type: integer
            properties:
              type: array
              items:
                type: object
                required:
                  - key
                  - count
                  - values
                properties:
                  key:
                    type: string
                    examples:
                      - plan
                  count:
                    type: integer
                  values:
                    type: array
                    items:
                      type: object
                      required:
                        - value
                        - count
                      properties:
                        value:
                          type: string
                          examples:
                            - pro
                        count:
                          type: integer
    SpeedInsights:
      oneOf:
        - type: object
          required:
            - enabled
          properties:
            enabled:
              type: boolean
              const: false
            locked:
              type: boolean
              const: true
              description: Present when the team's plan doesn't include this page (Free). Show the upgrade state; nothing is read, and what was collected is kept for when the team is on Pro.
        - type: object
          required:
            - enabled
            - range
            - device
            - visits
            - score
            - vitals
            - lcp
            - routes
            - targets
            - connections
          properties:
            enabled:
              type: boolean
              const: true
            range:
              $ref: "#/components/schemas/InsightsRange"
            device:
              type: string
              enum:
                - mobile
                - desktop
            visits:
              type: integer
              description: Page views on the device.
            score:
              type:
                - integer
                - "null"
              minimum: 0
              maximum: 100
            vitals:
              type: array
              description: The vitals measured, in the order LCP, INP, CLS, FCP, TTFB.
              items:
                type: object
                required:
                  - name
                  - p75
                  - samples
                properties:
                  name:
                    type: string
                    enum:
                      - LCP
                      - INP
                      - CLS
                      - FCP
                      - TTFB
                  p75:
                    type: number
                  samples:
                    type: integer
            lcp:
              type: array
              items:
                type: object
                required:
                  - start
                  - p75
                properties:
                  start:
                    type: string
                    format: date-time
                  p75:
                    type:
                      - number
                      - "null"
            routes:
              type: array
              items:
                type: object
                required:
                  - route
                  - visits
                  - lcp
                  - inp
                  - cls
                properties:
                  route:
                    type: string
                  visits:
                    type: integer
                  lcp:
                    type:
                      - number
                      - "null"
                  inp:
                    type:
                      - number
                      - "null"
                  cls:
                    type:
                      - number
                      - "null"
            targets:
              type: array
              items:
                type: object
                required:
                  - name
                  - target
                  - samples
                  - p75
                properties:
                  name:
                    type: string
                    enum:
                      - LCP
                      - INP
                      - CLS
                  target:
                    type: string
                    examples:
                      - main>img.hero
                  samples:
                    type: integer
                  p75:
                    type: number
            connections:
              type: array
              items:
                type: object
                required:
                  - connection
                  - samples
                properties:
                  connection:
                    type: string
                    enum:
                      - 4g
                      - 3g
                      - 2g
                      - slow-2g
                  samples:
                    type: integer
    Observability:
      type: object
      required:
        - as_of
        - range
        - bucket_seconds
        - totals
        - previous
        - buckets
        - routes
        - statuses
        - regions
        - all_routes
      properties:
        as_of:
          type: string
          format: date-time
        range:
          type: string
          enum:
            - 1h
            - 6h
            - 24h
            - 7d
        bucket_seconds:
          type: integer
          examples:
            - 3600
        totals:
          $ref: "#/components/schemas/ObservabilityTotals"
        previous:
          allOf:
            - $ref: "#/components/schemas/ObservabilityTotals"
          description: The same for the period before, for "on the hour before".
        buckets:
          type: array
          description: Oldest first; zeros where nothing came in. The last is still filling.
          items:
            type: object
            required:
              - start
              - requests
              - errors
              - p75_ms
              - p99_ms
            properties:
              start:
                type: string
                format: date-time
              requests:
                type: integer
              errors:
                type: integer
              p75_ms:
                type: integer
              p99_ms:
                type: integer
        routes:
          type: array
          description: The 20 busiest routes, busiest first.
          items:
            type: object
            required:
              - route
              - requests
              - errors
              - p75_ms
              - p99_ms
            properties:
              route:
                type: string
                examples:
                  - /products/[id]
              requests:
                type: integer
              errors:
                type: integer
              p75_ms:
                type: integer
              p99_ms:
                type: integer
        statuses:
          type: object
          description: Requests by status class, under every filter but `status`.
          required:
            - 2xx
            - 3xx
            - 4xx
            - 5xx
          properties:
            2xx:
              type: integer
            3xx:
              type: integer
            4xx:
              type: integer
            5xx:
              type: integer
        regions:
          type: array
          items:
            type: object
            required:
              - region
              - requests
            properties:
              region:
                type: string
                examples:
                  - abj-1
              requests:
                type: integer
        all_routes:
          type: array
          description: The 100 busiest routes in the range, for the Route filter.
          items:
            type: string
    AlertMetric:
      type: string
      enum:
        - error-rate
        - p75
        - p99
        - requests
      description: "`error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute."
    AlertChannel:
      type: string
      enum:
        - webhook
        - email
      description: "`webhook`: the team's webhook. `email`: the team's owners, admins and members."
    WorkflowStep:
      type: object
      required:
        - name
        - kind
        - state
        - seconds
        - detail
        - error
        - attempts
        - retried_by
        - wake_at
        - event
        - output
      properties:
        name:
          type: string
          examples:
            - update-inventory
        kind:
          type: string
          enum:
            - step
            - sleep
            - wait
        state:
          type: string
          enum:
            - running
            - succeeded
            - failed
            - waiting
            - skipped
            - canceled
        seconds:
          type:
            - integer
            - "null"
          description: Time spent running over every attempt; null for one not reached.
        detail:
          type: string
          examples:
            - Gave up after 3 attempts
        error:
          type:
            - array
            - "null"
          items:
            type: string
          description: "The last attempt's error: message, then where."
        attempts:
          type: integer
        retried_by:
          oneOf:
            - $ref: "#/components/schemas/FlagPerson"
            - type: "null"
        wake_at:
          type:
            - string
            - "null"
          format: date-time
          description: A sleep's end, or a wait's timeout.
        event:
          type:
            - string
            - "null"
          description: What a wait waits for.
        output:
          description: The step's result; a wait's is the event's data.
    WorkflowRun:
      type: object
      required:
        - id
        - workflow
        - state
        - trigger
        - trigger_text
        - started_by
        - started_at
        - finished_at
        - seconds
        - deployment
        - input
        - output
        - error
        - attempts
        - next_at
        - steps
      properties:
        id:
          type: string
        workflow:
          type: string
          examples:
            - sync-stock
        state:
          type: string
          enum:
            - running
            - succeeded
            - failed
            - canceled
        trigger:
          type: string
          enum:
            - schedule
            - event
            - manual
        trigger_text:
          type: string
          examples:
            - Every 15 minutes
        started_by:
          oneOf:
            - $ref: "#/components/schemas/FlagPerson"
            - type: "null"
          description: Who pressed Run now; null for a schedule or an event.
        started_at:
          type: string
          format: date-time
        finished_at:
          type:
            - string
            - "null"
          format: date-time
        seconds:
          type: integer
          description: From start to finish, or so far.
        deployment:
          type: object
          required:
            - id
            - sha
          properties:
            id:
              type: string
            sha:
              type:
                - string
                - "null"
        input:
          description: The JSON it started with.
        output:
          description: What the workflow returned.
        error:
          type:
            - array
            - "null"
          items:
            type: string
        attempts:
          type: string
          examples:
            - 3 on step 3
        next_at:
          type:
            - string
            - "null"
          format: date-time
          description: When the app is called for it next.
        steps:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowStep"
    WorkflowsPage:
      type: object
      required:
        - workflows
        - runs
      properties:
        workflows:
          type: array
          items:
            type: object
            required:
              - name
              - description
              - schedule
              - event
              - retries
              - trigger_text
              - last_run
              - success_rate
            properties:
              name:
                type: string
              description:
                type: string
              schedule:
                type:
                  - string
                  - "null"
                description: Five-field cron, in UTC.
              event:
                type:
                  - string
                  - "null"
              retries:
                type: integer
                description: Attempts after the first, for each step.
              trigger_text:
                type: string
              last_run:
                oneOf:
                  - type: "null"
                  - type: object
                    required:
                      - id
                      - state
                      - at
                    properties:
                      id:
                        type: string
                      state:
                        type: string
                        enum:
                          - running
                          - succeeded
                          - failed
                          - canceled
                      at:
                        type: string
                        format: date-time
              success_rate:
                type:
                  - number
                  - "null"
                minimum: 0
                maximum: 1
        runs:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowRun"
    SandboxRuntime:
      type: string
      enum:
        - node22
        - python312
        - go123
    SandboxSize:
      type: string
      enum:
        - small
        - large
      description: small = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
    SandboxState:
      type: string
      enum:
        - starting
        - running
        - stopped
      description: "`stopped` is suspended: the disk is kept and `start` resumes it."
    SandboxTerminalTicket:
      type: object
      required:
        - ticket
      properties:
        ticket:
          type: string
          description: "Admits the caller to this sandbox's terminal for 60 seconds: the `ticket` query parameter of `GET .../sandboxes/{sandbox}/terminal`."
          examples:
            - sbt_eyJzIjoic2J4XzEifQ.c2lnbmF0dXJl
    SandboxTerminalLine:
      type: object
      required:
        - kind
        - text
      properties:
        kind:
          type: string
          enum:
            - cmd
            - out
            - ok
            - err
        text:
          type: string
    SandboxUsage:
      type: object
      required:
        - cpu
        - memory_gb
        - disk_gb
        - idle_minutes
      properties:
        cpu:
          type: integer
          description: Percent of the size's vCPU in use.
        memory_gb:
          type: number
        disk_gb:
          type: number
        idle_minutes:
          type: integer
          description: Minutes since the last activity; drives the idle suspend.
    Sandbox:
      type: object
      required:
        - name
        - runtime
        - size
        - source
        - state
        - started_at
        - stopped_at
        - started_by
        - stop_after
        - url
        - terminal
        - usage
      properties:
        name:
          type: string
          examples:
            - seed-test-data
        runtime:
          $ref: "#/components/schemas/SandboxRuntime"
        size:
          $ref: "#/components/schemas/SandboxSize"
        source:
          type:
            - string
            - "null"
          description: What was cloned (e.g. "storefront · main"); null for an empty machine.
        state:
          $ref: "#/components/schemas/SandboxState"
        started_at:
          type: string
          format: date-time
        stopped_at:
          type:
            - string
            - "null"
          format: date-time
        started_by:
          $ref: "#/components/schemas/FlagPerson"
        stop_after:
          type: integer
          enum:
            - 10
            - 30
            - 60
            - 120
          description: Idle minutes before it suspends itself.
        url:
          type: string
          format: uri
          description: The sandbox's preview URL (port 3000), reachable by team members only.
        terminal:
          type: array
          items:
            $ref: "#/components/schemas/SandboxTerminalLine"
          description: The boot and run output so far; live output streams over the terminal WebSocket.
        usage:
          $ref: "#/components/schemas/SandboxUsage"
    SandboxPort:
      type: object
      required:
        - port
        - url
        - access
      properties:
        port:
          type: integer
          examples:
            - 3000
        url:
          type: string
          format: uri
        access:
          type: string
          enum:
            - team
            - public
          description: v1 exposes ports to team members only.
    SandboxDetail:
      allOf:
        - $ref: "#/components/schemas/Sandbox"
        - type: object
          required:
            - ports
          properties:
            ports:
              type: array
              items:
                $ref: "#/components/schemas/SandboxPort"
    SandboxPage:
      type: object
      required:
        - items
        - running
        - limit
        - as_of
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Sandbox"
        running:
          type: integer
          description: Live sandboxes (starting or running).
        limit:
          type: integer
          description: The most a team may run at once.
        as_of:
          type: string
          format: date-time
          description: The server's clock, for the page's relative times.
    SandboxCreate:
      type: object
      required:
        - name
        - runtime
        - size
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 40
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          examples:
            - seed-test-data
        runtime:
          $ref: "#/components/schemas/SandboxRuntime"
        size:
          $ref: "#/components/schemas/SandboxSize"
        clone:
          type: boolean
          default: false
          description: Check out the project's repository at main.
        env:
          type: boolean
          default: false
          description: Copy the Preview environment variables in.
        stop_after:
          type: integer
          enum:
            - 10
            - 30
            - 60
            - 120
          default: 30
          description: Idle minutes before it suspends itself.
    FlagType:
      type: string
      enum:
        - boolean
        - string
        - number
    FlagEnvironmentName:
      type: string
      enum:
        - production
        - preview
        - development
    FlagRuleOperator:
      type: string
      enum:
        - equals
        - not_equals
        - one_of
        - ends_with
        - starts_with
        - contains
    FlagEnvironmentInput:
      type: object
      properties:
        on:
          type: boolean
          description: A boolean flag's switch.
        value:
          type:
            - string
            - number
          description: A string or number flag's value.
    FlagPerson:
      type: object
      required:
        - id
        - name
        - email
        - avatar_url
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        avatar_url:
          type:
            - string
            - "null"
    FlagRule:
      type: object
      required:
        - id
        - attribute
        - operator
        - values
        - serve
        - label
      properties:
        id:
          type: string
        attribute:
          type: string
          examples:
            - email
        operator:
          $ref: "#/components/schemas/FlagRuleOperator"
        values:
          type: array
          items:
            type: string
        serve:
          type:
            - boolean
            - string
            - number
        label:
          type: string
          examples:
            - Email ends with @kudi.ng
    FlagEnvironment:
      type: object
      required:
        - on
        - rollout
        - value
        - rules
      properties:
        on:
          type: boolean
          description: A boolean flag's switch; always true for the others.
        rollout:
          type: integer
          minimum: 1
          maximum: 100
        value:
          type:
            - string
            - number
            - "null"
          description: A string or number flag's value; null for a boolean.
        rules:
          type: array
          items:
            $ref: "#/components/schemas/FlagRule"
    Flag:
      type: object
      required:
        - key
        - description
        - type
        - environments
        - created_by
        - updated_by
        - created_at
        - updated_at
      properties:
        key:
          type: string
          examples:
            - new-checkout
        description:
          type: string
        type:
          $ref: "#/components/schemas/FlagType"
        environments:
          type: object
          required:
            - production
            - preview
            - development
          properties:
            production:
              $ref: "#/components/schemas/FlagEnvironment"
            preview:
              $ref: "#/components/schemas/FlagEnvironment"
            development:
              $ref: "#/components/schemas/FlagEnvironment"
        created_by:
          $ref: "#/components/schemas/FlagPerson"
        updated_by:
          $ref: "#/components/schemas/FlagPerson"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    FlagList:
      type: object
      required:
        - items
        - total
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Flag"
        total:
          type: integer
          description: Every flag in the project, whatever the filters.
    FlagSeen:
      type: object
      required:
        - people
        - checks
      properties:
        people:
          type: integer
        checks:
          type: integer
    FlagDetail:
      allOf:
        - $ref: "#/components/schemas/Flag"
        - type: object
          required:
            - history
            - seen
          properties:
            history:
              type: array
              items:
                type: object
                required:
                  - id
                  - by
                  - text
                  - at
                properties:
                  id:
                    type: string
                  by:
                    $ref: "#/components/schemas/FlagPerson"
                  text:
                    type: string
                    examples:
                      - Set Preview rollout to 10%
                  at:
                    type: string
                    format: date-time
            seen:
              type: object
              required:
                - production
                - preview
                - development
              properties:
                production:
                  $ref: "#/components/schemas/FlagSeen"
                preview:
                  $ref: "#/components/schemas/FlagSeen"
                development:
                  $ref: "#/components/schemas/FlagSeen"
    Alert:
      type: object
      required:
        - id
        - name
        - metric
        - direction
        - threshold
        - window_minutes
        - routes
        - channels
        - on
        - state
        - since
        - last_value
        - checked_at
        - created_at
        - updated_at
      properties:
        id:
          type: string
          examples:
            - alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11
        name:
          type: string
          maxLength: 60
        metric:
          $ref: "#/components/schemas/AlertMetric"
        direction:
          type: string
          enum:
            - above
            - below
          description: "`below` only for `requests`."
        threshold:
          type: number
        window_minutes:
          type: integer
          enum:
            - 1
            - 5
            - 10
            - 30
        routes:
          type: array
          items:
            type: string
          description: Routes as Observability names them; a trailing `*` matches a prefix. Empty for all routes.
        channels:
          type: array
          items:
            $ref: "#/components/schemas/AlertChannel"
        on:
          type: boolean
        state:
          type: string
          enum:
            - ok
            - firing
        since:
          type: string
          format: date-time
          description: When it last fired or resolved, or was created or changed.
        last_value:
          type:
            - number
            - "null"
          description: The value at the last check; null before one, or with too little traffic.
        checked_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AlertPage:
      type: object
      required:
        - items
        - webhook_configured
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Alert"
        webhook_configured:
          type: boolean
          description: Whether the team has a webhook, so `webhook` can be chosen.
    AlertCreate:
      type: object
      required:
        - name
        - metric
        - threshold
        - window_minutes
        - channels
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 60
        metric:
          $ref: "#/components/schemas/AlertMetric"
        direction:
          type: string
          enum:
            - above
            - below
          default: above
        threshold:
          type: number
          exclusiveMinimum: 0
          maximum: 1000000
        window_minutes:
          type: integer
          enum:
            - 1
            - 5
            - 10
            - 30
        routes:
          type: array
          maxItems: 10
          items:
            type: string
            maxLength: 200
          default: []
        channels:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/AlertChannel"
        on:
          type: boolean
          default: true
    AlertUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 60
        metric:
          $ref: "#/components/schemas/AlertMetric"
        direction:
          type: string
          enum:
            - above
            - below
        threshold:
          type: number
          exclusiveMinimum: 0
          maximum: 1000000
        window_minutes:
          type: integer
          enum:
            - 1
            - 5
            - 10
            - 30
        routes:
          type: array
          maxItems: 10
          items:
            type: string
            maxLength: 200
        channels:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/AlertChannel"
        on:
          type: boolean
    AlertPreviewRequest:
      type: object
      required:
        - metric
        - window_minutes
      properties:
        metric:
          $ref: "#/components/schemas/AlertMetric"
        direction:
          type: string
          enum:
            - above
            - below
        window_minutes:
          type: integer
          enum:
            - 1
            - 5
            - 10
            - 30
        routes:
          type: array
          maxItems: 10
          items:
            type: string
            maxLength: 200
    AlertPreview:
      type: object
      required:
        - median_requests
        - minimum_requests
        - value
      properties:
        median_requests:
          type: number
          description: Median requests per window over the last 24 hours.
        minimum_requests:
          type: integer
          description: "What a window needs before the rule acts: 20, or 0 for `requests`."
        value:
          type:
            - number
            - "null"
          description: The value over the last window, or null with too little traffic.
    AlertDelivery:
      type: object
      required:
        - channel
        - status
        - error
        - at
      properties:
        channel:
          $ref: "#/components/schemas/AlertChannel"
        status:
          type: string
          enum:
            - pending
            - delivered
            - failed
        error:
          type:
            - string
            - "null"
          description: Why the last try failed, e.g. "The webhook answered 500".
        at:
          type:
            - string
            - "null"
          format: date-time
          description: When it was delivered or given up on.
    AlertEvent:
      type: object
      required:
        - id
        - kind
        - reason
        - value
        - at
        - deliveries
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
            - fired
            - resolved
        reason:
          type:
            - string
            - "null"
          enum:
            - recovered
            - quiet
            - changed
            - off
            - deleted
            - null
          description: "Why it resolved: its value came back, its traffic went too quiet to measure (`value` is null), or it was changed, switched off or deleted while firing."
        value:
          type:
            - number
            - "null"
        at:
          type: string
          format: date-time
        deliveries:
          type: array
          items:
            $ref: "#/components/schemas/AlertDelivery"
    AlertEventPage:
      type: object
      required:
        - items
        - next_cursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/AlertEvent"
        next_cursor:
          type:
            - string
            - "null"
    AlertWebhook:
      type: object
      required:
        - url
        - secret_last4
        - updated_at
      properties:
        url:
          type: string
          format: uri
        secret_last4:
          type: string
        updated_at:
          type: string
          format: date-time
    AlertChannels:
      type: object
      required:
        - webhook
      properties:
        webhook:
          oneOf:
            - $ref: "#/components/schemas/AlertWebhook"
            - type: "null"
    AlertWebhookSet:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          maxLength: 2000
          description: An https URL without a user name or password.
        rotate_secret:
          type: boolean
          default: false
    AlertWebhookSaved:
      type: object
      required:
        - webhook
        - secret
      properties:
        webhook:
          $ref: "#/components/schemas/AlertWebhook"
        secret:
          type:
            - string
            - "null"
          description: The new secret (64 hex characters), shown this once; null when it was kept.
    AlertWebhookTest:
      type: object
      required:
        - delivered
        - status
        - error
      properties:
        delivered:
          type: boolean
        status:
          type:
            - integer
            - "null"
        error:
          type:
            - string
            - "null"
    RuntimeLogPage:
      type: object
      required:
        - as_of
        - items
        - total
        - total_capped
        - next_cursor
      properties:
        as_of:
          type: string
          format: date-time
          description: The end of the range.
        items:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeLog"
        total:
          type: integer
          maximum: 10000
          description: Entries in the range that match the filters, counted up to 10,000.
        total_capped:
          type: boolean
          description: 'More than 10,000 entries match, so `total` is 10,000: show it as "10,000+".'
        next_cursor:
          type:
            - string
            - "null"
    ProjectDeploymentPage:
      type: object
      required:
        - items
        - total
        - all
        - branches
        - current
        - auto_deploy_paused
        - domains
        - building
        - next_cursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Deployment"
        total:
          type: integer
          description: Deployments that match the filters.
        all:
          type: integer
          description: Every deployment of the project, filters aside.
        branches:
          type: array
          items:
            type: string
          description: Branches that have deployments, most recent first.
        current:
          description: What production serves; what the inspector shows when nothing is picked.
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/Deployment"
        auto_deploy_paused:
          type: boolean
          description: True after a rollback, until a promote or `POST .../production` lifts it.
        domains:
          type: array
          items:
            $ref: "#/components/schemas/ProjectDomain"
          description: "What production answers on, once it has a deployment: the team's domains serving the project's production (working ones first, not a branch's or a redirect), then its free address."
        building:
          type: boolean
          description: Something is queued or building.
        next_cursor:
          type:
            - string
            - "null"
    TeamDeploymentPage:
      type: object
      required:
        - items
        - total
        - this_week
        - projects
        - authors
        - next_cursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Deployment"
        total:
          type: integer
        this_week:
          type: integer
          description: Deployments created since Monday (UTC).
        projects:
          type: array
          items:
            $ref: "#/components/schemas/DeploymentProject"
          description: Projects that have deployments, for the Project filter.
        authors:
          type: array
          description: Commit authors, for the Author filter.
          items:
            type: object
            required:
              - name
            properties:
              name:
                type: string
        next_cursor:
          type:
            - string
            - "null"
    ProductionChange:
      type: object
      required:
        - deployment
        - auto_deploy_paused
      properties:
        deployment:
          $ref: "#/components/schemas/Deployment"
        auto_deploy_paused:
          type: boolean
    EnvVarInput:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          examples:
            - STRIPE_SECRET_KEY
        value:
          type: string
          maxLength: 32768
          writeOnly: true
          description: May be empty; at most 32 KiB (32,768 bytes) once encoded. Never returned except as described on `EnvVar.value`.
        environments:
          type: array
          minItems: 1
          uniqueItems: true
          default:
            - production
            - preview
          description: Used by Production and Preview unless the user picks otherwise.
          items:
            $ref: "#/components/schemas/EnvironmentName"
        sensitive:
          type: boolean
          default: true
          description: "Write-only: nobody can read the value back, only replace it."
    EnvVarCreate:
      type: object
      required:
        - variables
      properties:
        variables:
          type: array
          minItems: 1
          maxItems: 500
          items:
            $ref: "#/components/schemas/EnvVarInput"
        on_conflict:
          type: string
          enum:
            - fail
            - replace
          default: fail
          description: "`fail` (Add variable): a key that already exists is 409 and nothing is saved. `replace` (Import .env): existing keys get the new value and environments."
    EnvVarUpdate:
      type: object
      minProperties: 1
      properties:
        value:
          type: string
          maxLength: 32768
          writeOnly: true
        environments:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/EnvironmentName"
    EnvVar:
      type: object
      required:
        - id
        - key
        - value
        - sensitive
        - environments
        - pending_redeploy
        - created_at
        - updated_at
        - updated_by
      properties:
        id:
          type: string
          examples:
            - var_01J9ZK3Q
        key:
          type: string
        value:
          type:
            - string
            - "null"
          description: Only for a non-sensitive variable whose key is meant for the browser (`NEXT_PUBLIC_`, `NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`, `REACT_APP_`, `EXPO_PUBLIC_` prefix, or a `_PUBLIC_KEY` suffix). Otherwise null; use `POST .../env/{key}/reveal`.
        sensitive:
          type: boolean
        environments:
          type: array
          items:
            $ref: "#/components/schemas/EnvironmentName"
        pending_redeploy:
          type: boolean
          description: Changed since the latest deployment; shows the "New" tag.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
    EnvVarPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - items
            - total
            - last_changed
            - redeploy
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/EnvVar"
            total:
              type: integer
              description: Variables matching the filters.
            last_changed:
              oneOf:
                - type: "null"
                - type: object
                  required:
                    - at
                    - by
                  properties:
                    at:
                      type: string
                      format: date-time
                    by:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: string
                        name:
                          type: string
            redeploy:
              type: object
              required:
                - required
                - changed
              properties:
                required:
                  type: boolean
                changed:
                  type: integer
    EnvVarBatchResult:
      type: object
      required:
        - items
        - created
        - replaced
        - redeploy_required
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EnvVar"
        created:
          type: integer
        replaced:
          type: integer
        redeploy_required:
          type: boolean
    EnvVarChange:
      type: object
      required:
        - item
        - redeploy_required
      properties:
        item:
          $ref: "#/components/schemas/EnvVar"
        redeploy_required:
          type: boolean
    EnvVarDeleted:
      type: object
      required:
        - key
        - restorable_until
        - redeploy_required
      properties:
        key:
          type: string
        restorable_until:
          type: string
          format: date-time
        redeploy_required:
          type: boolean
    EnvVarValue:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
        value:
          type: string
    EnvVarPull:
      type: object
      required:
        - environment
        - variables
        - skipped_sensitive
      properties:
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        variables:
          type: object
          additionalProperties:
            type: string
        skipped_sensitive:
          type: array
          items:
            type: string
          description: Keys left out because nobody can read them back.
    Redirect:
      type: object
      required:
        - to
        - status
      properties:
        to:
          type: string
          description: The hostname it sends visitors to, keeping the path.
        status:
          type: integer
          enum:
            - 301
            - 308
    DnsRecordType:
      type: string
      enum:
        - A
        - AAAA
        - CNAME
        - MX
        - TXT
        - CAA
    DnsRecordInput:
      type: object
      required:
        - type
        - name
        - value
        - ttl
      properties:
        type:
          $ref: "#/components/schemas/DnsRecordType"
        name:
          type: string
          maxLength: 253
          examples:
            - "@"
            - www
            - _dmarc
          description: Relative to the zone; `@` for the apex.
        value:
          type: string
          maxLength: 2048
          examples:
            - 10 mx.zoho.com
            - v=spf1 include:zoho.com ~all
          description: An MX record's is its priority and server; a TXT record's is its text without quotes.
        ttl:
          type: integer
          enum:
            - 0
            - 60
            - 300
            - 3600
            - 86400
          description: Seconds; `0` is Auto (5 minutes).
    DnsRecord:
      allOf:
        - $ref: "#/components/schemas/DnsRecordInput"
        - type: object
          required:
            - id
            - managed
            - used_by
            - updated_at
          properties:
            id:
              type: string
              pattern: ^rec_
            managed:
              type: boolean
              description: Orbits keeps it for a project; it can't be changed here.
            used_by:
              oneOf:
                - type: "null"
                - type: object
                  required:
                    - kind
                  properties:
                    kind:
                      type: string
                      enum:
                        - project
                        - email
                    project:
                      type: object
                      required:
                        - id
                        - slug
                        - name
                      properties:
                        id:
                          type: string
                        slug:
                          type: string
                        name:
                          type: string
            updated_at:
              type: string
              format: date-time
    DnsRecordList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/DnsRecord"
    DomainState:
      type: string
      enum:
        - pending
        - valid
        - misconfigured
      description: "`pending`: its record isn't there yet. `valid`: DNS points at Orbits. `misconfigured`: a record is there but points elsewhere (`seen` says where)."
    DnsMode:
      type: string
      enum:
        - external
        - orbits
      description: "`external`: the team keeps its DNS provider and adds one record. `orbits`: the team hands the domain's DNS to Orbits (an apex's nameservers at its registrar, or NS records for a subdomain at its parent's DNS)."
    Domain:
      type: object
      required:
        - id
        - name
        - apex
        - host
        - dns
        - state
        - project
        - branch
        - redirect
        - required_record
        - seen
        - nameservers
        - email
        - certificate
        - checked_at
        - created_at
      properties:
        id:
          type: string
          pattern: ^dom_
        name:
          type: string
          examples:
            - shop.shadyventures.ng
        apex:
          type: string
          examples:
            - shadyventures.ng
          description: The registrable part.
        host:
          type: string
          examples:
            - shop
            - "@"
          description: What precedes the apex; `@` for the apex itself.
        dns:
          $ref: "#/components/schemas/DnsMode"
        state:
          $ref: "#/components/schemas/DomainState"
        project:
          description: What it serves or redirects for; null is "Not in use".
          oneOf:
            - type: "null"
            - type: object
              required:
                - id
                - slug
                - name
              properties:
                id:
                  type: string
                slug:
                  type: string
                name:
                  type: string
        branch:
          type:
            - string
            - "null"
          description: The branch whose newest ready preview it serves; null for production.
        redirect:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/Redirect"
        required_record:
          type:
            - object
            - "null"
          description: "The one record an external domain needs at its DNS provider: an A record at an apex (a CNAME can't sit there), a CNAME below it. Null on Orbits DNS, which keeps the record itself."
          required:
            - type
            - name
            - value
          properties:
            type:
              type: string
              enum:
                - A
                - CNAME
            name:
              type: string
              examples:
                - shop
                - "@"
            value:
              type: string
              examples:
                - cname.theorbits.app
        seen:
          type:
            - string
            - "null"
          examples:
            - CNAME old-host.example.net
            - A 41.203.67.12
            - NS ns1.whogohost.com, ns2.whogohost.com
          description: What the last check found where the record (or, for an Orbits DNS zone, the nameservers) should be; null when nothing was there.
        nameservers:
          type:
            - object
            - "null"
          description: "An Orbits DNS zone's nameservers: for an apex, to set at its registrar; for a subdomain zone, to add as NS records for it at its parent's DNS. `pointing` once the zone is handed to them. Null for any other domain, including names inside a zone."
          required:
            - names
            - pointing
          properties:
            names:
              type: array
              items:
                type: string
              examples:
                - - ns1.theorbits.app
                  - ns2.theorbits.app
            pointing:
              type: boolean
        email:
          type:
            - string
            - "null"
          enum:
            - zoho
            - google
            - microsoft
            - null
          description: The provider Email setup added records for, on an Orbits DNS zone.
        certificate:
          type: object
          required:
            - state
            - issued_at
            - expires_at
          properties:
            state:
              type: string
              enum:
                - none
                - pending
                - active
                - failed
              description: "`none`: not needed yet (DNS not found, or the domain isn't in use). `pending`: DNS points here and the certificate is being issued; Orbits waits until public DNS answers for the name before asking Let's Encrypt. `failed`: the last try failed; it is tried again 5, 15, 30, then 60 minutes after each failure."
            issued_at:
              type:
                - string
                - "null"
              format: date-time
            expires_at:
              type:
                - string
                - "null"
              format: date-time
              description: It renews on its own about 30 days before.
        checked_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
    DomainPreview:
      type: object
      required:
        - domain
        - apex
        - host
        - dns
        - zone
        - required_record
        - nameservers
        - existing
      properties:
        domain:
          type: string
          examples:
            - pay.shadyventures.ng
          description: "As Add would store it: scheme, path and trailing dot off, lowercased."
        apex:
          type: string
        host:
          type: string
          examples:
            - pay
            - "@"
        dns:
          $ref: "#/components/schemas/DnsMode"
          description: What it would use. A name inside one of the team's zones is on Orbits DNS whatever was asked.
        zone:
          type:
            - string
            - "null"
          examples:
            - shadyventures.com
          description: The team's Orbits DNS zone it would be in (itself, when it would become a zone); null on outside DNS.
        required_record:
          type:
            - object
            - "null"
          description: The one record to add at the team's DNS provider, on outside DNS.
          required:
            - type
            - name
            - value
          properties:
            type:
              type: string
              enum:
                - A
                - CNAME
            name:
              type: string
            value:
              type: string
        nameservers:
          type:
            - array
            - "null"
          items:
            type: string
          description: "When it would become a zone: the nameservers to set (an apex) or add as NS records at its parent's DNS (a subdomain)."
        existing:
          description: The team has this domain already. Add links it to the request's project or redirect when it serves nothing; otherwise it's a 409.
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/Domain"
    EmailSetup:
      type: object
      required:
        - zone
        - provider
        - email_records
        - providers
      properties:
        zone:
          type: string
          examples:
            - shadyventures.com
        provider:
          type:
            - string
            - "null"
          enum:
            - zoho
            - google
            - microsoft
            - null
          description: "Set up now: the Active badge. Null when none is."
        email_records:
          type: integer
          description: The zone's mail records now (MX, SPF, Microsoft's autodiscover), for "Already set up · 5 records".
        providers:
          type: array
          items:
            type: object
            required:
              - id
              - records
            properties:
              id:
                type: string
                enum:
                  - zoho
                  - google
                  - microsoft
                  - other
              records:
                type: array
                items:
                  $ref: "#/components/schemas/DnsRecordInput"
                description: What Setup would add; empty for `other`.
    DomainList:
      type: object
      required:
        - as_of
        - items
        - summary
        - projects
      properties:
        as_of:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: "#/components/schemas/Domain"
        summary:
          type: object
          description: The team's domains whatever the filters.
          required:
            - total
            - apex
            - orbits
            - pending
            - misconfigured
          properties:
            total:
              type: integer
            apex:
              type: integer
              description: How many are apex domains; the rest are subdomains.
            orbits:
              type: array
              items:
                type: string
              description: Names of the domains on Orbits DNS.
            pending:
              type: integer
            misconfigured:
              type: integer
        projects:
          type: array
          description: The team's projects, for the project filter.
          items:
            type: object
            required:
              - id
              - slug
              - name
            properties:
              id:
                type: string
              slug:
                type: string
              name:
                type: string
    Integration:
      type: object
      required:
        - key
        - name
        - category
        - installed
      properties:
        key:
          type: string
          examples:
            - github
        name:
          type: string
          examples:
            - GitHub
        category:
          type: string
          enum:
            - source_code
            - notifications
            - payments
            - monitoring
        description:
          type: string
          examples:
            - Import repositories and deploy on every push.
        available:
          type: boolean
          description: False when the integration is listed but cannot be installed yet.
        installed:
          type: boolean
        status:
          type:
            - string
            - "null"
          enum:
            - connected
            - needs_attention
            - null
        summary:
          type:
            - string
            - "null"
          description: One line for the Installed tab, e.g. "Repositories for shadyventures".
        scope:
          type:
            - string
            - "null"
          examples:
            - All projects
        installed_at:
          type:
            - string
            - "null"
          format: date-time
        installed_by:
          oneOf:
            - type: "null"
            - type: object
              required:
                - id
                - name
              properties:
                id:
                  type: string
                name:
                  type: string
        fields:
          type: array
          description: Inputs needed to install. Secret values are never returned.
          items:
            type: object
            required:
              - name
              - secret
            properties:
              name:
                type: string
              label:
                type: string
              secret:
                type: boolean
        projects:
          type: array
          items:
            type: string
    UsageTotals:
      type: object
      required:
        - requests
        - bandwidth_bytes
        - build_minutes
        - function_runs
        - deployments
        - log_lines
      properties:
        requests:
          type: integer
        bandwidth_bytes:
          type: integer
        build_minutes:
          type: number
          description: One decimal place.
        function_runs:
          type: integer
        deployments:
          type: integer
        log_lines:
          type: integer
    UsageDay:
      type: object
      required:
        - date
        - totals
      properties:
        date:
          type: string
          format: date
        totals:
          $ref: "#/components/schemas/UsageTotals"
    Usage:
      type: object
      required:
        - month
        - current
        - months
        - days
        - totals
        - deleted_projects
        - previous
        - daily
        - by_project
        - logs_available
      properties:
        logs_available:
          type: boolean
          description: "False while the log store can't be reached: requests, bandwidth and function runs are then zeros, not a quiet month; builds and deployments still count. Show the log figures as unavailable."
        month:
          type: string
          examples:
            - 2026-10
        current:
          type: boolean
          description: This month, so the series stops at today.
        months:
          type: array
          items:
            type: string
          description: From the team's first deployment to now, newest first.
        days:
          type: array
          items:
            type: string
            format: date
          description: The month's days so far.
        totals:
          $ref: "#/components/schemas/UsageTotals"
        deleted_projects:
          allOf:
            - $ref: "#/components/schemas/UsageTotals"
          description: Usage of projects deleted since, which `totals` includes and `by_project` doesn't; zeros when there is none.
        previous:
          oneOf:
            - type: object
              required:
                - month
                - totals
              properties:
                month:
                  type: string
                totals:
                  $ref: "#/components/schemas/UsageTotals"
            - type: "null"
          description: The same days of the month before; null when the team had no deployments before this month.
        daily:
          type: array
          items:
            $ref: "#/components/schemas/UsageDay"
        by_project:
          type: array
          description: Every project the team has, most requests first. A deleted project's usage counts in the totals only.
          items:
            type: object
            required:
              - project_id
              - slug
              - name
              - totals
              - previous
              - daily
              - by_environment
              - preview_branches
            properties:
              project_id:
                type: string
              slug:
                type: string
              name:
                type: string
              totals:
                $ref: "#/components/schemas/UsageTotals"
              previous:
                oneOf:
                  - $ref: "#/components/schemas/UsageTotals"
                  - type: "null"
              daily:
                type: array
                items:
                  $ref: "#/components/schemas/UsageDay"
              by_environment:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/UsageTotals"
                description: Keyed by `production`, `preview` or `development`, for those with usage.
              preview_branches:
                type: integer
                description: Branches with a preview deployment this month.
    ActivityCategory:
      type: string
      enum:
        - deployments
        - domains
        - members
        - variables
        - integrations
        - projects
        - team
      description: What a line is about, as the Activity page's type filter groups them. `domains` has no lines yet.
    Activity:
      type: object
      required:
        - id
        - type
        - category
        - actor
        - summary
        - project_id
        - project
        - deployment_id
        - failed
        - created_at
      properties:
        id:
          type: string
          examples:
            - act_0193a1f2-6c1e-7d2a-9b3f-1e2d3c4b5a69
        type:
          type: string
          description: The event it was written from.
          examples:
            - project.production.changed
            - deployment.failed
            - team.member.added
        category:
          $ref: "#/components/schemas/ActivityCategory"
        actor:
          type: object
          required:
            - kind
            - user_id
            - name
          description: "Who did it: a member (`user`), a commit's author for a push (`git`, no `user_id`), or Orbits itself (`system`)."
          properties:
            kind:
              type: string
              enum:
                - user
                - system
                - git
            user_id:
              type:
                - string
                - "null"
            name:
              type: string
        summary:
          type: string
          description: The whole sentence, ready to show.
          examples:
            - Ada promoted a1f9c2e to production
        project_id:
          type:
            - string
            - "null"
        project:
          type:
            - object
            - "null"
          required:
            - id
            - slug
            - name
          description: The project it's about, as it was named then.
          properties:
            id:
              type: string
            slug:
              type: string
            name:
              type: string
        deployment_id:
          type:
            - string
            - "null"
          description: The deployment it's about, for a link to its page.
        failed:
          type: boolean
          description: "A build that failed: the page shows the line in red."
        created_at:
          type: string
          format: date-time
    ActivityPage:
      type: object
      required:
        - as_of
        - items
        - total
        - total_capped
        - next_cursor
        - any
        - people
        - projects
      properties:
        as_of:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: "#/components/schemas/Activity"
        total:
          type: integer
          maximum: 10000
          description: Lines that match the filters, counted up to 10,000.
        total_capped:
          type: boolean
          description: More than 10,000 lines match, so `total` is 10,000.
        next_cursor:
          type:
            - string
            - "null"
        any:
          type: boolean
          description: "Whether there is any activity at all, the other filters aside: in the team, or in the project when `project` is set. For the empty state."
        people:
          type: array
          description: Everyone who appears in the feed (or the project's lines, with `project`), most recent first, for the person filter.
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: string
              name:
                type: string
        projects:
          type: array
          description: Every project the feed mentions, most recent first, for the project filter.
          items:
            type: object
            required:
              - id
              - slug
              - name
            properties:
              id:
                type: string
              slug:
                type: string
              name:
                type: string
