---
title: "Roles · intentic sandbox API"
description: "Named characters an agent can wear: the accounts it speaks for and what it is told. Every route in the roles group of the intentic sandbox API."
url: "https://intentic.dev/api/roles/"
---

Agent setup

# Roles

Named characters an agent can wear: the accounts it speaks for and what it is told

**On this page (8 sections)**

- [The characters an agent can wear](#roles-list)
- [Create or edit a role](#roles-save)
- [Delete a role](#roles-remove)
- [What one role carries](#roles-kit)
- [Write a role's instructions](#roles-savePrompt)
- [Read one of a role's skills](#roles-readSkill)
- [Write one of a role's skills](#roles-saveSkill)
- [Delete one of a role's skills](#roles-removeSkill)

A role records a decision about accounts that already exist: which of them this character speaks for, what a conversation wearing it may do, and what it is told. The kit routes edit the files behind one — its own instructions, and the skills only its conversations reach.

8 calls. Pick one to open it, or use the list on the right.

**GET`/personas` The characters an agent can wear**

Each role with the connected accounts it speaks for, where a conversation wearing it opens, and what it is told. What it may reach is the access profiles that list it.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `roles` The characters an agent can wear | object[] |
| `id` The role's id | string |
| `label` What to call it on screen | string |
| `capabilities` Which signed-in accounts it speaks through:… | string[] |
| `brief` What this role is for, in… | string |
| `workspace` Where a conversation wearing it opens | object |
| `startIn` Which folder a conversation opens in | string |
| `context` Which part of the workspace a… | object |
| `repos` Which nested repositories a conversation on… | string[] |
| `briefing` Which of the notes the sandbox… | object |
| `omit` Which of the notes the sandbox… | "map" | "context" | "skills" | "search" … (9)[] |
| `models` Which models a conversation wearing it… | object[] |
| `provider` Which provider serves this work | string |
| `model` Which of its models | string |
| `effort` How hard this model should think,… | string |
| `thinking` Whether this model reasons before it… | boolean |
| `fast` Ask for this model's work at… | boolean |
| `harness` Which agentic loop runs it | "native" | "claude-code" | "codex" | "opencode" … (7) |
| `systemPromptMode` | "intentic" | "claude" | "custom" |
| `connected` Which accounts are actually connected right… | string[] |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/personas" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.list();
```

**POST`/personas` Create or edit a role**

Writes the whole card; sending an id that exists edits it. Nothing is connected, installed or spent by saving one, because a role only records a decision about accounts that already exist. It is stored as a file you can equally well edit by hand, which is why this writes the card whole rather than patching a field: a round trip through a screen should leave a change a reviewer recognises.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required The role's id | string | body |
| `label` What to call it on screen | string | body |
| `capabilities` required Which signed-in accounts it speaks through:… | string[] | body |
| `brief` What this role is for, in… | string | body |
| `workspace` Where a conversation wearing it opens | object | body |
| `startIn` Which folder a conversation opens in | string | body |
| `context` Which part of the workspace a… | object | body |
| `repos` required Which nested repositories a conversation on… | string[] | body |
| `briefing` Which of the notes the sandbox… | object | body |
| `omit` required Which of the notes the sandbox… | "map" | "context" | "skills" | "search" … (9)[] | body |
| `models` Which models a conversation wearing it… | object[] | body |
| `provider` required Which provider serves this work | string | body |
| `model` required Which of its models | string | body |
| `effort` How hard this model should think,… | string | body |
| `thinking` Whether this model reasons before it… | boolean | body |
| `fast` Ask for this model's work at… | boolean | body |
| `harness` Which agentic loop runs it | "native" | "claude-code" | "codex" | "opencode" … (7) | body |
| `systemPromptMode` | "intentic" | "claude" | "custom" | body |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/personas" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"id":"a1b2c3d4","label":"Nightly changelog","capabilities":["…","…"],"brief":"…","workspace":{"startIn":"…"},"context":{"repos":["root","site"]},"briefing":{"omit":["map","context"]},"models":[{"provider":"claude","model":"claude-sonnet-4-6","effort":"…","thinking":true,"fast":true,"harness":"native"},{"provider":"claude","model":"claude-haiku-4-6","effort":"…","thinking":true,"fast":true,"harness":"claude-code"}],"systemPromptMode":"intentic"}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.save({
 "id": "a1b2c3d4",
 "label": "Nightly changelog",
 "capabilities": [
 "…",
 "…"
 ],
 "brief": "…",
 "workspace": {
 "startIn": "…"
 },
 "context": {
 "repos": [
 "root",
 "site"
 ]
 },
 "briefing": {
 "omit": [
 "map",
 "context"
 ]
 },
 "models": [
 {
 "provider": "claude",
 "model": "claude-sonnet-4-6",
 "effort": "…",
 "thinking": true,
 "fast": true,
 "harness": "native"
 },
 {
 "provider": "claude",
 "model": "claude-haiku-4-6",
 "effort": "…",
 "thinking": true,
 "fast": true,
 "harness": "claude-code"
 }
 ],
 "systemPromptMode": "intentic"
});
```

**DELETE`/personas/{id}` Delete a role**

Takes away the character, never the accounts: every login it named stays connected. Its own prompt and skills go with it, since a folder nothing can reach is worse than deleting what somebody just asked to delete. Anything still pointed at it goes quiet rather than falling back to speaking as everyone.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which role | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X DELETE "$SANDBOX/personas/a1b2c3d4" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.remove({
 "id": "a1b2c3d4"
});
```

**GET`/personas/{id}/kit` What one role carries**

The instructions this role is given and the skills only its conversations can reach. A different question from what the agent knows generally, with a different answer.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which role | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `prompt` What this role is told, on… | string |
| `skills` Skills only this role's conversations can… | object[] |
| `name` The skill's name | string |
| `description` What it is for | string |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/personas/a1b2c3d4/kit" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.kit({
 "id": "a1b2c3d4"
});
```

**POST`/personas/{id}/prompt` Write a role's instructions**

Sets what this role is told. Saving an empty one removes it entirely rather than storing a blank, so the role simply falls back to the sandbox's own instructions.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which role | string | address |
| `prompt` required What to tell this role | string | body |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/personas/a1b2c3d4/prompt" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"prompt":"Update the changelog for the last five commits."}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.savePrompt({
 "id": "a1b2c3d4",
 "prompt": "Update the changelog for the last five commits."
});
```

**GET`/personas/{id}/skills/read` Read one of a role's skills**

The full text of a single skill belonging to this role.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which role | string | address |
| `name` required Which skill | string | query |

### What comes back

| Field | Type |
| --- | --- |
| `name` The skill's name | string |
| `description` What it is for | string |
| `body` The skill itself, in full | string |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/personas/a1b2c3d4/skills/read?name=nightly%20changelog" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.readSkill({
 "id": "a1b2c3d4",
 "name": "nightly changelog"
});
```

**POST`/personas/{id}/skills` Write one of a role's skills**

Creates or replaces a skill by name. There is nothing to switch on: a role's skill is available exactly when that role is worn, which is what belonging to it has to mean.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which role | string | address |
| `name` required What to call it | string | body |
| `description` required What it is for, which is… | string | body |
| `body` required The skill itself | string | body |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/personas/a1b2c3d4/skills" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"name":"nightly changelog","description":"Runs every night and opens a pull request when anything changed.","body":"…"}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.saveSkill({
 "id": "a1b2c3d4",
 "name": "nightly changelog",
 "description": "Runs every night and opens a pull request when anything changed.",
 "body": "…"
});
```

**POST`/personas/{id}/skills/remove` Delete one of a role's skills**

Removes a single skill from this role and leaves the rest of its kit alone.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which role | string | address |
| `name` required Which skill | string | body |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/personas/a1b2c3d4/skills/remove" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"name":"nightly changelog"}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.roles.removeSkill({
 "id": "a1b2c3d4",
 "name": "nightly changelog"
});
```

More in Agent setup

[Next Skills →](https://intentic.dev/api/skills/)
