> ## 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 custom column > Create a new custom column. If there is an existing custom column with the same name in the same scope, will return the existing custom column unmodified. Requires update permission on the scoping object. Custom columns are scoped to a specific table by the combination of `object_type`, `object_id`, `subtype`, and `variant`. Use the same scope when creating and listing columns. Use these combinations to display columns in the corresponding UI table: | Page | `object_type` | `object_id` | `subtype` | `variant` | | --- | --- | --- | --- | --- | | Dataset | `dataset` | Dataset ID | `""` | `dataset` | | Project logs | `project` | Project ID | `project_log` | `project_log` | | Experiment details | `project` | Project ID | `experiment` | `experiment` | | Experiments list | `project` | Project ID | `experiment` | `experiment_list` | Experiment span columns apply across experiments in the project. ## OpenAPI ````yaml /openapi.yaml post /v1/column 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/column: post: tags: - CustomColumns summary: Create custom column description: >- Create a new custom column. If there is an existing custom column with the same name in the same scope, will return the existing custom column unmodified. Requires update permission on the scoping object. Custom columns are scoped to a specific table by the combination of `object_type`, `object_id`, `subtype`, and `variant`. Use the same scope when creating and listing columns. Use these combinations to display columns in the corresponding UI table: | Page | `object_type` | `object_id` | `subtype` | `variant` | | --- | --- | --- | --- | --- | | Dataset | `dataset` | Dataset ID | `""` | `dataset` | | Project logs | `project` | Project ID | `project_log` | `project_log` | | Experiment details | `project` | Project ID | `experiment` | `experiment` | | Experiments list | `project` | Project ID | `experiment` | `experiment_list` | Experiment span columns apply across experiments in the project. operationId: postCustomColumn requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomColumn' responses: '200': description: Returns the new custom column object content: application/json: schema: $ref: '#/components/schemas/CustomColumn' '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: CreateCustomColumn: type: object properties: object_type: allOf: - $ref: '#/components/schemas/AclObjectType' - description: >- The type of the object the custom column is scoped to, usually `project` object_id: type: string format: uuid description: >- The ID of the scoping object. Use the project ID for project logs, experiment spans, and the experiments list. Use the dataset ID for dataset rows subtype: anyOf: - $ref: '#/components/schemas/AclObjectType' - type: string enum: - '' description: >- The child object type the custom column applies to, such as `experiment` or `project_log`. Use an empty string when the column applies directly to the scoping object, such as a dataset variant: allOf: - $ref: '#/components/schemas/CustomColumnVariant' - description: >- The table variant the custom column applies to. If omitted, defaults to the nonempty `subtype`, or otherwise to `object_type`. Set `experiment_list` explicitly to target the experiments list instead of experiment details. Use the same scope when creating and listing columns name: type: string description: The name of the custom column expr: type: string description: The expression used to extract the value for the custom column required: - object_type - object_id - subtype - name - expr CustomColumn: type: object properties: id: type: string format: uuid description: Unique identifier for the custom columns object_type: $ref: '#/components/schemas/AclObjectType' object_id: type: string format: uuid description: The id of the object the custom column is scoped for subtype: anyOf: - $ref: '#/components/schemas/AclObjectType' - type: string enum: - '' description: The object type that the ACL applies to variant: $ref: '#/components/schemas/CustomColumnVariant' name: type: string description: The name of the custom column expr: type: string description: The expression used to extract the value for the custom column created: type: - string - 'null' format: date-time description: Date of custom columns creation required: - id - object_type - object_id - subtype - variant - name - expr AclObjectType: type: string enum: - organization - project - experiment - dataset - prompt - prompt_session - group - role - org_member - project_log - org_project - org_audit_logs - project_group - project_group_projects - ai_secret - org_ai_secret - org_account description: The object type that the ACL applies to CustomColumnVariant: type: string enum: - project - experiment - dataset - project_log - experiment_list description: The table variant that the custom column applies to 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.