swagger.yaml

---
openapi: 3.0.3
info:
  title: Build.io API V1
  version: v1
  description: |-
    ## Authentication

    All endpoints accept an OAuth Bearer token in the `Authorization` header.

    Tokens come in four kinds, distinguished by their resource owner:

    - **User tokens** (default) — full access to the user's apps, teams, pipelines, and namespaces.
    - **App-scoped tokens** (prefix `bldp_`) — bound to a single app. Can only access endpoints
      that operate on that one app (e.g. `GET /api/v1/apps/:id`, builds, dynos, config vars).
      Endpoints that operate on user-level collections (`/api/v1/apps`, `/api/v1/teams`,
      `/api/v1/pipelines`, `/api/v1/namespaces`, `/api/v1/addon-attachments`, `/api/v1/addons`)
      return **403 Forbidden** for these tokens.
    - **Team-scoped tokens** (prefix `bldp_`) — bound to a single team. Can access that team's
      apps, pipelines, and namespaces and all per-app endpoints for those apps; cannot create
      apps or transfer addon billing. `/api/v1/me` returns `{ team, email }` for these tokens.
    - **Addon partner tokens** (`addon:config` scope) — issued to addon vendors for partner
      endpoints only.

    The `/api/v1/me` response shape varies by token kind: user tokens return `{ email }`;
    app-scoped tokens return `{ app, email }`; team-scoped tokens return `{ team, email }`
    where `email` belongs to the user that minted the token.
