Personas

Personas describe the speaker / point-of-view that a prompt should adopt. Like prompts, they are versioned - every update() creates a new CustomPersonaVersion. New personas default to private on the server (unlike prompts, which default to public).

Methods

list

client.personas.list(params?: ListParams): Promise<Page<PersonaSummary>>

Same shape as prompts.list - accepts page, pageSize, sort, scope, search, tag, and signal.

List public personas 
const page = await client.personas.list({
  scope: "public",
  sort: "newest",
  pageSize: 6,
});

return {
  total: page.total,
  items: page.items.map((p) => ({ id: p.id, title: p.title, tags: p.tags })),
};

listAll

client.personas.listAll(params?: ListParams): AsyncIterable<PersonaSummary>

Iterate the public feed 
const titles = [];
for await (const persona of client.personas.listAll({ scope: "public", pageSize: 12 })) {
  titles.push(persona.title);
  if (titles.length >= 12) break;
}
return titles;

get

client.personas.get(id: string): Promise<Persona>

Fetch a public persona detail 
const page = await client.personas.list({ scope: "public", pageSize: 6 });
const first = page.items[0];
if (!first) return { empty: true };

const persona = await client.personas.get(first.id);
return {
  id: persona.id,
  title: persona.title,
  description: persona.description,
  isPublic: persona.isPublic,
  isOwner: persona.isOwner,
  currentVersion: persona.currentVersion,
  latestVersionId: persona.latestVersionId,
};

create

client.personas.create(input: PersonaCreateInput): Promise<PersonaCreateResponse>

Create a new persona. The response includes the new versionId in addition to the persona id.

⚠️ Writes to your account. Cleans up after itself.
Create then delete 
const created = await client.personas.create({
  title: "Docs demo persona",
  description: "An ephemeral persona created from the docs site.",
  tags: ["demo", "docs"],
});
console.log("created", created);

await client.personas.delete(created.id);

return created;

update

client.personas.update(id: string, input: PersonaUpdateInput): Promise<void>

Creates a new persona version. Pass an optional changelog.

⚠️ Writes to your account. Cleans up after itself.
Create, update, then delete 
const created = await client.personas.create({
  title: "Docs demo: original",
  description: "Original description.",
});

await client.personas.update(created.id, {
  title: "Docs demo: updated",
  description: "Updated description.",
  changelog: "Refined wording.",
});

const detail = await client.personas.get(created.id);

await client.personas.delete(created.id);

return { id: created.id, currentVersion: detail.currentVersion, title: detail.title };

delete

client.personas.delete(id: string): Promise<void>

⚠️ Writes to your account. Cleans up after itself.
Create then delete 
const created = await client.personas.create({
  title: "Docs demo: ephemeral",
  description: "Will be deleted immediately.",
});

await client.personas.delete(created.id);

try {
  await client.personas.get(created.id);
  return { deleted: false };
} catch (err) {
  if (err instanceof PromptyNotFoundError) {
    return { deleted: true, status: err.status };
  }
  throw err;
}

setVisibility

client.personas.setVisibility(id: string, isPublic: boolean): Promise<void>

Personas are private by default - flip to public to make them appear in the public feed.

⚠️ Writes to your account. Cleans up after itself.
Toggle visibility, then clean up 
const created = await client.personas.create({ title: "Docs demo: visibility", description: "" });

await client.personas.setVisibility(created.id, true);
const afterPublic = await client.personas.get(created.id);

await client.personas.setVisibility(created.id, false);
const afterPrivate = await client.personas.get(created.id);

await client.personas.delete(created.id);

return { afterPublic: afterPublic.isPublic, afterPrivate: afterPrivate.isPublic };

vote

client.personas.vote(id: string, value: 1 | -1): Promise<void>

⚠️ Writes to your account. Cleans up after itself.
Vote on your own persona 
const created = await client.personas.create({ title: "Docs demo: vote", description: "" });
await client.personas.vote(created.id, 1);
const detail = await client.personas.get(created.id);
await client.personas.delete(created.id);
return { upvotes: detail.upvotes, userVote: detail.userVote };

unvote

client.personas.unvote(id: string): Promise<void>

⚠️ Writes to your account. Cleans up after itself.
Vote, unvote, clean up 
const created = await client.personas.create({ title: "Docs demo: unvote", description: "" });
await client.personas.vote(created.id, 1);
await client.personas.unvote(created.id);
const detail = await client.personas.get(created.id);
await client.personas.delete(created.id);
return { upvotes: detail.upvotes, userVote: detail.userVote };

toggleFavorite

client.personas.toggleFavorite(id: string): Promise<{ favorited: boolean }>

⚠️ Writes to your account. Cleans up after itself.
Toggle on, off, clean up 
const created = await client.personas.create({ title: "Docs demo: favorite", description: "" });
const a = await client.personas.toggleFavorite(created.id);
const b = await client.personas.toggleFavorite(created.id);
await client.personas.delete(created.id);
return { firstToggle: a.favorited, secondToggle: b.favorited };

listVersions

client.personas.listVersions(id: string, params?: VersionListParams): Promise<Page<PersonaVersionSummary>>

⚠️ Writes to your account. Cleans up after itself.
Create, update, list versions, clean up 
const created = await client.personas.create({ title: "Docs demo: v1", description: "" });
await client.personas.update(created.id, { title: "Docs demo: v2", description: "v2", changelog: "second" });
const page = await client.personas.listVersions(created.id, { pageSize: 10 });
await client.personas.delete(created.id);
return {
  total: page.total,
  versions: page.items.map((v) => ({ version: v.version, title: v.title, changelog: v.changelog })),
};

getVersion

client.personas.getVersion(id: string, versionId: string): Promise<PersonaVersion>

⚠️ Writes to your account. Cleans up after itself.
Pull a specific version 
const created = await client.personas.create({ title: "Docs demo: getVersion", description: "" });
const versions = await client.personas.listVersions(created.id, { pageSize: 10 });
const first = versions.items[0];
const version = await client.personas.getVersion(created.id, first.id);
await client.personas.delete(created.id);
return {
  versionId: version.id,
  version: version.version,
  title: version.title,
  description: version.description,
};