Braintrust ProjectAutomations API
The ProjectAutomations API from Braintrust — 2 operation(s) for projectautomations.
OpenAPI Specification
openapi: 3.1.1
info:
version: 1.0.0
title: Braintrust Acls ProjectAutomations 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: ProjectAutomations
paths:
/v1/project_automation:
post:
tags:
- ProjectAutomations
security:
- bearerAuth: []
- {}
operationId: postProjectAutomation
description: Create a new project_automation. If there is an existing project_automation with the same name as the one specified in the request, will return the existing project_automation unmodified
summary: Create project_automation
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
put:
tags:
- ProjectAutomations
security:
- bearerAuth: []
- {}
operationId: putProjectAutomation
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
summary: Create or replace project_automation
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
get:
operationId: getProjectAutomation
tags:
- ProjectAutomations
description: List out all project_automations. The project_automations are sorted by creation date, with the most recently-created project_automations coming first
summary: List project_automations
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/AppLimitParam'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- $ref: '#/components/parameters/Ids'
- $ref: '#/components/parameters/ProjectAutomationName'
- $ref: '#/components/parameters/OrgName'
responses:
'200':
description: Returns a list of project_automation objects
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/ProjectAutomation'
description: A list of project_automation 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/project_automation/{project_automation_id}:
get:
operationId: getProjectAutomationId
tags:
- ProjectAutomations
description: Get a project_automation object by its id
summary: Get project_automation
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/ProjectAutomationIdParam'
responses:
'200':
description: Returns the 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
patch:
operationId: patchProjectAutomationId
tags:
- ProjectAutomations
description: Partially update a project_automation 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 project_automation
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/ProjectAutomationIdParam'
requestBody:
description: Fields to update
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/PatchProjectAutomation'
responses:
'200':
description: Returns the 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
delete:
operationId: deleteProjectAutomationId
tags:
- ProjectAutomations
description: Delete a project_automation object by its id
summary: Delete project_automation
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/ProjectAutomationIdParam'
responses:
'200':
description: Returns the deleted 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
components:
schemas:
SpanScope:
type: object
properties:
type:
type: string
enum:
- span
required:
- type
description: Process individual spans
PatchProjectAutomation:
type: object
properties:
name:
type: string
nullable: true
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.
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'
- nullable: true
description: The configuration for the automation rule
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
OrgName:
type: string
description: Filter search results to within a particular organization
TopicAutomationFacetModel:
type: string
nullable: true
enum:
- brain-facet-latest
- brain-facet-1
- brain-facet-2
- null
description: Optional facet model override for topic automation
GroupScope:
type: object
properties:
type:
type: string
enum:
- group
group_by:
type: string
description: Field path to group by, e.g. metadata.session_id
idle_seconds:
type: number
description: 'Optional: trigger after this many seconds of inactivity'
required:
- type
- group_by
description: Process spans/traces grouped by a field (e.g., session_id)
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)
AppLimitParam:
type: integer
nullable: true
minimum: 0
description: Limit the number of objects to return
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.
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
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/braintrust/refs/heads/main/openapi/braintrust-projectautomations-api-openapi.yml