Reference/API/Acls

List acls

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

GET
/v1/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

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"
object_id
Required
string

The id of the object the ACL applies to

Format: "uuid"
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" \
  -H "Authorization: Bearer <token>"

Returns a list of acl objects

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

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

POST
/v1/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

application/jsonOptional

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"
object_id
Required
string

The id of the object the ACL applies to

Format: "uuid"
user_idstring

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

Format: "uuid"
group_idstring

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

Format: "uuid"
permissionstring

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

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

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

Format: "uuid"
curl -X POST "https://api.braintrust.dev/v1/acl" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -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"
  }'

Returns the new acl object

{
  "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 single acl

Delete a single acl

DELETE
/v1/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

application/jsonOptional

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"
object_id
Required
string

The id of the object the ACL applies to

Format: "uuid"
user_idstring

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

Format: "uuid"
group_idstring

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

Format: "uuid"
permissionstring

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

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

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

Format: "uuid"
curl -X DELETE "https://api.braintrust.dev/v1/acl" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -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"
  }'

Returns the deleted acl object

{
  "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 acl

Get an acl object by its id

GET
/v1/acl/{acl_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"
curl -X GET "https://api.braintrust.dev/v1/acl/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>"

Returns the acl object

{
  "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 acl

Delete an acl object by its id

DELETE
/v1/acl/{acl_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"
curl -X DELETE "https://api.braintrust.dev/v1/acl/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>"

Returns the deleted acl object

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

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.

POST
/v1/acl/batch_update

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

application/jsonOptional

Acls to add/remove.

add_aclsarray<object>

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_aclsarray<object>

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.

curl -X POST "https://api.braintrust.dev/v1/acl/batch_update" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -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"
      }
    ]
  }'

A success status

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

On this page