Stainless Builds API

openapi: 3.2.0
info:
  title: Stainless Builds API
  version: 1.0.0
  description: 'Operations tagged Builds across 2 of this provider''s published API definitions: stainless.yml, stainless-sdk-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: v1
tags:
- name: Builds
paths:
  /v0/builds:
    get:
      summary: List project builds
      description: 'List user-triggered builds for a given project.


        An optional revision can be specified to filter by config commit SHA, or

        hashes of file contents.'
      parameters:
      - in: query
        name: project
        schema:
          type: string
          description: Project name
        required: true
      - in: query
        name: branch
        schema:
          type: string
          description: Branch name
      - in: query
        name: revision
        schema:
          anyOf:
          - type: string
            description: A config commit SHA used for the build
          - type: object
            propertyNames:
              type: string
              description: File path
            additionalProperties:
              type: object
              properties:
                hash:
                  type: string
                  description: File content hash
              required:
              - hash
            description: Hash of the files used for the build
          default: {}
      - in: query
        name: cursor
        schema:
          type: string
          description: Pagination cursor from a previous response.
      - in: query
        name: limit
        schema:
          type: number
          exclusiveMinimum: 0
          maximum: 100
          default: 10
          description: 'Maximum number of builds to return, defaults to 10 (maximum: 100).'
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Build'
                  has_more:
                    type: boolean
                  next_cursor:
                    type: string
                required:
                - data
                - has_more
      tags:
      - Builds
      operationId: getV0Builds
      x-operation-id-source: derived
    post:
      summary: Create build
      description: 'Create a build, on top of a project branch, against a given input revision.


        The project branch will be modified so that its latest set of config files

        points to the one specified by the input revision.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  type: string
                  description: Project name
                branch:
                  type: string
                  description: 'The project branch to use for the build. If not specified, the

                    branch is inferred from the `revision`, and will 400 when that

                    is not possible.'
                revision:
                  anyOf:
                  - type: object
                    properties:
                      merge:
                        type: string
                        description: A merge command in the format "base..head"
                      files:
                        type: object
                        propertyNames:
                          type: string
                          description: File path
                        additionalProperties:
                          $ref: '#/components/schemas/FileInput'
                        description: File contents to commit directly
                    required:
                    - merge
                    - files
                    description: 'A merge command combined with explicit file contents. The files are committed

                      to the merge target (`base`) without performing an auto-merge.'
                  - type: string
                    description: A branch name, commit SHA, or merge command in the format "base..head"
                  - type: object
                    propertyNames:
                      type: string
                      description: File path
                    additionalProperties:
                      $ref: '#/components/schemas/FileInput'
                    description: File contents to commit directly
                  description: 'Specifies what to build: a branch name, commit SHA, merge command

                    ("base..head"), or file contents.'
                targets:
                  type: array
                  items:
                    $ref: '#/components/schemas/Target'
                  description: 'Optional list of SDK targets to build. If not specified, all configured

                    targets will be built.'
                commit_message:
                  type: string
                  description: Optional commit message to use when creating a new commit.
                target_commit_messages:
                  type: object
                  properties:
                    node:
                      type: string
                    typescript:
                      type: string
                    python:
                      type: string
                    go:
                      type: string
                    java:
                      type: string
                    kotlin:
                      type: string
                    ruby:
                      type: string
                    terraform:
                      type: string
                    cli:
                      type: string
                    php:
                      type: string
                    csharp:
                      type: string
                    sql:
                      type: string
                    openapi:
                      type: string
                  additionalProperties: false
                  description: 'Optional commit messages to use for each SDK when making a new commit.

                    SDKs not represented in this object will fallback to the optional

                    `commit_message` parameter, or will fallback further to the default

                    commit message.'
                allow_empty:
                  type: boolean
                  default: false
                  description: Whether to allow empty commits (no changes). Defaults to false.
                enable_ai_commit_message:
                  type: boolean
                  description: 'Whether to generate AI-powered commit messages for the build.

                    Cannot be combined with `commit_message` or `target_commit_messages`.'
              required:
              - project
              - revision
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
      tags:
      - Builds
      operationId: postV0Builds
      x-operation-id-source: derived
    servers:
    - url: v1
  /v0/builds/{buildId}:
    get:
      summary: Retrieve build
      description: Retrieve a build by its ID.
      parameters:
      - in: path
        name: buildId
        schema:
          type: string
          description: Build ID
        required: true
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
      tags:
      - Builds
      operationId: getV0BuildsByBuildId
      x-operation-id-source: derived
    servers:
    - url: v1
  /v0/builds/compare:
    post:
      summary: Creates two comparable builds
      description: 'Create two builds whose outputs can be directly compared with each other.


        Created builds _modify_ their project branches so that their latest sets of

        config files point to the ones specified by the input revision.


        This endpoint is useful because a build has more inputs than the set of

        config files it uses, so comparing two builds directly may return spurious

        differences. Builds made via this endpoint are guaranteed to have

        differences arising from the set of config files, and any custom code.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  type: string
                  description: Project name
                base:
                  type: object
                  properties:
                    revision:
                      anyOf:
                      - type: object
                        properties:
                          merge:
                            type: string
                            description: A merge command in the format "base..head"
                          files:
                            type: object
                            propertyNames:
                              type: string
                              description: File path
                            additionalProperties:
                              $ref: '#/components/schemas/FileInput'
                            description: File contents to commit directly
                        required:
                        - merge
                        - files
                        description: 'A merge command combined with explicit file contents. The files are committed

                          to the merge target (`base`) without performing an auto-merge.'
                      - type: string
                        description: A branch name, commit SHA, or merge command in the format "base..head"
                      - type: object
                        propertyNames:
                          type: string
                          description: File path
                        additionalProperties:
                          $ref: '#/components/schemas/FileInput'
                        description: File contents to commit directly
                      description: 'Specifies what to build: a branch name, a commit SHA, or file contents.'
                    branch:
                      type: string
                      description: 'Branch to use. When using a branch name as revision, this must match or be

                        omitted.'
                    commit_message:
                      type: string
                      description: Optional commit message to use when creating a new commit.
                  required:
                  - revision
                  - branch
                  description: Parameters for the base build
                head:
                  type: object
                  properties:
                    revision:
                      anyOf:
                      - type: object
                        properties:
                          merge:
                            type: string
                            description: A merge command in the format "base..head"
                          files:
                            type: object
                            propertyNames:
                              type: string
                              description: File path
                            additionalProperties:
                              $ref: '#/components/schemas/FileInput'
                            description: File contents to commit directly
                        required:
                        - merge
                        - files
                        description: 'A merge command combined with explicit file contents. The files are committed

                          to the merge target (`base`) without performing an auto-merge.'
                      - type: string
                        description: A branch name, commit SHA, or merge command in the format "base..head"
                      - type: object
                        propertyNames:
                          type: string
                          description: File path
                        additionalProperties:
                          $ref: '#/components/schemas/FileInput'
                        description: File contents to commit directly
                      description: 'Specifies what to build: a branch name, a commit SHA, or file contents.'
                    branch:
                      type: string
                      description: 'Branch to use. When using a branch name as revision, this must match or be

                        omitted.'
                    commit_message:
                      type: string
                      description: Optional commit message to use when creating a new commit.
                  required:
                  - revision
                  - branch
                  description: Parameters for the head build
                targets:
                  type: array
                  items:
                    $ref: '#/components/schemas/Target'
                  description: 'Optional list of SDK targets to build. If not specified, all configured

                    targets will be built.'
              required:
              - project
              - base
              - head
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                properties:
                  base:
                    $ref: '#/components/schemas/Build'
                  head:
                    $ref: '#/components/schemas/Build'
                required:
                - base
                - head
      tags:
      - Builds
      operationId: postV0BuildsCompare
      x-operation-id-source: derived
    servers:
    - url: v1
  /v0/builds/{buildId}/diagnostics:
    get:
      summary: Get diagnostics for a build
      description: 'Get the list of diagnostics for a given build.


        If no language targets are specified, diagnostics for all languages are returned.'
      parameters:
      - in: path
        name: buildId
        schema:
          type: string
          description: Build ID
        required: true
      - in: query
        name: targets
        schema:
          type: string
          description: Optional comma-delimited list of language targets to filter diagnostics by
      - in: query
        name: severity
        schema:
          type: string
          enum:
          - fatal
          - error
          - warning
          - note
          description: Includes the given severity and above (fatal > error > warning > note).
      - in: query
        name: cursor
        schema:
          type: string
          description: Pagination cursor from a previous response
      - in: query
        name: limit
        schema:
          type: number
          exclusiveMinimum: 0
          maximum: 100
          default: 100
          description: 'Maximum number of diagnostics to return, defaults to 100 (maximum: 100)'
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BuildDiagnostic'
                  has_more:
                    type: boolean
                  next_cursor:
                    type: string
                required:
                - data
                - has_more
      tags:
      - Builds
      operationId: getV0BuildsByBuildIdDiagnostics
      x-operation-id-source: derived
    servers:
    - url: v1
