> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create AI secret

> 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



## OpenAPI

````yaml /openapi.yaml post /v1/ai_secret
openapi: 3.1.1
info:
  version: 1.0.0
  title: Braintrust 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: []
  - {}
paths:
  /v1/ai_secret:
    post:
      tags:
        - AiSecrets
      summary: Create AI secret
      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
      operationId: postAiSecret
      requestBody:
        description: Any desired information about the new AI secret object
        required: true
        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: {}
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
        '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: {}
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
      security:
        - bearerAuth: []
        - {}
components:
  schemas:
    CreateAISecret:
      type: object
      properties:
        name:
          type: string
          description: Name of the AI secret
        type:
          type:
            - string
            - 'null'
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: {}
        secret:
          type:
            - string
            - 'null'
          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
            - 'null'
          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
    AISecret:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the AI secret
        created:
          type:
            - string
            - 'null'
          format: date-time
          description: Date of AI secret creation
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Date of last AI secret update
        secret_updated_at:
          type:
            - string
            - 'null'
          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
            - 'null'
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: {}
        secret_updated_by_user_id:
          type:
            - string
            - 'null'
          format: uuid
          description: User id of the last update to the encrypted secret value
        preview_secret:
          type:
            - string
            - 'null'
      required:
        - id
        - org_id
        - name
  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).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.