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/personasThe 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
rolesThe characters an agent can wear
object[]
idThe role's id
string
labelWhat to call it on screen
string
capabilitiesWhich signed-in accounts it speaks through:…
import { sandbox } from "@intentic/sandbox-client";const result = await sandbox.roles.list();
POST/personasCreate 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
idrequiredThe role's id
string
body
labelWhat to call it on screen
string
body
capabilitiesrequiredWhich signed-in accounts it speaks through:…
string[]
body
briefWhat this role is for, in…
string
body
workspaceWhere a conversation wearing it opens
object
body
startInWhich folder a conversation opens in
string
body
contextWhich part of the workspace a…
object
body
reposrequiredWhich nested repositories a conversation on…
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.
import { sandbox } from "@intentic/sandbox-client";const result = await sandbox.roles.remove({ "id": "a1b2c3d4"});
GET/personas/{id}/kitWhat 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.
import { sandbox } from "@intentic/sandbox-client";const result = await sandbox.roles.kit({ "id": "a1b2c3d4"});
POST/personas/{id}/promptWrite 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
idrequiredWhich role
string
address
promptrequiredWhat to tell this role
string
body
What comes back
Field
Type
okAlways true
true
Try itanswered in this tab
curl
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
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/readRead one of a role's skills
The full text of a single skill belonging to this role.
import { sandbox } from "@intentic/sandbox-client";const result = await sandbox.roles.readSkill({ "id": "a1b2c3d4", "name": "nightly changelog"});
POST/personas/{id}/skillsWrite 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
idrequiredWhich role
string
address
namerequiredWhat to call it
string
body
descriptionrequiredWhat it is for, which is…
string
body
bodyrequiredThe skill itself
string
body
What comes back
Field
Type
okAlways true
true
Try itanswered in this tab
curl
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
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/removeDelete one of a role's skills
Removes a single skill from this role and leaves the rest of its kit alone.