components:
  schemas:
    CheckStep:
      oneOf:
      - type: object
        properties:
          status:
            type: string
            enum:
            - not_started
        required:
        - status
      - type: object
        properties:
          status:
            type: string
            enum:
            - waiting
          url:
            type:
            - string
            - 'null'
        required:
        - status
        - url
      - type: object
        properties:
          status:
            type: string
            enum:
            - queued
          url:
            type:
            - string
            - 'null'
        required:
        - status
        - url
      - type: object
        properties:
          status:
            type: string
            enum:
            - in_progress
          url:
            type:
            - string
            - 'null'
        required:
        - status
        - url
      - type: object
        properties:
          status:
            type: string
            enum:
            - completed
          completed:
            type: object
            properties:
              conclusion:
                $ref: '#/components/schemas/CheckConclusion'
              url:
                type:
                - string
                - 'null'
            required:
            - conclusion
            - url
            description: deprecated
          conclusion:
            $ref: '#/components/schemas/CheckConclusion'
          url:
            type:
            - string
            - 'null'
        required:
        - status
        - completed
        - conclusion
        - url
      discriminator:
        propertyName: status
    Build:
      type: object
      properties:
        object:
          type: string
          enum:
          - build
        id:
          type: string
          description: Build ID
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        project:
          type: string
        org:
          type: string
        config_commit:
          type: string
        documented_spec:
          oneOf:
          - type: object
            properties:
              type:
                type: string
                enum:
                - content
              content:
                type: string
            required:
            - type
            - content
          - type: object
            properties:
              type:
                type: string
                enum:
                - url
              url:
                type: string
              expires:
                type: string
                format: date-time
            required:
            - type
            - url
            - expires
          - type: 'null'
        targets:
          type: object
          properties:
            node:
              $ref: '#/components/schemas/BuildTarget'
            typescript:
              $ref: '#/components/schemas/BuildTarget'
            python:
              $ref: '#/components/schemas/BuildTarget'
            go:
              $ref: '#/components/schemas/BuildTarget'
            java:
              $ref: '#/components/schemas/BuildTarget'
            kotlin:
              $ref: '#/components/schemas/BuildTarget'
            ruby:
              $ref: '#/components/schemas/BuildTarget'
            terraform:
              $ref: '#/components/schemas/BuildTarget'
            cli:
              $ref: '#/components/schemas/BuildTarget'
            php:
              $ref: '#/components/schemas/BuildTarget'
            csharp:
              $ref: '#/components/schemas/BuildTarget'
            sql:
              $ref: '#/components/schemas/BuildTarget'
            openapi:
              $ref: '#/components/schemas/BuildTarget'
          additionalProperties: false
      required:
      - object
      - id
      - updated_at
      - created_at
      - project
      - org
      - config_commit
      - documented_spec
      - targets
    CheckConclusion:
      type: string
      enum:
      - success
      - failure
      - skipped
      - cancelled
      - action_required
      - neutral
      - timed_out
    BuildDiagnostic:
      type: object
      properties:
        code:
          type: string
          description: The kind of diagnostic.
        level:
          type: string
          enum:
          - fatal
          - error
          - warning
          - note
          description: The severity of the diagnostic.
        ignored:
          type: boolean
          description: Whether the diagnostic is ignored in the Stainless config.
        message:
          type: string
          description: A description of the diagnostic.
        more:
          oneOf:
          - $ref: '#/components/schemas/BuildDiagnosticMore'
          - type: 'null'
        oas_ref:
          type: string
          description: A JSON pointer to a relevant field in the OpenAPI spec.
        config_ref:
          type: string
          description: A JSON pointer to a relevant field in the Stainless config.
      required:
      - code
      - level
      - ignored
      - message
      - more
    BuildTarget:
      type: object
      properties:
        object:
          type: string
          enum:
          - build_target
        status:
          type: string
          enum:
          - not_started
          - codegen
          - postgen
          - completed
        commit:
          $ref: '#/components/schemas/CommitStep'
        lint:
          $ref: '#/components/schemas/CheckStep'
        test:
          $ref: '#/components/schemas/CheckStep'
        build:
          $ref: '#/components/schemas/CheckStep'
        install_url:
          type:
          - string
          - 'null'
      required:
      - object
      - status
      - commit
      - install_url
    BuildDiagnosticMore:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - markdown
          markdown:
            type: string
        required:
        - type
        - markdown
      - type: object
        properties:
          type:
            type: string
            enum:
            - raw
          raw:
            type: string
        required:
        - type
        - raw
      discriminator:
        propertyName: type
    Commit:
      type: object
      properties:
        sha:
          type: string
        repo:
          type: object
          properties:
            host:
              type: string
            owner:
              type: string
            name:
              type: string
            branch:
              type: string
          required:
          - host
          - owner
          - name
          - branch
        tree_oid:
          type:
          - string
          - 'null'
        stats:
          type:
          - object
          - 'null'
          properties:
            additions:
              type: integer
              minimum: 0
            deletions:
              type: integer
              minimum: 0
            total:
              type: integer
              minimum: 0
          required:
          - additions
          - deletions
          - total
      required:
      - sha
      - repo
      - tree_oid
      - stats
    Target:
      type: string
      enum:
      - node
      - typescript
      - python
      - go
      - java
      - kotlin
      - ruby
      - terraform
      - cli
      - php
      - csharp
      - sql
      - openapi
    CommitConclusion:
      type: string
      enum:
      - error
      - warning
      - note
      - success
      - merge_conflict
      - upstream_merge_conflict
      - fatal
      - payment_required
      - cancelled
      - timed_out
      - noop
      - version_bump
    FileInput:
      anyOf:
      - type: object
        properties:
          content:
            type: string
            description: File content
        required:
        - content
      - type: object
        properties:
          url:
            type: string
            description: URL to fetch file content from
        required:
        - url
    CommitStep:
      oneOf:
      - type: object
        properties:
          status:
            type: string
            enum:
            - not_started
        required:
        - status
      - type: object
        properties:
          status:
            type: string
            enum:
            - waiting
        required:
        - status
      - type: object
        properties:
          status:
            type: string
            enum:
            - queued
        required:
        - status
      - type: object
        properties:
          status:
            type: string
            enum:
            - in_progress
        required:
        - status
      - type: object
        properties:
          status:
            type: string
            enum:
            - completed
          completed:
            type: object
            properties:
              conclusion:
                $ref: '#/components/schemas/CommitConclusion'
              merge_conflict_pr:
                type:
                - object
                - 'null'
                properties:
                  number:
                    type: number
                  repo:
                    type: object
                    properties:
                      host:
                        type: string
                      owner:
                        type: string
                      name:
                        type: string
                    required:
                    - host
                    - owner
                    - name
                required:
                - number
                - repo
              commit:
                oneOf:
                - $ref: '#/components/schemas/Commit'
                - type: 'null'
              completed_at:
                type: string
                format: date-time
            required:
            - conclusion
            - merge_conflict_pr
            - commit
            - completed_at
            description: deprecated
          conclusion:
            $ref: '#/components/schemas/CommitConclusion'
          merge_conflict_pr:
            type:
            - object
            - 'null'
            properties:
              number:
                type: number
              repo:
                type: object
                properties:
                  host:
                    type: string
                  owner:
                    type: string
                  name:
                    type: string
                required:
                - host
                - owner
                - name
            required:
            - number
            - repo
          commit:
            oneOf:
            - $ref: '#/components/schemas/Commit'
            - type: 'null'
          completed_at:
            type: string
            format: date-time
        required:
        - status
        - completed
        - conclusion
        - merge_conflict_pr
        - commit
        - completed_at
      discriminator:
        propertyName: status
x-refined-from:
- stainless.yml
- stainless-sdk-openapi.yml