paths:
  "/api/v1/addon-attachments":
    get:
      summary: list addon attachments
      tags:
      - Addon Attachments
      security:
      - bearer: []
        oauth2: []
      description: List all addon attachments
      operationId: listAddonAttachments
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/addon_attachment"
        '403':
          description: app-scoped token forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    post:
      summary: create addon attachment
      tags:
      - Addon Attachments
      security:
      - bearer: []
        oauth2: []
      description: Attach an addon to an app
      operationId: createAddonAttachment
      parameters: []
      responses:
        '201':
          description: attachment created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon_attachment"
        '404':
          description: app not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
        '422':
          description: addon not provisioned
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              title: CreateAddonAttachmentRequest
              type: object
              properties:
                addon:
                  type: string
                  description: Addon name or ID to attach
                app:
                  type: string
                  description: App name or ID to attach the addon to
                name:
                  type: string
                  description: Attachment name (e.g., DATABASE_RED)
                  nullable: true
                confirm:
                  type: string
                  description: Owning app name for confirmation
                  nullable: true
              required:
              - addon
              - app
  "/api/v1/addon-attachments/{addon_attachment_id}":
    parameters:
    - name: addon_attachment_id
      in: path
      description: Addon attachment ID
      required: true
      schema:
        type: string
    get:
      summary: show addon attachment
      tags:
      - Addon Attachments
      security:
      - bearer: []
        oauth2: []
      description: Get info about an addon attachment
      operationId: getAddonAttachment
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon_attachment"
        '404':
          description: attachment not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    delete:
      summary: delete addon attachment
      tags:
      - Addon Attachments
      security:
      - bearer: []
        oauth2: []
      description: Detach an addon from an app
      operationId: deleteAddonAttachment
      responses:
        '200':
          description: attachment deleted
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon_attachment"
        '403':
          description: cannot delete last billing app attachment even with cross-app
            attachments
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
        '404':
          description: attachment not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/addon-services":
    get:
      summary: list addon services
      tags:
      - Addon Services
      security:
      - bearer: []
        oauth2: []
      description: List all visible addon services from the catalog
      operationId: listAddonServices
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/addon_service_catalog_item"
  "/api/v1/addon-services/{name}/plans":
    parameters:
    - name: name
      in: path
      description: Addon service name
      required: true
      schema:
        type: string
    get:
      summary: list plans for addon service
      tags:
      - Addon Services
      security:
      - bearer: []
        oauth2: []
      description: List all visible plans for an addon service
      operationId: listAddonServicePlans
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/addon_plan_catalog_item"
        '404':
          description: service not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/apps/{app_id_or_name}/addons":
    parameters:
    - name: app_id_or_name
      in: path
      description: App ID or name
      required: true
      schema:
        type: string
    get:
      summary: list addons
      tags:
      - Addons
      security:
      - bearer: []
        oauth2: []
      description: List all addons for an app
      operationId: listAppAddons
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/addon"
        '404':
          description: app not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    post:
      summary: create addon
      tags:
      - Addons
      security:
      - bearer: []
        oauth2: []
      description: Create and provision a new addon for an app
      operationId: createAddon
      parameters: []
      responses:
        '201':
          description: addon created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon"
        '422':
          description: unlisted service rejected
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              title: CreateAddonRequest
              type: object
              properties:
                plan:
                  type: string
                  description: Addon service and plan in format "service:plan"
                  example: schema-to-go:basic
                human_name:
                  type: string
                  description: User-provided display name for the addon (optional)
                  nullable: true
                description:
                  type: string
                  description: User-provided description of the addon (optional)
                  nullable: true
                config:
                  type: object
                  description: Addon-specific configuration options (use list-addon-fields
                    to discover available options for each service)
                  additionalProperties:
                    type: string
                  example:
                    region: us-east-1
                    company-name: my-app
              required:
              - plan
  "/api/v1/apps/{app_id_or_name}/addons/{addon_id_or_name}":
    parameters:
    - name: app_id_or_name
      in: path
      description: App ID or name
      required: true
      schema:
        type: string
    - name: addon_id_or_name
      in: path
      description: Addon ID or name
      required: true
      schema:
        type: string
    get:
      summary: show addon
      tags:
      - Addons
      security:
      - bearer: []
        oauth2: []
      description: Get info about an addon
      operationId: getAddon
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon"
        '404':
          description: addon not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    delete:
      summary: destroy addon
      tags:
      - Addons
      security:
      - bearer: []
        oauth2: []
      description: Destroy an addon (deprovisions and removes from all attached apps)
      operationId: destroyAddon
      responses:
        '200':
          description: addon destroyed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon"
        '404':
          description: addon not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/addons/{id}":
    parameters:
    - name: id
      in: path
      description: Addon ID or name
      required: true
      schema:
        type: string
    get:
      summary: show addon info
      tags:
      - Addons
      security:
      - bearer: []
        oauth2: []
      description: Get detailed addon info including attachments
      operationId: getAddonInfo
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon_with_attachments"
        '404':
          description: addon not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    patch:
      summary: transfer addon billing
      tags:
      - Addons
      security:
      - bearer: []
        oauth2: []
      description: Move which app owns and pays for the addon. The target app must
        already have the addon attached and must belong to the same team.
      operationId: transferAddonBilling
      parameters: []
      responses:
        '200':
          description: billing transferred
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/addon_with_attachments"
        '403':
          description: addon tokens cannot transfer billing
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
        '404':
          description: target app not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
        '422':
          description: target app is not eligible
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - billing_entity
              properties:
                billing_entity:
                  type: object
                  required:
                  - app
                  properties:
                    app:
                      type: string
                      description: Target app name or ID
        required: true
  "/api/v1/teams/{team_id}/addons":
    parameters:
    - name: team_id
      in: path
      description: Team ID or name
      required: true
      schema:
        type: string
    get:
      summary: list team addons
      tags:
      - Addons
      security:
      - bearer: []
        oauth2: []
      description: List all addons for a team (across all apps)
      operationId: listTeamAddons
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/addon"
        '404':
          description: team not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/apps/{app_id}/collaborators":
    get:
      summary: List collaborators for an app
      tags:
      - Collaborators
      security:
      - bearer: []
        oauth2: []
      parameters:
      - name: app_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns collaborators
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/collaborator"
        '404':
          description: App not found
        '401':
          description: Unauthorized
  "/api/v1/apps":
    get:
      summary: list apps
      security:
      - bearer: []
        oauth2: []
      description: List all apps
      parameters:
      - name: team_id
        in: query
        description: team id or name
        schema:
          type: string
      operationId: apps
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                title: AppsResponse
                type: array
                items:
                  "$ref": "#/components/schemas/app"
        '403':
          description: app-scoped token forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    post:
      summary: create app
      security:
      - bearer: []
        oauth2: []
      operationId: CreateApp
      parameters: []
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/app"
        '403':
          description: app-scoped token forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              title: CreateAppRequest
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                  nullable: true
                team_id:
                  type: string
                  format: uuid
                  nullable: true
                region:
                  type: string
                  nullable: true
              required:
              - name
  "/api/v1/apps/{app_id_or_name}":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    get:
      summary: show app
      security:
      - bearer: []
        oauth2: []
      operationId: app
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/app"
    patch:
      summary: update app
      security:
      - bearer: []
        oauth2: []
      operationId: updateApp
      description: Update app attributes. Use build_stack to change the stack for
        the next build.
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/app"
        '422':
          description: invalid stack
      requestBody:
        content:
          application/json:
            schema:
              title: UpdateAppRequest
              type: object
              properties:
                build_stack:
                  type: string
                  description: Stack for the next build (e.g. heroku-22, heroku-24)
  "/api/v1/apps/{app_id_or_name}/buildpacks":
    parameters:
    - name: app_id_or_name
      in: path
      description: App ID or name
      required: true
      schema:
        type: string
    get:
      summary: list buildpacks
      tags:
      - Buildpacks
      security:
      - bearer: []
        oauth2: []
      operationId: listBuildpacks
      description: List an app's buildpack installations in execution order
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/buildpack_installation"
        '404':
          description: app not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    put:
      summary: update buildpacks
      tags:
      - Buildpacks
      security:
      - bearer: []
        oauth2: []
      operationId: updateBuildpacks
      description: Replace an app's buildpack list. Order determines execution order.
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/buildpack_installation"
        '422':
          description: invalid params
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
        '404':
          description: app not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - updates
              properties:
                updates:
                  type: array
                  description: Ordered list of buildpacks. The order determines execution
                    order.
                  items:
                    type: object
                    required:
                    - buildpack
                    properties:
                      buildpack:
                        type: string
                        description: Buildpack registry name or URL
  "/api/v1/apps/{app_id}/builds":
    parameters:
    - name: app_id
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: limit
      in: query
      required: false
      description: Page size. Defaults to 25, capped at 100.
      schema:
        type: integer
    - name: cursor
      in: query
      required: false
      description: Opaque cursor, taken from the previous response's Link header.
      schema:
        type: string
    get:
      summary: list builds
      security:
      - bearer: []
        oauth2: []
      operationId: builds
      description: 'Builds for an app, newest first. Keyset paginated: when more results
        exist the response carries an RFC 8288 Link header with rel="next". Absent
        means the last page.'
      responses:
        '200':
          description: successful
          headers:
            Link:
              schema:
                type: string
              required: false
              description: 'RFC 8288 link to the next page: <url>; rel="next". Absent
                on the last page.'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/build"
  "/api/v1/apps/{app_id}/builds/{id}":
    parameters:
    - name: app_id
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: build id
      required: true
      schema:
        type: string
    get:
      summary: show build
      security:
      - bearer: []
        oauth2: []
      operationId: build
      description: A single build. Previously routed but unimplemented, so it 404ed.
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/build"
        '404':
          description: not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/apps/{app_id_or_name}/config-vars":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    get:
      summary: list all config-vars
      security:
      - bearer: []
        oauth2: []
      operationId: config_vars
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                title: ConfigVarsResponse
                type: object
                additionalProperties:
                  type: string
    patch:
      summary: set or update config-vars
      security:
      - bearer: []
        oauth2: []
      parameters: []
      operationId: set_config_vars
      responses:
        '200':
          description: successful
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
              example:
                KEY1: value1
                KEY2: value2
              description: Dynamic key-value pairs for configuration variables
  "/api/v1/apps/{app_id_or_name}/config-vars/{key}":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: key
      in: path
      description: config var key
      required: true
      schema:
        type: string
    delete:
      summary: delete config-var
      description: Delete a config-var
      security:
      - bearer: []
        oauth2: []
      operationId: delete_config_var
      responses:
        '204':
          description: successful
  "/api/v1/apps/{app_id}/deployments":
    parameters:
    - name: app_id
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: limit
      in: query
      required: false
      description: Page size. Defaults to 25, capped at 100.
      schema:
        type: integer
    - name: cursor
      in: query
      required: false
      description: Opaque cursor, taken from the previous response's Link header.
      schema:
        type: string
    get:
      summary: list deployments
      security:
      - bearer: []
        oauth2: []
      operationId: deployments
      description: 'Deployments for an app, newest first. Keyset paginated the same
        way as builds: an RFC 8288 Link header when more results exist.'
      responses:
        '200':
          description: successful
          headers:
            Link:
              schema:
                type: string
              required: false
              description: 'RFC 8288 link to the next page: <url>; rel="next". Absent
                on the last page.'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/deployment"
  "/api/v1/apps/{app_id}/deployments/{id}":
    parameters:
    - name: app_id
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: deployment id
      required: true
      schema:
        type: string
    get:
      summary: show deployment
      security:
      - bearer: []
        oauth2: []
      operationId: deployment
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/deployment"
        '404':
          description: not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/apps/{app_id_or_name}/domains":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    get:
      summary: list domains
      tags:
      - Domains
      security:
      - bearer: []
        oauth2: []
      operationId: listDomains
      description: List all domains for an app (platform domain + custom domains)
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/domain"
    post:
      summary: create domain
      tags:
      - Domains
      security:
      - bearer: []
        oauth2: []
      operationId: createDomain
      description: Add a domain to an app
      parameters: []
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/domain"
        '422':
          description: invalid hostname
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  description: The domain to add
                cert:
                  type: string
                  nullable: true
                  description: Certificate name (optional)
              required:
              - hostname
    delete:
      summary: clear all domains
      tags:
      - Domains
      security:
      - bearer: []
        oauth2: []
      operationId: clearDomains
      description: Clear all custom domains from an app
      responses:
        '204':
          description: no content
  "/api/v1/apps/{app_id_or_name}/domains/{domain_id}":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: domain_id
      in: path
      description: domain id or hostname
      required: true
      schema:
        type: string
    get:
      summary: show domain
      tags:
      - Domains
      security:
      - bearer: []
        oauth2: []
      operationId: showDomain
      description: Get detailed information about a specific domain
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/domain"
        '404':
          description: not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    patch:
      summary: update domain
      tags:
      - Domains
      security:
      - bearer: []
        oauth2: []
      operationId: updateDomain
      description: Update a domain (e.g., change SSL certificate)
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/domain"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cert:
                  type: string
                  description: New certificate name
    delete:
      summary: remove domain
      tags:
      - Domains
      security:
      - bearer: []
        oauth2: []
      operationId: removeDomain
      description: Remove a domain from an app
      responses:
        '204':
          description: no content
        '422':
          description: cannot delete platform domain
  "/api/v1/apps/{app_id_or_name}/dynos/list":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    get:
      summary: list dynos
      security:
      - bearer: []
        oauth2: []
      operationId: list_dynos
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                title: DynosResponse
                type: array
                items:
                  "$ref": "#/components/schemas/dyno"
  "/api/v1/apps/{app_id_or_name}/dynos":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    delete:
      summary: restart all dynos
      security:
      - bearer: []
        oauth2: []
      operationId: restart_all_dynos
      responses:
        '204':
          description: successful
  "/api/v1/apps/{app_id_or_name}/dynos/{dyno}":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: dyno
      in: path
      description: dyno name
      required: true
      schema:
        type: string
    delete:
      summary: restart specific dyno
      security:
      - bearer: []
        oauth2: []
      operationId: restart_dynos
      responses:
        '204':
          description: successful
  "/api/v1/apps/{app_id_or_name}/dynos/run":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    post:
      summary: run one-off command
      security:
      - bearer: []
        oauth2: []
      operationId: run_dyno
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                title: DynoRunResponse
                type: object
                properties:
                  output:
                    type: string
                  status:
                    type: string
                required:
                - output
                - status
        '201':
          description: 'attach: a ticket for an SSH session'
          content:
            application/json:
              schema:
                title: DynoRunTicketResponse
                type: object
                properties:
                  ticket:
                    type: string
                    description: SSH password, valid for expires_in seconds
                  expires_in:
                    type: integer
                  size:
                    type: string
                required:
                - ticket
                - expires_in
                - size
        '403':
          description: attach with an app-scoped token
        '404':
          description: app not found
        '422':
          description: missing command, or invalid size
      requestBody:
        content:
          application/json:
            schema:
              title: DynoRunRequest
              type: object
              properties:
                command:
                  type: string
                  description: Shell command to run (required unless attach is true)
                type:
                  type: string
                  description: 'Process type (default: worker)'
                size:
                  type: string
                  description: 'Dyno size (default: from formation; with attach, like
                    a Heroku one-off dyno)'
                timeout:
                  type: integer
                  description: 'Timeout in seconds (30–1800, default: 300)'
                attach:
                  type: boolean
                  description: Run no Job; return a short-lived ticket to use as the
                    SSH password (bld run)
        required: true
  "/api/v1/apps/{app_id_or_name}/dynos/{dyno}/exec":
    parameters:
    - name: app_id_or_name
      in: path
      description: app id or name
      required: true
      schema:
        type: string
    - name: dyno
      in: path
      description: dyno name
      required: true
      schema:
        type: string
    post:
      summary: exec into dyno
      security:
      - bearer: []
        oauth2: []
      operationId: exec_dyno
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                title: DynoExecResponse
                type: object
                properties:
                  output:
                    type: string
                  stderr:
                    type: string
                  exit_code:
                    type: integer
                required:
                - output
                - stderr
                - exit_code
        '422':
          description: missing parameters
      requestBody:
        content:
          application/json:
            schema:
              title: DynoExecRequest
              type: object
              properties:
                command:
                  title: DynoExecRequestCommand
                  type: array
                  items:
                    type: string
                  description: Command to execute in the dyno. Must be an array of
                    strings (e.g. ["/bin/sh", "-c", "echo hello"]).
              required:
              - command
        required: true
  "/api/v1/apps/{app_id_or_name}/formation":
    parameters:
    - name: app_id_or_name
      in: path
      description: App ID or name
      required: true
      schema:
        type: string
    patch:
      summary: batch update formation
      tags:
      - Formation
      security:
      - bearer: []
        oauth2: []
      description: Batch update process formation (Heroku-compatible)
      operationId: updateFormation
      parameters: []
      responses:
        '200':
          description: update size only
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: unknown process type
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
        '404':
          description: app not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              title: FormationBatchUpdateRequest
              type: object
              properties:
                updates:
                  type: array
                  items:
                    "$ref": "#/components/schemas/formation_update"
                  description: Array of process updates
              required:
              - updates
  "/api/v1/me":
    get:
      summary: identity
      operationId: me
      security:
      - bearer: []
        oauth2: []
      description: |-
        Returns identity info for the bearer. Response shape varies by token kind:
        user tokens return { email }; app-scoped tokens (bldp_) return { app, email }
        where email is the minting user's email.
      responses:
        '200':
          description: 'team-scoped token: returns the bound team and minter email'
          content:
            application/json:
              schema:
                title: AppMeResponse
                type: object
                properties:
                  email:
                    type: string
                    nullable: true
                    description: Email of the user who minted the token
                  app:
                    type: object
                    title: MeApp
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                    required:
                    - id
                    - name
                  team:
                    type: object
                    title: MeTeam
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                    required:
                    - id
                    - name
                required:
                - email
        '401':
          description: no authentication
  "/api/v1/namespaces":
    get:
      summary: list all namespaces
      description: List all namespaces
      security:
      - bearer: []
        oauth2: []
      operationId: namespaces
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/namespace"
        '403':
          description: app-scoped token forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
    post:
      summary: create a namespace
      description: Create a namespace (deprecated - namespaces are now managed by
        Kubernetes)
      security:
      - bearer: []
        oauth2: []
      parameters: []
      operationId: create_namespace
      responses:
        '410':
          description: gone
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: CreateNamespaceRequest
              properties:
                name:
                  type: string
                zone_id:
                  type: string
                  format: uuid
                  description: Zone ID (required - namespaces are zone-scoped)
                team_id:
                  type: string
                  nullable: true
                description:
                  type: string
                  nullable: true
                region:
                  type: string
                  nullable: true
              required:
              - name
              - zone_id
  "/api/v1/namespaces/{namespace_id_or_name}":
    parameters:
    - name: namespace_id_or_name
      in: path
      required: true
      description: Namespace name or ID
      schema:
        type: string
    get:
      summary: show namespace
      description: Show a namespace
      security:
      - bearer: []
        oauth2: []
      operationId: namespace
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/namespace"
    delete:
      summary: delete a namespace
      description: Delete a namespace
      security:
      - bearer: []
        oauth2: []
      operationId: delete_namespace
      responses:
        '204':
          description: successful
  "/api/v1/oidc-login":
    get:
      summary: kubernetes oidc-login
      operationId: oidc_login
      security:
      - bearer: []
        oauth2: []
        api_key: []
        openIdConnect: []
      parameters:
      - name: region
        in: query
        schema:
          type: string
          example: us-test-1
          description: Region for the cluster
          required:
          - region
      responses:
        '200':
          description: properly authenticated request
          content:
            application/json:
              examples:
                oidc_body:
                  value:
                    kind: ExecCredential
                    apiVersion: client.authentication.k8s.io/v1beta1
                    spec:
                      interactive: false
                    status:
                      expirationTimestamp: '2024-05-23T14:20:59Z'
                      token: eyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
              schema:
                title: OidcLoginResponse
                type: object
                properties:
                  kind:
                    type: string
                  apiVersion:
                    type: string
                  spec:
                    type: object
                    title: OidcLoginResponseSpec
                    properties:
                      interactive:
                        type: boolean
                  status:
                    type: object
                    title: OidcLoginResponseStatus
                    properties:
                      expirationTimestamp:
                        type: string
                      token:
                        type: string
                required:
                - kind
                - apiVersion
                - spec
                - status
        '401':
          description: no authentication
  "/api/v1/pipelines/{pipeline_id_or_name}":
    parameters:
    - name: pipeline_id_or_name
      in: path
      description: Pipeline ID or Name
      required: true
      schema:
        type: string
    get:
      summary: get a specific pipeline
      tags:
      - Pipelines
      security:
      - bearer: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/pipeline"
        '404':
          description: pipeline not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      description: Retrieves details for a specific pipeline
      operationId: get_pipeline
  "/api/v1/environments/{id}":
    parameters:
    - name: id
      in: path
      description: Environment ID
      required: true
      schema:
        type: string
    get:
      summary: get environment config-vars (e.g. pipeline RA env)
      tags:
      - - Environments
      security:
      - bearer: []
        oauth2: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          description: 'not found - security: cannot access environments from other
            teams'
    patch:
      summary: set or update environment config-vars (e.g. pipeline RA env)
      tags:
      - - Environments
      security:
      - bearer: []
        oauth2: []
      parameters: []
      responses:
        '200':
          description: successful
        '404':
          description: 'not found - security: cannot update environments from other
            teams'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
              example:
                KEY1: value1
                KEY2: value2
                KEY_TO_DELETE:
              description: Key-value pairs; set string values, use null to delete
  "/api/v1/environments/{id}/{key}":
    parameters:
    - name: id
      in: path
      description: Environment ID
      required: true
      schema:
        type: string
    - name: key
      in: path
      description: config var key
      required: true
      schema:
        type: string
    delete:
      summary: delete environment config-var
      tags:
      - - Environments
      security:
      - bearer: []
        oauth2: []
      responses:
        '204':
          description: successful
  "/api/v1/pipelines":
    get:
      summary: list pipelines
      tags:
      - Pipelines
      security:
      - bearer: []
      description: Lists pipelines for the current user. Defaults to personal team;
        pass team_id to select a different team.
      operationId: list_pipelines
      parameters:
      - name: team_id
        in: query
        required: false
        description: Team ID or name. Defaults to personal team (matching apps#index).
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/pipeline"
        '403':
          description: app-scoped token forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/pipelines/{pipeline_id_or_name}/apps":
    parameters:
    - name: pipeline_id_or_name
      in: path
      description: Pipeline ID or Name
      required: true
      schema:
        type: string
    get:
      summary: list apps in a pipeline
      tags:
      - Pipelines
      security:
      - bearer: []
      description: A list of applications in the pipeline.
      operationId: list_pipeline_apps
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/app"
        '404':
          description: pipeline not found for apps list
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/pipelines/{pipeline_id_or_name}/diff":
    parameters:
    - name: pipeline_id_or_name
      in: path
      description: Pipeline ID or Name
      required: true
      schema:
        type: string
    - name: source_app
      in: query
      description: Source app ID or name
      required: true
      schema:
        type: string
    get:
      summary: compare source app commits to downstream apps
      tags:
      - Pipelines
      security:
      - bearer: []
      description: Compares the source app current commit to each downstream app via
        GitHub compare API.
      operationId: get_pipeline_diff
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                  diffs:
                    type: array
                    items:
                      type: object
                      properties:
                        app:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                        status:
                          type: string
                          enum:
                          - ahead
                          - behind
                          - identical
                          - diverged
                          - error
                          - unavailable
                        ahead_by:
                          type: integer
                        behind_by:
                          type: integer
                        error_message:
                          type: string
                        commits:
                          type: array
                          items:
                            type: object
                            properties:
                              sha:
                                type: string
                              message:
                                type: string
                              author:
                                type: string
                                nullable: true
                              date:
                                type: string
                                nullable: true
        '404':
          description: source app not found
        '422':
          description: no downstream apps
  "/api/v1/pipelines/{pipeline_id}/promotions":
    parameters:
    - name: pipeline_id
      in: path
      description: Pipeline ID
      required: true
      schema:
        type: string
    post:
      summary: create a pipeline promotion
      tags:
      - Pipeline Promotions
      security:
      - bearer: []
      description: Creates a promotion from a source app to one or more target apps.
        Returns immediately with pending status — clients poll GET .../promotions/:id
        for completion.
      operationId: create_pipeline_promotion
      parameters: []
      responses:
        '201':
          description: groups all targets under first promotion ID
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/pipeline_promotion"
        '404':
          description: source app not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
        '422':
          description: source app not in pipeline
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: object
                  properties:
                    app:
                      type: string
                      description: Source app ID or name
                  required:
                  - app
                targets:
                  type: array
                  description: Target apps. Omit to promote to all downstream apps.
                  items:
                    type: object
                    properties:
                      app:
                        type: string
                        description: Target app ID or name
              required:
              - source
  "/api/v1/pipelines/{pipeline_id}/promotions/{id}":
    parameters:
    - name: pipeline_id
      in: path
      description: Pipeline ID
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: Promotion group ID
      required: true
      schema:
        type: string
    get:
      summary: get promotion status
      tags:
      - Pipeline Promotions
      security:
      - bearer: []
      description: Returns aggregate promotion status. Clients poll this until status
        is no longer pending.
      operationId: get_pipeline_promotion
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/pipeline_promotion"
        '404':
          description: promotion not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/pipelines/{pipeline_id}/promotions/{id}/promotion-targets":
    parameters:
    - name: pipeline_id
      in: path
      description: Pipeline ID
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: Promotion group ID
      required: true
      schema:
        type: string
    get:
      summary: list promotion targets
      tags:
      - Pipeline Promotions
      security:
      - bearer: []
      description: Returns per-target status with error_message on failure.
      operationId: get_pipeline_promotion_targets
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/promotion_target"
        '404':
          description: promotion not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/teams":
    get:
      summary: list all teams
      security:
      - bearer: []
        oauth2: []
      description: List all teams
      operationId: teams
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                title: TeamsResponse
                type: array
                items:
                  "$ref": "#/components/schemas/team"
        '403':
          description: app-scoped token forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
  "/api/v1/teams/{id}":
    parameters:
    - name: id
      in: path
      required: true
      description: Team name or ID
      schema:
        type: string
    get:
      summary: show team
      description: Show a team
      security:
      - bearer: []
        oauth2: []
      operationId: team
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/team"
        '403':
          description: app-scoped token forbidden
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error_response"
servers:
- url: "/"
components:
  schemas:
    error_response:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details (optional)
          additionalProperties: true
      required:
      - code
      example:
        code: not_found
        message: The requested resource was not found
        details:
          available_options:
          - option1
          - option2
    validation_errors:
      type: object
      properties:
        error:
          type: string
          example: validation_failed
        error_description:
          type: string
          example: Validation failed
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            name:
            - is required
            email:
            - is invalid
      required:
      - error
    app:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        team:
          type: object
          title: AppTeam
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        pipeline:
          type: object
          title: AppPipeline
          properties:
            id:
              type: string
              format: uuid
              nullable: true
            name:
              type: string
              nullable: true
          nullable: true
        dns_refreshed_at:
          type: string
          format: date_time
          nullable: true
        builds_count:
          type: integer
        deployments_count:
          type: integer
        slugs_count:
          type: integer
        current_build_id:
          type: string
          format: uuid
          nullable: true
        current_image_id:
          type: string
          format: uuid
          nullable: true
        current_deployment_id:
          type: string
          format: uuid
          nullable: true
        formation:
          type: object
          additionalProperties:
            type: object
            title: AppFormationValue
            properties:
              size:
                type: string
              display:
                type: string
              quantity:
                type: integer
            example:
              web:
                size: basic
                display: server start
                quantity: 1
            description: Dyno formation
        build_stack:
          type: string
          description: 'Stack for the next build (Heroku: build_stack)'
        stack:
          type: string
          description: 'Stack currently deployed (Heroku: stack)'
        region:
          type: string
        buildpacks:
          type: array
          items:
            type: object
            title: AppBuildpack
            properties:
              url:
                type: string
        description:
          type: string
          nullable: true
        pipeline_stage:
          type: string
          nullable: true
        policy_allow_websockets:
          type: boolean
        policy_response_timeout:
          type: integer
        policy_max_connections:
          type: integer
        policy_erosion_resistance_seconds:
          type: integer
        policy_share_process_namespace:
          type: boolean
        policy_temporary_self_signed:
          type: boolean
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
        deleted_at:
          type: string
          format: date_time
          nullable: true
        web_url:
          type: string
          description: Full HTTPS URL for the application
        git_url:
          type: string
          description: Git push URL for deploying via git push
        branch:
          type: string
          nullable: true
          description: GitHub branch for the application
        environment_id:
          type: string
          format: uuid
        ssh_host:
          type: string
          description: SSH host for running one-off dynos
          nullable: false
        ssh_port:
          type: integer
          description: SSH port for running one-off dynos
          nullable: false
      required:
      - id
      - name
      - team
      - build_stack
      - region
      - ssh_host
      - ssh_port
    addon_app:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - id
      - name
    attachment_addon:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
        app:
          "$ref": "#/components/schemas/addon_app"
      required:
      - id
      - name
      - app
    addon_attachment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Attachment name (e.g., DATABASE, DATABASE_RED)
        addon:
          "$ref": "#/components/schemas/attachment_addon"
        app:
          "$ref": "#/components/schemas/addon_app"
        state:
          type: string
          enum:
          - pending
          - attached
          - detached
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
      required:
      - id
      - name
      - addon
      - app
      - state
    addon_service_category:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        human_name:
          type: string
      required:
      - id
      - name
      - human_name
    addon_service_catalog_item:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        human_name:
          type: string
        state:
          type: string
        supports_log_drains:
          type: boolean
        supports_sharing:
          type: boolean
        supports_multiple_installations:
          type: boolean
        category:
          "$ref": "#/components/schemas/addon_service_category"
      required:
      - id
      - name
      - human_name
      - state
    addon_plan_price:
      type: object
      properties:
        cents:
          type: integer
        unit:
          type: string
        contract:
          type: boolean
        currency:
          type: string
      required:
      - cents
      - unit
    addon_plan_catalog_item:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        human_name:
          type: string
        description:
          type: string
          nullable: true
        state:
          type: string
        monthly_price:
          "$ref": "#/components/schemas/addon_plan_price"
        yearly_price:
          "$ref": "#/components/schemas/addon_plan_price"
      required:
      - id
      - name
      - human_name
      - state
    addon_service:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - id
      - name
    addon_plan:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - id
      - name
    addon_billed_price:
      type: object
      properties:
        cents:
          type: integer
        unit:
          type: string
        contract:
          type: boolean
      required:
      - cents
      - unit
    addon:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
          description: Globally unique addon name
        human_name:
          type: string
          nullable: true
          description: User-provided display name for the addon
        description:
          type: string
          nullable: true
          description: User-provided description of the addon
        addon_service:
          "$ref": "#/components/schemas/addon_service"
        plan:
          "$ref": "#/components/schemas/addon_plan"
        app:
          "$ref": "#/components/schemas/addon_app"
        state:
          type: string
          enum:
          - pending
          - requested
          - provisioned
          - deprovisioning
          - deprovisioned
        config_vars:
          type: array
          items:
            type: string
          description: Config var names provided by this addon
        billed_price:
          "$ref": "#/components/schemas/addon_billed_price"
        web_url:
          type: string
          nullable: true
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
      required:
      - id
      - addon_service
      - plan
      - app
      - state
    addon_info_attachment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Attachment name (e.g., DATABASE)
        app:
          "$ref": "#/components/schemas/addon_app"
        state:
          type: string
          enum:
          - pending
          - attached
          - detached
      required:
      - id
      - name
      - app
      - state
    addon_with_attachments:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
          description: Globally unique addon name
        human_name:
          type: string
          nullable: true
          description: User-provided display name for the addon
        description:
          type: string
          nullable: true
          description: User-provided description of the addon
        addon_service:
          "$ref": "#/components/schemas/addon_service"
        plan:
          "$ref": "#/components/schemas/addon_plan"
        app:
          "$ref": "#/components/schemas/addon_app"
        state:
          type: string
          enum:
          - pending
          - requested
          - provisioned
          - deprovisioning
          - deprovisioned
        config_vars:
          type: array
          items:
            type: string
        billed_price:
          "$ref": "#/components/schemas/addon_billed_price"
        web_url:
          type: string
          nullable: true
        attachments:
          type: array
          items:
            "$ref": "#/components/schemas/addon_info_attachment"
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
      required:
      - id
      - addon_service
      - plan
      - app
      - state
    collaborator_user:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
      required:
      - id
      - email
    collaborator_app:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - id
      - name
    collaborator:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
        user:
          "$ref": "#/components/schemas/collaborator_user"
        app:
          "$ref": "#/components/schemas/collaborator_app"
        role:
          type: string
      required:
      - id
      - user
      - app
      - role
    process:
      type: object
      properties:
        index:
          type: integer
        status:
          type: string
        started_at:
          type: string
          format: date_time
        restarts:
          type: integer
          nullable: true
        restarted_at:
          type: string
          format: date_time
          nullable: true
      required:
      - index
      - status
      - started_at
    dyno:
      type: object
      properties:
        type:
          type: string
        quantity:
          type: integer
        size:
          type: string
        display:
          type: string
        processes:
          type: array
          items:
            "$ref": "#/components/schemas/process"
      required:
      - type
      - quantity
      - size
      - display
      - processes
    buildpack_installation:
      type: object
      properties:
        ordinal:
          type: integer
          description: Determines the order in which the buildpacks will execute
        buildpack:
          type: object
          required:
          - url
          - name
          properties:
            url:
              type: string
              description: Buildpack registry name or URL
            name:
              type: string
              description: Buildpack registry name or URL
      required:
      - ordinal
      - buildpack
    build:
      type: object
      properties:
        id:
          type: string
          format: uuid
        app:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        user:
          type: object
          properties:
            id:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
        source_blob:
          type: object
          description: Where the source came from.
          properties:
            url:
              type: string
              nullable: true
            version:
              type: string
              nullable: true
            version_description:
              type: string
              nullable: true
            checksum:
              type: string
              nullable: true
        buildpacks:
          type: array
          nullable: true
          items:
            type: object
            properties:
              url:
                type: string
              name:
                type: string
                nullable: true
        stack:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - pending
          - packing
          - uploading
          - succeeded
          - failed
          description: Build state, reported verbatim rather than collapsed.
        output_stream_url:
          type: string
          nullable: true
        slug:
          type: object
          nullable: true
          properties:
            id:
              type: string
              nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - app
      - stack
      - state
      - created_at
      - updated_at
    deployment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        app:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        build:
          type: object
          nullable: true
          properties:
            id:
              type: string
          description: The build this deployment released, when it came from one.
        user:
          type: object
          properties:
            id:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
        version:
          type: integer
          nullable: true
        description:
          type: string
          nullable: true
        state:
          type: string
          enum:
          - pending
          - releasing
          - failed
          - succeeded
          - deploying
          - deployed
          - testing
          - tested
          - vibing
          - vibed
          description: Deployment state, reported verbatim rather than collapsed.
        current:
          type: boolean
          description: Whether this is the app's current deployment.
        failover:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - app
      - state
      - current
      - created_at
      - updated_at
    domain:
      type: object
      properties:
        id:
          type: string
          format: uuid
        hostname:
          type: string
          description: The domain name
        kind:
          type: string
          enum:
          - platform
          - custom
          description: Type of domain
        cname:
          type: string
          nullable: true
          description: CNAME target for DNS configuration
        status:
          type: string
          enum:
          - pending
          - deployed
          - succeeded
          - failed
          description: Domain status
        acm_status:
          type: string
          nullable: true
          description: SSL certificate status
        acm_status_reason:
          type: string
          nullable: true
          description: Reason for certificate status
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
        sni_endpoint:
          type: object
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
          description: SSL endpoint information
        app:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
          required:
          - id
          - name
          description: Associated app
      required:
      - id
      - hostname
      - kind
      - status
      - app
    exec_output:
      type: object
      properties:
        output:
          type: string
        stderr:
          type: string
        exit_code:
          type: integer
      required:
      - output
      - stderr
      - exit_code
    formation_update:
      type: object
      properties:
        type:
          type: string
          description: Process type (e.g. web, worker)
        quantity:
          type: integer
          nullable: true
        size:
          type: string
          nullable: true
      required:
      - type
    namespace:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        team:
          type: object
          title: NamespaceTeam
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        description:
          type: string
          nullable: true
        state:
          type: string
        region:
          type: string
        actor:
          type: object
          title: NamespaceActor
          properties:
            id:
              type: string
              format: uuid
            email:
              type: string
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
      required: []
    pipeline:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        team:
          type: object
          title: PipelineTeam
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        environments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              kind:
                type: string
                enum:
                - ra
                - ci
                - ai
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
      required:
      - id
      - name
      - team
    pipeline_promotion:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          - succeeded
          - failed
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
        pipeline:
          type: object
          title: PromotionPipeline
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        source:
          type: object
          title: PromotionSource
          properties:
            app:
              type: object
              title: PromotionSourceApp
              properties:
                id:
                  type: string
                  format: uuid
                name:
                  type: string
      required:
      - id
      - status
      - pipeline
      - source
    promotion_target:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          - promoting
          - succeeded
          - failed
        error_message:
          type: string
          nullable: true
        app:
          type: object
          title: PromotionTargetApp
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        pipeline_promotion:
          type: object
          title: PromotionTargetPromotion
          properties:
            id:
              type: string
              format: uuid
      required:
      - id
      - status
      - app
      - pipeline_promotion
    team:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        personal:
          type: boolean
        created_at:
          type: string
          format: date_time
        updated_at:
          type: string
          format: date_time
      required: []
  securitySchemes:
    bearer:
      type: http
      name: Bearer
      in: header
      description: Your Bearer token
      scheme: bearer
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: Your API key
    oauth2:
      type: oauth2
      description: Authorization-code clients support PKCE. Public clients should
        pass code_challenge/code_challenge_method=S256 to /oauth/authorize and code_verifier
        to /oauth/token; existing confidential clients may continue using client_secret.
      flows:
        authorizationCode:
          authorizationUrl: "/oauth/authorize"
          tokenUrl: "/oauth/token"
          scopes:
            read: {}
            write: {}
    open_id_connect:
      type: openIdConnect
      openIdConnectUrl: "/.well-known/openid-configuration"
      description: OpenID Connect