Roles - Docs - Braintrust

GET

/v1/role

List roles

List out all roles. The roles are sorted by creation date, with the most recently-created roles 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

`role_name`string

Name of the role to search for

`org_name`string

Filter search results to within a particular organization

Status code	Description
`200`	Returns a list of role 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/role?limit=0&starting_after=497f6eca-6276-4993-bfeb-53cbbbba6f08&ending_before=497f6eca-6276-4993-bfeb-53cbbbba6f08&ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&role_name=string&org_name=string"

{
  "objects": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "created": "2019-08-24T14:15:22Z",
      "name": "string",
      "description": "string",
      "deleted_at": "2019-08-24T14:15:22Z",
      "member_permissions": [
        {
          "permission": "create",
          "restrict_object_type": "organization"
        }
      ],
      "member_roles": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ]
    }
  ]
}

POST

/v1/role

Create role

Create a new role. If there is an existing role with the same name as the one specified in the request, will return the existing role 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 role object

`name`
Required
string

Name of the role

`description`string | null

Textual description of the role

`member_permissions`array<object> | null

(permission, restrict_object_type) tuples which belong to this role

`member_roles`array<string> | null

Ids of the roles this role inherits from

An inheriting role has all the permissions contained in its member roles, as well as all of their inherited permissions

`org_name`string | null

For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the role belongs in.

Status code	Description
`200`	Returns the new role 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/role" \
  -d '{
  "name": "string",
  "description": "string",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "org_name": "string"
}'

A role is a collection of permissions which can be granted as part of an ACL

Roles can consist of individual permissions, as well as a set of roles they inherit from

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "created": "2019-08-24T14:15:22Z",
  "name": "string",
  "description": "string",
  "deleted_at": "2019-08-24T14:15:22Z",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

PUT

/v1/role

Create or replace role

Create or replace role. If there is an existing role with the same name as the one specified in the request, will replace the existing role with the provided fields

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

`name`
Required
string

Name of the role

`description`string | null

Textual description of the role

`member_permissions`array<object> | null

(permission, restrict_object_type) tuples which belong to this role

`member_roles`array<string> | null

Ids of the roles this role inherits from

An inheriting role has all the permissions contained in its member roles, as well as all of their inherited permissions

`org_name`string | null

For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the role belongs in.

Status code	Description
`200`	Returns the new role 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 PUT "https://api.braintrust.dev/v1/role" \
  -d '{
  "name": "string",
  "description": "string",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "org_name": "string"
}'

A role is a collection of permissions which can be granted as part of an ACL

Roles can consist of individual permissions, as well as a set of roles they inherit from

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "created": "2019-08-24T14:15:22Z",
  "name": "string",
  "description": "string",
  "deleted_at": "2019-08-24T14:15:22Z",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

GET

/v1/role/{role_id}

Get role

Get a role 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

`role_id`
Required
string

Role id

Format: "uuid"

Status code	Description
`200`	Returns the role 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/role/497f6eca-6276-4993-bfeb-53cbbbba6f08"

A role is a collection of permissions which can be granted as part of an ACL

Roles can consist of individual permissions, as well as a set of roles they inherit from

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "created": "2019-08-24T14:15:22Z",
  "name": "string",
  "description": "string",
  "deleted_at": "2019-08-24T14:15:22Z",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

PATCH

/v1/role/{role_id}

Partially update role

Partially update a role object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null.

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)

Fields to update

`description`string | null

Textual description of the role

`name`string | null

Name of the role

`add_member_permissions`array<object> | null

A list of permissions to add to the role

`remove_member_permissions`array<object> | null

A list of permissions to remove from the role

`add_member_roles`array<string> | null

A list of role IDs to add to the role's inheriting-from set

`remove_member_roles`array<string> | null

A list of role IDs to remove from the role's inheriting-from set

Path Parameters

`role_id`
Required
string

Role id

Format: "uuid"

Status code	Description
`200`	Returns the role 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 PATCH "https://api.braintrust.dev/v1/role/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -d '{
  "description": "string",
  "name": "string",
  "add_member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "remove_member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "add_member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "remove_member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}'

A role is a collection of permissions which can be granted as part of an ACL

Roles can consist of individual permissions, as well as a set of roles they inherit from

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "created": "2019-08-24T14:15:22Z",
  "name": "string",
  "description": "string",
  "deleted_at": "2019-08-24T14:15:22Z",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

DELETE

/v1/role/{role_id}

Delete role

Delete a role 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

`role_id`
Required
string

Role id

Format: "uuid"

Status code	Description
`200`	Returns the deleted role 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/role/497f6eca-6276-4993-bfeb-53cbbbba6f08"

A role is a collection of permissions which can be granted as part of an ACL

Roles can consist of individual permissions, as well as a set of roles they inherit from

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "created": "2019-08-24T14:15:22Z",
  "name": "string",
  "description": "string",
  "deleted_at": "2019-08-24T14:15:22Z",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Query

AuthorizationRequiredBearer <token>

limitinteger

starting_afterstring

ending_beforestring

idsAny properties in string, array<string>

Object 1

role_namestring

org_namestring

Response

Typescript

Body

AuthorizationRequiredBearer <token>

nameRequiredstring

descriptionstring | null

member_permissionsarray<object> | null

Object 1

member_rolesarray<string> | null

org_namestring | null

Response

Typescript

Body

AuthorizationRequiredBearer <token>

nameRequiredstring

descriptionstring | null

member_permissionsarray<object> | null

Object 1

member_rolesarray<string> | null

org_namestring | null

Response

Typescript

Path

AuthorizationRequiredBearer <token>

role_idRequiredstring

Response

Typescript

Path

Body

AuthorizationRequiredBearer <token>

descriptionstring | null

namestring | null

add_member_permissionsarray<object> | null

Object 1

remove_member_permissionsarray<object> | null

Object 1

add_member_rolesarray<string> | null

remove_member_rolesarray<string> | null

role_idRequiredstring

Response

Typescript

Path

AuthorizationRequiredBearer <token>

role_idRequiredstring

Response

Typescript

On this page

`Authorization`
Required
Bearer <token>

`limit`integer

`starting_after`string

`ending_before`string

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

`role_name`string

`org_name`string

`Authorization`
Required
Bearer <token>

`name`
Required
string

`description`string | null

`member_permissions`array<object> | null

`member_roles`array<string> | null

`org_name`string | null

`Authorization`
Required
Bearer <token>

`name`
Required
string

`description`string | null

`member_permissions`array<object> | null

`member_roles`array<string> | null

`org_name`string | null

`Authorization`
Required
Bearer <token>

`role_id`
Required
string

`Authorization`
Required
Bearer <token>

`description`string | null

`name`string | null

`add_member_permissions`array<object> | null

`remove_member_permissions`array<object> | null

`add_member_roles`array<string> | null

`remove_member_roles`array<string> | null

`role_id`
Required
string

`Authorization`
Required
Bearer <token>

`role_id`
Required
string