Reference/API/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

/v1/acl

The Authorization access token

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

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

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

/v1/acl

The Authorization access token

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

Each permission permits a certain type of operation on an object in the system

Permissions can be assigned to to objects on an individual basis, or grouped into roles

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

restrict_object_typestring | null

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"

role_idstring | null

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

Delete single acl

Delete a single acl

/v1/acl

The Authorization access token

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

Each permission permits a certain type of operation on an object in the system

Permissions can be assigned to to objects on an individual basis, or grouped into roles

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

restrict_object_typestring | null

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"

role_idstring | null

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
/v1/acl/{acl_id}

Get acl

Get an acl object by its id

/v1/acl/{acl_id}

The Authorization access token

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
/v1/acl/{acl_id}

Delete acl

Delete an acl object by its id

/v1/acl/{acl_id}

The Authorization access token

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

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.

/v1/acl/batch-update

The Authorization access token

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

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