openapi: 3.1.1
info:
  version: 1.0.0
  title: Braintrust Acls AiSecrets 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: AiSecrets
paths:
  /v1/ai_secret:
    post:
      tags:
      - AiSecrets
      security:
      - bearerAuth: []
      - {}
      operationId: postAiSecret
      description: Create a new ai_secret. If there is an existing ai_secret with the same name as the one specified in the request, will return the existing ai_secret unmodified
      summary: Create ai_secret
      requestBody:
        description: Any desired information about the new ai_secret object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAISecret'
      responses:
        '200':
          description: Returns the new ai_secret object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AISecret'
        '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
    put:
      tags:
      - AiSecrets
      security:
      - bearerAuth: []
      - {}
      operationId: putAiSecret
      description: Create or replace ai_secret. If there is an existing ai_secret with the same name as the one specified in the request, will replace the existing ai_secret with the provided fields
      summary: Create or replace ai_secret
      requestBody:
        description: Any desired information about the new ai_secret object
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAISecret'
      responses:
        '200':
          description: Returns the new ai_secret object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AISecret'
        '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: deleteAiSecret
      tags:
      - AiSecrets
      description: Delete a single ai_secret
      summary: Delete single ai_secret
      security:
      - bearerAuth: []
      - {}
      requestBody:
        description: Parameters which uniquely specify the ai_secret to delete
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAISecret'
      responses:
        '200':
          description: Returns the deleted ai_secret object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AISecret'
        '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
    get:
      operationId: getAiSecret
      tags:
      - AiSecrets
      description: List out all ai_secrets. The ai_secrets are sorted by creation date, with the most recently-created ai_secrets coming first
      summary: List ai_secrets
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AppLimitParam'
      - $ref: '#/components/parameters/StartingAfter'
      - $ref: '#/components/parameters/EndingBefore'
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/AiSecretName'
      - $ref: '#/components/parameters/OrgName'
      - $ref: '#/components/parameters/AISecretType'
      responses:
        '200':
          description: Returns a list of ai_secret objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/AISecret'
                    description: A list of ai_secret objects
                required:
                - objects
                additionalProperties: false
        '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
  /v1/ai_secret/{ai_secret_id}:
    get:
      operationId: getAiSecretId
      tags:
      - AiSecrets
      description: Get an ai_secret object by its id
      summary: Get ai_secret
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AiSecretIdParam'
      responses:
        '200':
          description: Returns the ai_secret object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AISecret'
        '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: patchAiSecretId
      tags:
      - AiSecrets
      description: Partially update an ai_secret object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null.
      summary: Partially update ai_secret
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AiSecretIdParam'
      requestBody:
        description: Fields to update
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAISecret'
      responses:
        '200':
          description: Returns the ai_secret object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AISecret'
        '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: deleteAiSecretId
      tags:
      - AiSecrets
      description: Delete an ai_secret object by its id
      summary: Delete ai_secret
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/AiSecretIdParam'
      responses:
        '200':
          description: Returns the deleted ai_secret object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AISecret'
        '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:
  parameters:
    EndingBefore:
      schema:
        $ref: '#/components/schemas/EndingBefore'
      required: false
      description: 'Pagination cursor id.


        For example, if the initial item in the last page you fetched had an id of `foo`, pass `ending_before=foo` to fetch the previous page. Note: you may only pass one of `starting_after` and `ending_before`'
      name: ending_before
      in: query
    StartingAfter:
      schema:
        $ref: '#/components/schemas/StartingAfter'
      required: false
      description: 'Pagination cursor id.


        For example, if the final item in the last page you fetched had an id of `foo`, pass `starting_after=foo` to fetch the next page. Note: you may only pass one of `starting_after` and `ending_before`'
      name: starting_after
      in: query
    AppLimitParam:
      schema:
        $ref: '#/components/schemas/AppLimitParam'
      required: false
      description: Limit the number of objects to return
      name: limit
      in: query
    AiSecretIdParam:
      schema:
        $ref: '#/components/schemas/AiSecretIdParam'
      required: true
      description: AiSecret id
      name: ai_secret_id
      in: path
    Ids:
      schema:
        $ref: '#/components/schemas/Ids'
      required: false
      description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
      name: ids
      in: query
    AiSecretName:
      schema:
        $ref: '#/components/schemas/AiSecretName'
      required: false
      description: Name of the ai_secret to search for
      name: ai_secret_name
      in: query
      allowReserved: true
    OrgName:
      schema:
        $ref: '#/components/schemas/OrgName'
      required: false
      description: Filter search results to within a particular organization
      name: org_name
      in: query
      allowReserved: true
    AISecretType:
      schema:
        $ref: '#/components/schemas/AISecretType'
      required: false
      name: ai_secret_type
      in: query
  schemas:
    AiSecretIdParam:
      type: string
      format: uuid
      description: AiSecret id
    OrgName:
      type: string
      description: Filter search results to within a particular organization
    AppLimitParam:
      type: integer
      nullable: true
      minimum: 0
      description: Limit the number of objects to return
    Ids:
      anyOf:
      - type: string
        format: uuid
      - type: array
        items:
          type: string
          format: uuid
      description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
    AISecretType:
      anyOf:
      - type: string
      - type: array
        items:
          type: string
    AISecret:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the AI secret
        created:
          type: string
          nullable: true
          format: date-time
          description: Date of AI secret creation
        updated_at:
          type: string
          nullable: true
          format: date-time
          description: Date of last AI secret update
        secret_updated_at:
          type: string
          nullable: true
          format: date-time
          description: Date of last update to the encrypted secret value itself
        org_id:
          type: string
          format: uuid
          description: Unique identifier for the organization
        name:
          type: string
          description: Name of the AI secret
        type:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
        secret_updated_by_user_id:
          type: string
          nullable: true
          format: uuid
          description: User id of the last update to the encrypted secret value
        preview_secret:
          type: string
          nullable: true
      required:
      - id
      - org_id
      - name
    PatchAISecret:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Name of the AI secret
        type:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
        secret:
          type: string
          nullable: true
    DeleteAISecret:
      type: object
      properties:
        name:
          type: string
          description: Name of the AI secret
        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 AI Secret belongs in.
      required:
      - name
    StartingAfter:
      type: string
      format: uuid
      description: 'Pagination cursor id.


        For example, if the final item in the last page you fetched had an id of `foo`, pass `starting_after=foo` to fetch the next page. Note: you may only pass one of `starting_after` and `ending_before`'
    CreateAISecret:
      type: object
      properties:
        name:
          type: string
          description: Name of the AI secret
        type:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
        secret:
          type: string
          nullable: true
          description: Secret value. If omitted in a PUT request, the existing secret value will be left intact, not replaced with null.
        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 AI Secret belongs in.
      required:
      - name
    EndingBefore:
      type: string
      format: uuid
      description: 'Pagination cursor id.


        For example, if the initial item in the last page you fetched had an id of `foo`, pass `ending_before=foo` to fetch the previous page. Note: you may only pass one of `starting_after` and `ending_before`'
    AiSecretName:
      type: string
      description: Name of the ai_secret to search for
  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).'