ReferenceAPI

GET/v1/acl

List acls

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

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

Query Parameters

limitinteger

Limit the number of objects to return

Minimum: 0

starting_afterstring

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_beforestring

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"

idsAny 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 codeDescription
200Returns a list of acl objects
400The request was unacceptable, often due to missing a required parameter
401No valid API key provided
403The API key doesn’t have permissions to perform the request
429Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500Something went wrong on Braintrust's end. (These are rare.)
curl -X GET "https://api.braintrustdata.com/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_idstring | null

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

Format: "uuid"

group_idstring | null

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

Format: "uuid"

permissionstring | null

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

Value in: "create" | "read" | "update" | "delete" | "create_acls" | "read_acls" | "update_acls" | "delete_acls" | null

restrict_object_typestring | 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_idstring | null

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

Format: "uuid"
Status codeDescription
200Returns the new acl object
400The request was unacceptable, often due to missing a required parameter
401No valid API key provided
403The API key doesn’t have permissions to perform the request
429Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500Something went wrong on Braintrust's end. (These are rare.)
curl -X POST "https://api.braintrustdata.com/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 codeDescription
200Returns the acl object
400The request was unacceptable, often due to missing a required parameter
401No valid API key provided
403The API key doesn’t have permissions to perform the request
429Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500Something went wrong on Braintrust's end. (These are rare.)
curl -X GET "https://api.braintrustdata.com/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 codeDescription
200Returns the deleted acl object
400The request was unacceptable, often due to missing a required parameter
401No valid API key provided
403The API key doesn’t have permissions to perform the request
429Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500Something went wrong on Braintrust's end. (These are rare.)
curl -X DELETE "https://api.braintrustdata.com/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"
}

Previous

API

Next

ApiKeys

On this page