openapi: 3.1.1
info:
  version: 1.0.0
  title: Braintrust Acls Environments API
  description: 'API specification for the backend data server. The API is hosted globally at

    https://api.braintrust.dev or in your own environment.


    You can access the OpenAPI spec for this API at https://github.com/braintrustdata/braintrust-openapi.'
  license:
    name: Apache 2.0
servers:
- url: https://api.braintrust.dev
security:
- bearerAuth: []
- {}
tags:
- name: Environments
paths:
  /environment:
    get:
      operationId: listEnvironments
      summary: List environments
      description: List out all environments. The environments are sorted by creation date, with the most recently-created environments first.
      tags:
      - Environments
      security:
      - bearerAuth: []
      - {}
      parameters:
      - schema:
          anyOf:
          - type: string
            format: uuid
          - type: array
            items:
              type: string
              format: uuid
            minItems: 1
          description: Filter by environment IDs. Supports a single ID or multiple values.
        required: false
        name: ids
        in: query
      - schema:
          type: string
        required: false
        name: name
        in: query
      - $ref: '#/components/parameters/OrgName'
      responses:
        '200':
          description: List of environments
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Environment'
                required:
                - objects
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
    post:
      operationId: createEnvironment
      summary: Create environment
      description: Create a new environment
      tags:
      - Environments
      security:
      - bearerAuth: []
      - {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvironment'
      responses:
        '200':
          description: Created environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
  /environment/{environment_id}:
    get:
      operationId: getEnvironment
      summary: Get environment
      tags:
      - Environments
      security:
      - bearerAuth: []
      - {}
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: environment_id
        in: path
      responses:
        '200':
          description: Environment object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
    patch:
      operationId: updateEnvironment
      summary: Partially update environment
      tags:
      - Environments
      security:
      - bearerAuth: []
      - {}
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: environment_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchEnvironment'
      responses:
        '200':
          description: Updated environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
    delete:
      operationId: deleteEnvironment
      summary: Delete environment
      tags:
      - Environments
      security:
      - bearerAuth: []
      - {}
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: environment_id
        in: path
      responses:
        '200':
          description: Deleted environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: The request was unacceptable, often due to missing a required parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '429':
          description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                nullable: true
components:
  schemas:
    CreateEnvironment:
      type: object
      properties:
        name:
          type: string
          description: Name of the environment
        slug:
          type: string
          description: A url-friendly, unique identifier for the environment within an organization
        description:
          type: string
          nullable: true
          description: Textual description of the environment
        org_name:
          type: string
          nullable: true
          description: For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the environment belongs in.
      required:
      - name
      - slug
    OrgName:
      type: string
      description: Filter search results to within a particular organization
    Environment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the environment
        org_id:
          type: string
          format: uuid
          description: Unique identifier for the organization that the environment belongs under
        name:
          type: string
          description: Name of the environment
        slug:
          type: string
          description: A url-friendly, unique identifier for the environment within an organization
        description:
          type: string
          nullable: true
          description: Textual description of the environment
        created:
          type: string
          nullable: true
          format: date-time
          description: Date of environment creation
        deleted_at:
          type: string
          nullable: true
          format: date-time
          description: Date of environment deletion, or null if the environment is still active
      required:
      - id
      - org_id
      - name
      - slug
    PatchEnvironment:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Name of the environment
        slug:
          type: string
          nullable: true
          description: A url-friendly, unique identifier for the environment within an organization
        description:
          type: string
          nullable: true
          description: Textual description of the environment
  parameters:
    OrgName:
      schema:
        $ref: '#/components/schemas/OrgName'
      required: false
      description: Filter search results to within a particular organization
      name: org_name
      in: query
      allowReserved: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or JWT
      description: 'Most Braintrust endpoints are authenticated by providing your API key as a header `Authorization: Bearer [api_key]` to your HTTP request. You can create an API key in the Braintrust [organization settings page](https://www.braintrustdata.com/app/settings?subroute=api-keys).'