Acls - Docs - Braintrust

GET

/v1/acl

List acls

List out all acls. The acls are sorted by creation date, with the most recently-created acls coming first

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.

In: header

Query Parameters

`limit`integer

Limit the number of objects to return

Minimum: 0

`starting_after`string

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

Format: "uuid"

`ending_before`string

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

Format: "uuid"

`ids`Any properties in string, array<string>

Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times

`object_type`
Required
string

The object type that the ACL applies to

Value in:

"organization" | "project" | "experiment" | "dataset" | "prompt" | "prompt_session" | "group" | "role" | "org_member" | "project_log" | "org_project" | null

`object_id`
Required
string

The id of the object the ACL applies to

Format: "uuid"

Status code	Description
`200`	Returns a list of acl objects
`400`	The request was unacceptable, often due to missing a required parameter
`401`	No valid API key provided
`403`	The API key doesn’t have permissions to perform the request
`429`	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
`500`	Something went wrong on Braintrust's end. (These are rare.)

curl -X GET "https://api.braintrust.dev/v1/acl?limit=0&starting_after=497f6eca-6276-4993-bfeb-53cbbbba6f08&ending_before=497f6eca-6276-4993-bfeb-53cbbbba6f08&ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&object_type=organization&object_id=497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "objects": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "object_type": "organization",
      "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "permission": "create",
      "restrict_object_type": "organization",
      "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
      "_object_org_id": "4d272dc1-1d6f-4a99-8c76-7bcbfc11ce4e",
      "created": "2019-08-24T14:15:22Z"
    }
  ]
}

POST

/v1/acl

Create acl

Create a new acl. If there is an existing acl with the same contents as the one specified in the request, will return the existing acl unmodified

Authorization

`Authorization`
Required
Bearer <token>

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.

In: header

Request Body (Optional)

Any desired information about the new acl object

`object_type`
Required
string

The object type that the ACL applies to

Value in:

"organization" | "project" | "experiment" | "dataset" | "prompt" | "prompt_session" | "group" | "role" | "org_member" | "project_log" | "org_project" | null

`object_id`
Required
string

The id of the object the ACL applies to

Format: "uuid"

`user_id`string | null

Id of the user the ACL applies to. Exactly one of user_id and group_id will be provided

Format: "uuid"

`group_id`string | null

Id of the group the ACL applies to. Exactly one of user_id and group_id will be provided

Format: "uuid"

`permission`string | null

Permission the ACL grants. Exactly one of permission and role_id will be provided

`restrict_object_type`string | null

When setting a permission directly, optionally restricts the permission grant to just the specified object type. Cannot be set alongside a role_id.

Value in:

"organization" | "project" | "experiment" | "dataset" | "prompt" | "prompt_session" | "group" | "role" | "org_member" | "project_log" | "org_project" | null

`role_id`string | null

Id of the role the ACL grants. Exactly one of permission and role_id will be provided

Format: "uuid"

Status code	Description
`200`	Returns the new acl object
`400`	The request was unacceptable, often due to missing a required parameter
`401`	No valid API key provided
`403`	The API key doesn’t have permissions to perform the request
`429`	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
`500`	Something went wrong on Braintrust's end. (These are rare.)

curl -X POST "https://api.braintrust.dev/v1/acl" \
  -d '{
  "object_type": "organization",
  "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "permission": "create",
  "restrict_object_type": "organization",
  "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9"
}'

An ACL grants a certain permission or role to a certain user or group on an object.

ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project.

To restrict a grant to a particular sub-object, you may specify restrict_object_type in the ACL, as part of a direct permission grant or as part of a role.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "object_type": "organization",
  "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "permission": "create",
  "restrict_object_type": "organization",
  "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
  "_object_org_id": "4d272dc1-1d6f-4a99-8c76-7bcbfc11ce4e",
  "created": "2019-08-24T14:15:22Z"
}

DELETE

/v1/acl

Delete single acl

Delete a single acl

Authorization

`Authorization`
Required
Bearer <token>

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.

In: header

Request Body (Optional)

Parameters which uniquely specify the acl to delete

`object_type`
Required
string

The object type that the ACL applies to

Value in:

