Jump toRoles

Roles

Built-in and custom roles, and who holds them where.

get/v1/role_assignments

List assignments

Any key of this organization

Sorts by created_at (default, newest first), role and expires_at; facets count role, principal_kind and created_by (who assigned it, usr_… or sa_…), which also filters, as does the created time range.

Query parameters

principal_idstring
workspace_idstring
rolestring[]
principal_kindstring[]
created_bystring[]
limitinteger
Rows per page, 1 to 200. Omitted: every row.
at least 1at most 200
cursorstring
qstring
Search: rows whose name (or the list's other searchable text) contains this, any case.
at most 200 characters
orderstring
Sort field; a leading - sorts down. Each list names the fields it sorts by.
at most 64 charactersmatches ^-?[a-z_]+$
includestring[]
total_count (counted up to 10,000) and facets (a count per filter value).
One oftotal_countfacets
created_afterstring
Only rows created at or after this time (RFC 3339).
date-time
created_beforestring
Only rows created at or before this time (RFC 3339).
date-time
updated_afterstring
Only rows last changed at or after this time (RFC 3339).
date-time
updated_beforestring
Only rows last changed at or before this time (RFC 3339).
date-time

Response200

objectstring
list
dataRoleAssignment[]
9 fields
- idstring
- objectstring
  role_assignment
- created_atstring
- expires_atstring or null
- principal_idstring
- principal_kindstring
  One ofuserservice_accountgroup
- rolestring
- workspace_idstring or null
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/role_assignments?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "ra_01jc9f6ea6gbyszz4awcw2mg13",
      "object": "role_assignment",
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "expires_at": "2026-11-10T09:30:00.000Z",
      "principal_id": "principal id",
      "principal_kind": "user",
      "role": "role",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

post/v1/role_assignments

Assign role

Needs role.manage

Request bodyAssignmentCreate

principal_idstringRequired
principal_kindstringRequired
One ofuserservice_accountgroup
rolestringRequired
expires_atstring or null
date-time
workspace_idstring or null

Response201

idstring
objectstring
role_assignment
created_atstring
expires_atstring or null
principal_idstring
principal_kindstring
One ofuserservice_accountgroup
rolestring
workspace_idstring or null
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/role_assignments" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2026-11-10T09:30:00.000Z",
    "principal_id": "principal id",
    "principal_kind": "user",
    "role": "role",
    "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
  }'

Response · 201

JSON

{
  "id": "ra_01jc9f6ea6gbyszz4awcw2mg13",
  "object": "role_assignment",
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "expires_at": "2026-11-10T09:30:00.000Z",
  "principal_id": "principal id",
  "principal_kind": "user",
  "role": "role",
  "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
}

get/v1/roles

List roles

Any key of this organization

Sorts by kind (default: built-in roles strongest first, then custom ones by name), name, permissions (how many), created_at and updated_at (built-in roles last); q searches names and descriptions. Filters, each repeatable: builtin (true, false), created_by and updated_by (usr_… or sa_…), plus the created and updated time ranges; facets count each of them.

Query parameters

builtinstring[]
created_bystring[]
updated_bystring[]
limitinteger
Rows per page, 1 to 200. Omitted: every row.
at least 1at most 200
cursorstring
qstring
Search: rows whose name (or the list's other searchable text) contains this, any case.
at most 200 characters
orderstring
Sort field; a leading - sorts down. Each list names the fields it sorts by.
at most 64 charactersmatches ^-?[a-z_]+$
includestring[]
total_count (counted up to 10,000) and facets (a count per filter value).
One oftotal_countfacets
created_afterstring
Only rows created at or after this time (RFC 3339).
date-time
created_beforestring
Only rows created at or before this time (RFC 3339).
date-time
updated_afterstring
Only rows last changed at or after this time (RFC 3339).
date-time
updated_beforestring
Only rows last changed at or before this time (RFC 3339).
date-time

Response200

objectstring
list
dataRole[]
10 fields
- idstring or null
- objectstring
  role
- builtinboolean
- descriptionstring or null
- namestring
- permissionsstring[]
- created_atstring or null
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/roles?limit=20" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "id": "rol_01jcpxjfrf1q5xwty7pdsq4st9",
      "object": "role",
      "builtin": true,
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "description": "Reads new support email and drafts a reply.",
      "name": "Support triage",
      "permissions": [
        "permission"
      ],
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

post/v1/roles

Create role

Needs role.manage

Request bodyRoleCreate

namestringRequired
at least 1 charactersat most 100 characters
permissionsstring[]Required
at least 1 itemsat most 100 items
descriptionstring or null
at most 1000 characters

Response201

idstring or null
objectstring
role
builtinboolean
descriptionstring or null
namestring
permissionsstring[]
created_atstring or null
created_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
updated_atstring or null
updated_byActorRef or null
Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/roles" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Reads new support email and drafts a reply.",
    "name": "Support triage",
    "permissions": [
      "permission"
    ]
  }'

Response · 201

JSON

{
  "id": "rol_01jcpxjfrf1q5xwty7pdsq4st9",
  "object": "role",
  "builtin": true,
  "created_at": "2026-11-10T09:30:00.000Z",
  "created_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  },
  "description": "Reads new support email and drafts a reply.",
  "name": "Support triage",
  "permissions": [
    "permission"
  ],
  "updated_at": "2026-11-10T09:30:00.000Z",
  "updated_by": {
    "kind": "user",
    "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }
}

delete/v1/role_assignments/{assignment_id}

Unassign role

Needs role.manage

Path parameters

assignment_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/role_assignments/ra_01jc9f6ea6gbyszz4awcw2mg13" \
  -H "Authorization: Bearer $MDA_API_KEY"

delete/v1/roles/{role_id}

Delete role

Needs role.manage

Path parameters

role_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/roles/rol_01jcpxjfrf1q5xwty7pdsq4st9" \
  -H "Authorization: Bearer $MDA_API_KEY"

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide