---
title: "Personas · intentic sandbox API"
description: "Named characters an agent can wear: the accounts it speaks for and what it is told. Every route in the personas group of the intentic sandbox API, with its input, its answer and a playground."
url: "https://intentic.dev/api/personas/"
---

Agent setup

# Personas

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](#personas-list)
- [Create or edit a persona](#personas-save)
- [Delete a persona](#personas-remove)
- [What one persona carries](#personas-kit)
- [Write a persona's instructions](#personas-savePrompt)
- [Read one of a persona's skills](#personas-readSkill)
- [Write one of a persona's skills](#personas-saveSkill)
- [Delete one of a persona's skills](#personas-removeSkill)

A persona 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 persona with the connected accounts it speaks for, what a conversation wearing it is allowed to do, and where it works.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `personas` The characters an agent can wear | object[] |
| `id` The persona's id | string |
| `label` What to call it on screen | string |
| `capabilities` Which connected accounts are its hands | string[] |
| `repos` Which repositories prefer this persona, so… | string[] |
| `powers` What a conversation wearing it may… | object |
| `files` What it may do with files:… | "none" | "read" | "write" |
| `shell` Whether it may run commands, and… | boolean |
| `code` Whether it may write and run… | boolean |
| `web` Whether it may fetch a page… | boolean |
| `browser` | boolean |
| `delegate` | boolean |
| `sandbox` | boolean |
| `connectors` | string[] |
| `computers` | string[] |
| `mcp` | string[] |
| `workspace` Where it works | object |
| `startIn` Which folder a conversation opens in | string |
| `folders` Which folders it may touch at… | string[] |
| `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.personas.list();
```

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

Writes the whole card; sending an id that exists edits it. Nothing is connected, installed or spent by saving one, because a persona 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 persona's id | string | body |
| `label` What to call it on screen | string | body |
| `capabilities` required Which connected accounts are its hands | string[] | body |
| `repos` Which repositories prefer this persona, so… | string[] | body |
| `powers` What a conversation wearing it may… | object | body |
| `files` What it may do with files:… | "none" | "read" | "write" | body |
| `shell` Whether it may run commands, and… | boolean | body |
| `code` Whether it may write and run… | boolean | body |
| `web` Whether it may fetch a page… | boolean | body |
| `browser` | boolean | body |
| `delegate` | boolean | body |
| `sandbox` | boolean | body |
| `connectors` | string[] | body |
| `computers` | string[] | body |
| `mcp` | string[] | body |
| `workspace` Where it works | object | body |
| `startIn` Which folder a conversation opens in | string | body |
| `folders` Which folders it may touch at… | string[] | 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":["…","…"],"repos":["root","site"],"powers":{"files":"none","shell":true,"code":true,"web":true,"browser":true,"delegate":true,"sandbox":true,"connectors":["…","…"],"computers":["…","…"],"mcp":["…","…"]},"workspace":{"startIn":"…","folders":["…","…"]},"systemPromptMode":"intentic"}'
```

TypeScript

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

const result = await sandbox.personas.save({
 "id": "a1b2c3d4",
 "label": "Nightly changelog",
 "capabilities": [
 "…",
 "…"
 ],
 "repos": [
 "root",
 "site"
 ],
 "powers": {
 "files": "none",
 "shell": true,
 "code": true,
 "web": true,
 "browser": true,
 "delegate": true,
 "sandbox": true,
 "connectors": [
 "…",
 "…"
 ],
 "computers": [
 "…",
 "…"
 ],
 "mcp": [
 "…",
 "…"
 ]
 },
 "workspace": {
 "startIn": "…",
 "folders": [
 "…",
 "…"
 ]
 },
 "systemPromptMode": "intentic"
});
```

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

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 persona | 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.personas.remove({
 "id": "a1b2c3d4"
});
```

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

The instructions this persona 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 persona | string | address |

### What comes back

| Field | Type |
| --- | --- |
| `prompt` What this persona is told, on… | string |
| `skills` Skills only this persona'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.personas.kit({
 "id": "a1b2c3d4"
});
```

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

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

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which persona | string | address |
| `prompt` required What to tell this persona | 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.personas.savePrompt({
 "id": "a1b2c3d4",
 "prompt": "Update the changelog for the last five commits."
});
```

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

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

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which persona | 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.personas.readSkill({
 "id": "a1b2c3d4",
 "name": "nightly changelog"
});
```

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

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

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which persona | 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.personas.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 persona's skills**

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

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `id` required Which persona | 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.personas.removeSkill({
 "id": "a1b2c3d4",
 "name": "nightly changelog"
});
```

More in Agent setup

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