"organization" | "project" | "experiment" | "dataset" | "prompt" | "prompt_session" | "group" | "role" | "org_member" | "project_log" | "org_project" | null

`object_id`
Required
string

The id of the object the ACL applies to

Format: "uuid"

`user_id`string | null

Id of the user the ACL applies to. Exactly one of user_id and group_id will be provided

Format: "uuid"

`group_id`string | null

Id of the group the ACL applies to. Exactly one of user_id and group_id will be provided

Format: "uuid"

`permission`string | null

Permission the ACL grants. Exactly one of permission and role_id will be provided

`restrict_object_type`string | null

When setting a permission directly, optionally restricts the permission grant to just the specified object type. Cannot be set alongside a role_id.

Value in:

"organization" | "project" | "experiment" | "dataset" | "prompt" | "prompt_session" | "group" | "role" | "org_member" | "project_log" | "org_project" | null

`role_id`string | null

Id of the role the ACL grants. Exactly one of permission and role_id will be provided

Format: "uuid"

Status code	Description
`200`	Returns the deleted acl object
`400`	The request was unacceptable, often due to missing a required parameter
`401`	No valid API key provided
`403`	The API key doesn’t have permissions to perform the request
`429`	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
`500`	Something went wrong on Braintrust's end. (These are rare.)

curl -X DELETE "https://api.braintrust.dev/v1/acl" \
  -d '{
  "object_type": "organization",
  "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "permission": "create",
  "restrict_object_type": "organization",
  "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9"
}'

An ACL grants a certain permission or role to a certain user or group on an object.

ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project.

To restrict a grant to a particular sub-object, you may specify restrict_object_type in the ACL, as part of a direct permission grant or as part of a role.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "object_type": "organization",
  "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "permission": "create",
  "restrict_object_type": "organization",
  "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
  "_object_org_id": "4d272dc1-1d6f-4a99-8c76-7bcbfc11ce4e",
  "created": "2019-08-24T14:15:22Z"
}

GET

/v1/acl/{acl_id}

Get acl

Get an acl object by its id

Authorization

`Authorization`
Required
Bearer <token>

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.

In: header

Path Parameters

`acl_id`
Required
string

Acl id

Format: "uuid"

Status code	Description
`200`	Returns the acl object
`400`	The request was unacceptable, often due to missing a required parameter
`401`	No valid API key provided
`403`	The API key doesn’t have permissions to perform the request
`429`	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
`500`	Something went wrong on Braintrust's end. (These are rare.)

curl -X GET "https://api.braintrust.dev/v1/acl/497f6eca-6276-4993-bfeb-53cbbbba6f08"

An ACL grants a certain permission or role to a certain user or group on an object.

ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project.

To restrict a grant to a particular sub-object, you may specify restrict_object_type in the ACL, as part of a direct permission grant or as part of a role.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "object_type": "organization",
  "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "permission": "create",
  "restrict_object_type": "organization",
  "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
  "_object_org_id": "4d272dc1-1d6f-4a99-8c76-7bcbfc11ce4e",
  "created": "2019-08-24T14:15:22Z"
}

DELETE

/v1/acl/{acl_id}

Delete acl

Delete an acl object by its id

Authorization

`Authorization`
Required
Bearer <token>

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.

In: header

Path Parameters

`acl_id`
Required
string

Acl id

Format: "uuid"

Status code	Description
`200`	Returns the deleted acl object
`400`	The request was unacceptable, often due to missing a required parameter
`401`	No valid API key provided
`403`	The API key doesn’t have permissions to perform the request
`429`	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
`500`	Something went wrong on Braintrust's end. (These are rare.)

curl -X DELETE "https://api.braintrust.dev/v1/acl/497f6eca-6276-4993-bfeb-53cbbbba6f08"

An ACL grants a certain permission or role to a certain user or group on an object.

ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project.

To restrict a grant to a particular sub-object, you may specify restrict_object_type in the ACL, as part of a direct permission grant or as part of a role.

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "object_type": "organization",
  "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "permission": "create",
  "restrict_object_type": "organization",
  "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
  "_object_org_id": "4d272dc1-1d6f-4a99-8c76-7bcbfc11ce4e",
  "created": "2019-08-24T14:15:22Z"
}

