> ## Documentation Index > Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create or replace project_automation > Create or replace project_automation. If there is an existing project_automation with the same name as the one specified in the request, will replace the existing project_automation with the provided fields ## OpenAPI ````yaml /openapi.yaml put /v1/project_automation 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/project_automation: put: tags: - ProjectAutomations summary: Create or replace project_automation description: >- Create or replace project_automation. If there is an existing project_automation with the same name as the one specified in the request, will replace the existing project_automation with the provided fields operationId: putProjectAutomation requestBody: description: Any desired information about the new project_automation object required: false content: application/json: schema: $ref: '#/components/schemas/CreateProjectAutomation' responses: '200': description: Returns the new project_automation object content: application/json: schema: $ref: '#/components/schemas/ProjectAutomation' '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 security: - bearerAuth: [] - {} components: schemas: CreateProjectAutomation: type: object properties: project_id: type: string format: uuid description: >- Unique identifier for the project that the project automation belongs under name: type: string description: Name of the project automation description: type: string nullable: true description: Textual description of the project automation config: oneOf: - type: object properties: event_type: type: string enum: - logs description: The type of automation. btql_filter: type: string description: BTQL filter to identify rows for the automation rule interval_seconds: type: number minimum: 1 maximum: 2592000 description: >- Perform the triggered action at most once in this interval of seconds action: oneOf: - type: object properties: type: type: string enum: - webhook description: The type of action to take url: type: string description: The webhook URL to send the request to required: - type - url - type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert required: - type - workspace_id - channel description: The action to take when the automation rule is triggered required: - event_type - btql_filter - interval_seconds - action - type: object properties: event_type: type: string enum: - btql_export description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' export_definition: oneOf: - type: object properties: type: type: string enum: - log_traces required: - type - type: object properties: type: type: string enum: - log_spans required: - type - type: object properties: type: type: string enum: - btql_query btql_query: type: string description: The BTQL query to export required: - type - btql_query description: The definition of what to export scope: anyOf: - $ref: '#/components/schemas/SpanScope' - $ref: '#/components/schemas/TraceScope' - $ref: '#/components/schemas/GroupScope' - type: 'null' description: >- Execution scope for export automation. Defaults to span-level execution. export_path: type: string description: >- The path to export the results to. It should include the storage protocol and prefix, e.g. s3://bucket-name/path/to/export format: type: string enum: - jsonl - parquet description: The format to export the results in interval_seconds: type: number minimum: 1 maximum: 2592000 description: >- Perform the triggered action at most once in this interval of seconds credentials: oneOf: - type: object properties: type: type: string enum: - aws_iam role_arn: type: string description: The ARN of the IAM role to use external_id: type: string description: >- The automation-specific external id component (auto-generated by default) required: - type - role_arn - external_id - type: object properties: type: type: string enum: - gcp_service_account service_account_email: type: string description: The GCP service account email to impersonate required: - type - service_account_email batch_size: type: number nullable: true description: The number of rows to export in each batch required: - event_type - export_definition - export_path - format - interval_seconds - credentials - type: object properties: event_type: type: string enum: - retention description: The type of automation. object_type: $ref: '#/components/schemas/RetentionObjectType' retention_days: type: number minimum: 0 description: The number of days to retain the object required: - event_type - object_type - retention_days - type: object properties: event_type: type: string enum: - environment_update description: The type of automation. environment_filter: type: array items: type: string description: Optional list of environment slugs to filter by action: oneOf: - type: object properties: type: type: string enum: - webhook description: The type of action to take url: type: string description: The webhook URL to send the request to required: - type - url - type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert required: - type - workspace_id - channel description: The action to take when the automation rule is triggered required: - event_type - action - $ref: '#/components/schemas/TopicAutomationConfig' description: The configuration for the automation rule required: - project_id - name - config ProjectAutomation: type: object properties: id: type: string format: uuid description: Unique identifier for the project automation project_id: type: string format: uuid description: >- Unique identifier for the project that the project automation belongs under user_id: type: string nullable: true format: uuid description: Identifies the user who created the project automation created: type: string nullable: true format: date-time description: Date of project automation creation name: type: string description: Name of the project automation description: type: string nullable: true description: Textual description of the project automation config: oneOf: - type: object properties: event_type: type: string enum: - logs description: The type of automation. btql_filter: type: string description: BTQL filter to identify rows for the automation rule interval_seconds: type: number minimum: 1 maximum: 2592000 description: >- Perform the triggered action at most once in this interval of seconds action: oneOf: - type: object properties: type: type: string enum: - webhook description: The type of action to take url: type: string description: The webhook URL to send the request to required: - type - url - type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert required: - type - workspace_id - channel description: The action to take when the automation rule is triggered required: - event_type - btql_filter - interval_seconds - action - type: object properties: event_type: type: string enum: - btql_export description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' export_definition: oneOf: - type: object properties: type: type: string enum: - log_traces required: - type - type: object properties: type: type: string enum: - log_spans required: - type - type: object properties: type: type: string enum: - btql_query btql_query: type: string description: The BTQL query to export required: - type - btql_query description: The definition of what to export scope: anyOf: - $ref: '#/components/schemas/SpanScope' - $ref: '#/components/schemas/TraceScope' - $ref: '#/components/schemas/GroupScope' - type: 'null' description: >- Execution scope for export automation. Defaults to span-level execution. export_path: type: string description: >- The path to export the results to. It should include the storage protocol and prefix, e.g. s3://bucket-name/path/to/export format: type: string enum: - jsonl - parquet description: The format to export the results in interval_seconds: type: number minimum: 1 maximum: 2592000 description: >- Perform the triggered action at most once in this interval of seconds credentials: oneOf: - type: object properties: type: type: string enum: - aws_iam role_arn: type: string description: The ARN of the IAM role to use external_id: type: string description: >- The automation-specific external id component (auto-generated by default) required: - type - role_arn - external_id - type: object properties: type: type: string enum: - gcp_service_account service_account_email: type: string description: The GCP service account email to impersonate required: - type - service_account_email batch_size: type: number nullable: true description: The number of rows to export in each batch required: - event_type - export_definition - export_path - format - interval_seconds - credentials - type: object properties: event_type: type: string enum: - retention description: The type of automation. object_type: $ref: '#/components/schemas/RetentionObjectType' retention_days: type: number minimum: 0 description: The number of days to retain the object required: - event_type - object_type - retention_days - type: object properties: event_type: type: string enum: - environment_update description: The type of automation. environment_filter: type: array items: type: string description: Optional list of environment slugs to filter by action: oneOf: - type: object properties: type: type: string enum: - webhook description: The type of action to take url: type: string description: The webhook URL to send the request to required: - type - url - type: object properties: type: type: string enum: - slack description: The type of action to take workspace_id: type: string description: The Slack workspace ID to post to channel: type: string description: The Slack channel ID to post to message_template: type: string description: Custom message template for the alert required: - type - workspace_id - channel description: The action to take when the automation rule is triggered required: - event_type - action - $ref: '#/components/schemas/TopicAutomationConfig' description: The configuration for the automation rule required: - id - project_id - name - config AutomationStatus: type: string enum: - active - paused description: Whether the automation is active or paused. SpanScope: type: object properties: type: type: string enum: - span required: - type description: Process individual spans TraceScope: type: object properties: type: type: string enum: - trace idle_seconds: type: number description: >- Consider trace complete after this many seconds of inactivity (default: 30) required: - type description: Process entire traces (all spans sharing the same root_span_id) GroupScope: type: object properties: type: type: string enum: - group group_by: type: string description: Field path to group by, e.g. metadata.session_id interval_seconds: type: number minimum: 1 description: Maximum time range to include when constructing a group max_traces: type: integer minimum: 1 maximum: 64 description: >- Maximum number of traces to include when constructing a group (default/max: 64) placement: type: string enum: - first - each description: Which trace or traces to write grouped scorer results to idle_seconds: type: number description: 'Optional: trigger after this many seconds of inactivity' required: - type - group_by - placement description: Process spans/traces grouped by a field (e.g., session_id) RetentionObjectType: type: string enum: - project_logs - experiment - dataset description: The object type that the retention policy applies to TopicAutomationConfig: type: object properties: event_type: type: string enum: - topic description: The type of automation. status: $ref: '#/components/schemas/AutomationStatus' sampling_rate: type: number minimum: 0 maximum: 1 description: The sampling rate for topic automation facet_model: $ref: '#/components/schemas/TopicAutomationFacetModel' facet_functions: type: array items: allOf: - $ref: '#/components/schemas/SavedFunctionId' - anyOf: - type: object properties: type: type: string enum: - function id: type: string version: type: string description: The version of the function required: - type - id title: function - type: object properties: type: type: string enum: - global name: type: string function_type: $ref: '#/components/schemas/FunctionTypeEnum' required: - type - name title: global description: Facet functions used by the topic automation topic_map_functions: type: array items: $ref: '#/components/schemas/TopicMapFunctionAutomation' description: Topic map functions with optional per-topic-map filters scope: anyOf: - $ref: '#/components/schemas/SpanScope' - $ref: '#/components/schemas/TraceScope' - $ref: '#/components/schemas/GroupScope' - type: 'null' description: >- Execution scope for topic automation. Defaults to span-level execution. data_scope: $ref: '#/components/schemas/TopicAutomationDataScope' btql_filter: type: string nullable: true description: Optional BTQL filter applied before topic automation. rerun_seconds: type: number nullable: true minimum: 600 description: How often to recompute topic maps relabel_overlap_seconds: type: number nullable: true minimum: 60 description: >- How much recent history to relabel after a new topic map version becomes active backfill_time_range: anyOf: - type: string - type: object properties: from: type: string to: type: string required: - from - to - type: 'null' description: Topic window used for classification coverage and initial backfill. required: - event_type - sampling_rate - facet_functions - topic_map_functions TopicAutomationFacetModel: type: string nullable: true enum: - brain-facet-latest - brain-facet-1 - brain-facet-2 - null description: Optional facet model override for topic automation SavedFunctionId: anyOf: - type: object properties: type: type: string enum: - function id: type: string version: type: string description: The version of the function required: - type - id title: function - type: object properties: type: type: string enum: - global name: type: string function_type: $ref: '#/components/schemas/FunctionTypeEnum' required: - type - name title: global - type: 'null' description: Optional function identifier that produced the classification FunctionTypeEnum: type: string enum: - llm - scorer - task - tool - custom_view - preprocessor - facet - classifier - tag - parameters - sandbox - null default: scorer description: The type of global function. Defaults to 'scorer'. TopicMapFunctionAutomation: type: object properties: function: allOf: - $ref: '#/components/schemas/SavedFunctionId' - anyOf: - type: object properties: type: type: string enum: - function id: type: string version: type: string description: The version of the function required: - type - id title: function - type: object properties: type: type: string enum: - global name: type: string function_type: $ref: '#/components/schemas/FunctionTypeEnum' required: - type - name title: global description: Topic map function btql_filter: type: string nullable: true description: >- Per-topic-map BTQL filter. For trace scope, a topic map runs when max(filter) over the trace is truthy. For span scope, it runs when the current span matches. required: - function TopicAutomationDataScope: anyOf: - type: object properties: type: type: string enum: - project_logs required: - type - type: object properties: type: type: string enum: - project_experiments required: - type - type: object properties: type: type: string enum: - experiment experiment_id: type: string required: - type - experiment_id - type: 'null' description: Optional data scope for topic automation. 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). ````