Acls

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

`ids`string

Format: "uuid"

`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"
}

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"
}

AuthorizationRequiredBearer <token>

limitinteger

starting_afterstring

ending_beforestring

idsAny properties in string, array<string>

idsstring

Properties (option 2)

object_typeRequiredstring

object_idRequiredstring

Authorization

Query

Response

Typescript

AuthorizationRequiredBearer <token>

object_typeRequiredstring

object_idRequiredstring

user_idstring | null

group_idstring | null

permissionstring | null

restrict_object_typestring | null

role_idstring | null

Authorization

Body

Response

Typescript

AuthorizationRequiredBearer <token>

acl_idRequiredstring

Authorization

Path

Response

Typescript

AuthorizationRequiredBearer <token>

acl_idRequiredstring

Authorization

Path

Response

Typescript

`Authorization`
Required
Bearer <token>

`limit`integer

`starting_after`string

`ending_before`string

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

`ids`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>

`acl_id`
Required
string

`Authorization`
Required
Bearer <token>

`acl_id`
Required
string