POST

/v1/acl/batch-update

Batch update acls

Batch update acls. This operation is idempotent, so adding acls which already exist will have no effect, and removing acls which do not exist will have no effect.

Authorization

`Authorization`
Required
Bearer <token>

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.

In: header

Request Body (Optional)

Acls to add/remove.

`add_acls`array<object> | null

An ACL grants a certain permission or role to a certain user or group on an object.

ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project.

To restrict a grant to a particular sub-object, you may specify restrict_object_type in the ACL, as part of a direct permission grant or as part of a role.

`remove_acls`array<object> | null

An ACL grants a certain permission or role to a certain user or group on an object.

ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project.

To restrict a grant to a particular sub-object, you may specify restrict_object_type in the ACL, as part of a direct permission grant or as part of a role.

Status code	Description
`200`	A success status
`400`	The request was unacceptable, often due to missing a required parameter
`401`	No valid API key provided
`403`	The API key doesn’t have permissions to perform the request
`429`	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
`500`	Something went wrong on Braintrust's end. (These are rare.)

curl -X POST "https://api.braintrust.dev/v1/acl/batch-update" \
  -d '{
  "add_acls": [
    {
      "object_type": "organization",
      "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "permission": "create",
      "restrict_object_type": "organization",
      "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9"
    }
  ],
  "remove_acls": [
    {
      "object_type": "organization",
      "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "permission": "create",
      "restrict_object_type": "organization",
      "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9"
    }
  ]
}'

{
  "added_acls": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "object_type": "organization",
      "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "permission": "create",
      "restrict_object_type": "organization",
      "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
      "_object_org_id": "4d272dc1-1d6f-4a99-8c76-7bcbfc11ce4e",
      "created": "2019-08-24T14:15:22Z"
    }
  ],
  "removed_acls": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "object_type": "organization",
      "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "permission": "create",
      "restrict_object_type": "organization",
      "role_id": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
      "_object_org_id": "4d272dc1-1d6f-4a99-8c76-7bcbfc11ce4e",
      "created": "2019-08-24T14:15:22Z"
    }
  ]
}

Query

AuthorizationRequiredBearer <token>

limitinteger

starting_afterstring

ending_beforestring

idsAny properties in string, array<string>

Object 1

object_typeRequiredstring

object_idRequiredstring

Response

Typescript

Body

AuthorizationRequiredBearer <token>

object_typeRequiredstring

object_idRequiredstring

user_idstring | null

group_idstring | null

permissionstring | null

restrict_object_typestring | null

role_idstring | null

Response

Typescript

Body

AuthorizationRequiredBearer <token>

object_typeRequiredstring

object_idRequiredstring

user_idstring | null

group_idstring | null

permissionstring | null

restrict_object_typestring | null

role_idstring | null

Response

Typescript

Path

AuthorizationRequiredBearer <token>

acl_idRequiredstring

Response

Typescript

Path

AuthorizationRequiredBearer <token>

acl_idRequiredstring

Response

Typescript

Body

AuthorizationRequiredBearer <token>

add_aclsarray<object> | null

Object 1

remove_aclsarray<object> | null

Object 1

Response

Typescript

On this page

Query

Body

Body

Path

Path

Body

`Authorization`
Required
Bearer <token>

`limit`integer

`starting_after`string

`ending_before`string

`ids`Any properties in string, array<string>

`object_type`
Required
string

`object_id`
Required
string

`Authorization`
Required
Bearer <token>

`object_type`
Required
string

`object_id`
Required
string

`user_id`string | null

`group_id`string | null

`permission`string | null

`restrict_object_type`string | null

`role_id`string | null

`Authorization`
Required
Bearer <token>

`object_type`
Required
string

`object_id`
Required
string

`user_id`string | null

`group_id`string | null

`permission`string | null

`restrict_object_type`string | null

`role_id`string | null

`Authorization`
Required
Bearer <token>

`acl_id`
Required
string

`Authorization`
Required
Bearer <token>

`acl_id`
Required
string

`Authorization`
Required
Bearer <token>

`add_acls`array<object> | null

`remove_acls`array<object> | null