---
title: "Create Role"
api: "POST /v1/api/roles-and-permissions/roles"
description: "Create a new role with specific permissions for your workspace."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

Requires the `role:create` permission in the workspace.

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
Name of the role (e.g., "Agent Manager").
</ParamField>

<ParamField body="description" type="string" required>
Description of the role and its intended use. Must not be empty.
</ParamField>

<ParamField body="permissions" type="array of strings" required>
Permission keys to grant, in `category:action` form (e.g., `"agent:view"`, `"call_history:view"`). At least one is required. Each item must be a plain string, not an object. An unknown key returns `400` with `Invalid permission: <key>`. `agency_hub:*` permissions can only be granted in an agency (white-label) master workspace; elsewhere they return `403`. Use [List Permissions](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/roles/list-permissions) for the available keys.
</ParamField>

<ParamField body="userIds" type="array of strings" required>
User IDs to assign this role to. Send an empty array `[]` to create the role without assigning anyone.
</ParamField>

## Response

Returns `201 Created` with the new role.

<ResponseField name="_id" type="string">
Unique identifier for the created role.
</ResponseField>

<ResponseField name="name" type="string">
Name of the role.
</ResponseField>

<ResponseField name="description" type="string">
Description of the role.
</ResponseField>

<ResponseField name="permissions" type="object">
Granted permissions grouped by category. Each key is a category and its value is the list of permission keys in that category.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the role.
</ResponseField>

<ResponseField name="isSystem" type="boolean">
Always `false` for roles you create.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the role was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
Timestamp when the role was last updated.
</ResponseField>

<RequestExample>
```json
{
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": [
    "agent:view",
    "agent:create",
    "agent:edit",
    "call_history:view"
  ],
  "userIds": []
}
```
</RequestExample>

<ResponseExample>
```json 201
{
  "_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
  "workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1",
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": {
    "agent": ["agent:view", "agent:create", "agent:edit"],
    "call_history": ["call_history:view"]
  },
  "isSystem": false,
  "createdAt": "2024-06-01T09:00:00.000Z",
  "updatedAt": "2024-06-01T09:00:00.000Z",
  "__v": 0
}
```

```json 400
{
  "error": "Invalid permission: agent_view"
}
```
</ResponseExample>


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
