Prompts

Prompts are the core resource: a versioned, taggable instruction record. Every prompt has at least one PromptVersion carrying the editable content (title, task, compiledPrompt, etc.); updates create a new version rather than mutating the previous one.

Methods
About destructive examples Examples marked writes to your account create real prompts and clean them up. You'll be prompted to confirm before they run.

list

client.prompts.list(params?: ListParams): Promise<Page<PromptSummary>>

Paginated list of prompts. Returns a navigable Page<T>.

Parameters

NameTypeDefaultDescription
pagenumber11-based page number.
pageSize6 | 12 | 24 | 48 | 10012Items per page (server-enforced enum).
sort"newest" | "most-upvoted" | "most-favorited""newest"Sort order.
scope"public" | "mine" | "favorites" | "all""public"Which prompts to include.
searchstring-Full-text search (max 200 chars).
tagstring-Filter by a single tag.
signalAbortSignal-Abort the request.
List public prompts 
const page = await client.prompts.list({
  scope: "public",
  sort: "most-upvoted",
  pageSize: 6,
});

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

listAll

client.prompts.listAll(params?: ListParams): AsyncIterable<PromptSummary>

Async iterator that walks every page automatically. Use for await; break stops further requests.

Iterate the public feed 
const titles = [];
for await (const prompt of client.prompts.listAll({ scope: "public", pageSize: 12 })) {
  titles.push(prompt.title);
  if (titles.length >= 12) break; // stop early - don't drain everything
}
return titles;

get

client.prompts.get(id: string): Promise<Prompt>

Fetch the full Prompt by id. Throws PromptyNotFoundError on 404.

Fetch one of the top public prompts 
const page = await client.prompts.list({ scope: "public", pageSize: 6, sort: "most-upvoted" });
const first = page.items[0];
if (!first) return { empty: true };

const prompt = await client.prompts.get(first.id);
return {
  id: prompt.id,
  title: prompt.title,
  task: prompt.task.slice(0, 120) + (prompt.task.length > 120 ? "…" : ""),
  tags: prompt.tags,
  isPublic: prompt.isPublic,
  isOwner: prompt.isOwner,
  currentVersion: prompt.currentVersion,
};

create

client.prompts.create(input: PromptCreateInput): Promise<PromptCreateResponse>

Create a new prompt. The response is narrower than Prompt - it only carries the row identifiers (id, userId, isPublic, etc.) because the title/task/compiledPrompt live on the version row. Call get(response.id) if you need the full record.

⚠️ Writes to your account. Cleans up after itself.
Create then delete 
const created = await client.prompts.create({
  title: "Docs demo: greet a colleague",
  task: "Write a friendly greeting for a colleague.",
  compiledPrompt: "Write a friendly greeting for a colleague joining the team.",
  description: "Created from the @prompty-tools/core docs site.",
  isPublic: false,
  tags: ["demo", "docs"],
});
console.log("created", created.id);

// Clean up so we don't leave docs litter in your account.
await client.prompts.delete(created.id);
console.log("cleaned up", created.id);

return created;

update

client.prompts.update(id: string, input: PromptUpdateInput): Promise<void>

Create a new version of the prompt. Every field is required (the server snapshots a complete version), and a non-empty changelog is mandatory.

⚠️ Writes to your account. Cleans up after itself.
Create, update, then delete 
const created = await client.prompts.create({
  title: "Docs demo: original",
  task: "Original task.",
  compiledPrompt: "Original compiled prompt.",
  isPublic: false,
});

await client.prompts.update(created.id, {
  title: "Docs demo: updated",
  task: "Updated task.",
  compiledPrompt: "Updated compiled prompt.",
  changelog: "Refined wording.",
});

const detail = await client.prompts.get(created.id);
console.log("currentVersion =", detail.currentVersion);

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

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

delete

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

Permanently delete a prompt and all of its versions. Resolves with void.

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

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

// Confirm deletion: GET should now 404.
try {
  await client.prompts.get(created.id);
  return { deleted: false, note: "Still found?" };
} catch (err) {
  if (err instanceof PromptyNotFoundError) {
    return { deleted: true, status: err.status };
  }
  throw err;
}

setVisibility

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

Toggle whether a prompt is publicly visible. Backed by the dedicated PATCH /prompts/{id}/visibility endpoint.

⚠️ Writes to your account. Cleans up after itself.
Flip a private prompt to public, then clean up 
const created = await client.prompts.create({
  title: "Docs demo: visibility toggle",
  task: "Demo.",
  compiledPrompt: "Demo.",
  isPublic: false,
});

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

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

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

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

vote

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

Upvote (1) or downvote (-1) a prompt.

⚠️ Writes to your account. Cleans up after itself.
Vote on your own prompt then clean up 
const created = await client.prompts.create({
  title: "Docs demo: vote target",
  task: "Demo.",
  compiledPrompt: "Demo.",
  isPublic: false,
});

await client.prompts.vote(created.id, 1);
const detail = await client.prompts.get(created.id);

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

return { upvotes: detail.upvotes, downvotes: detail.downvotes, userVote: detail.userVote };

unvote

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

Remove the caller's vote (sends { value: null } to the same endpoint). Idempotent - calling it without a prior vote is a no-op.

⚠️ Writes to your account. Cleans up after itself.
Vote, then unvote, then clean up 
const created = await client.prompts.create({
  title: "Docs demo: unvote",
  task: "Demo.",
  compiledPrompt: "Demo.",
  isPublic: false,
});

await client.prompts.vote(created.id, 1);
const afterVote = await client.prompts.get(created.id);

await client.prompts.unvote(created.id);
const afterUnvote = await client.prompts.get(created.id);

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

return {
  afterVote: { upvotes: afterVote.upvotes, userVote: afterVote.userVote },
  afterUnvote: { upvotes: afterUnvote.upvotes, userVote: afterUnvote.userVote },
};

toggleFavorite

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

Flip the favorite state. The endpoint is a true toggle on the server - there is no set-favorite-to-X form. The response tells you the resulting state.

⚠️ Writes to your account. Cleans up after itself.
Toggle on, toggle off, then clean up 
const created = await client.prompts.create({
  title: "Docs demo: favorite toggle",
  task: "Demo.",
  compiledPrompt: "Demo.",
  isPublic: false,
});

const a = await client.prompts.toggleFavorite(created.id);
const b = await client.prompts.toggleFavorite(created.id);

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

return { firstToggle: a.favorited, secondToggle: b.favorited };

listVersions

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

Paginated list of versions for a prompt. Page sizes are 10 | 20 | 50 (different from the main list endpoints).

⚠️ Writes to your account. Cleans up after itself.
Create, update twice, list versions, clean up 
const created = await client.prompts.create({
  title: "Docs demo: v1",
  task: "v1 task.",
  compiledPrompt: "v1.",
  isPublic: false,
});

await client.prompts.update(created.id, {
  title: "Docs demo: v2",
  task: "v2 task.",
  compiledPrompt: "v2.",
  changelog: "Second iteration.",
});

const page = await client.prompts.listVersions(created.id, { pageSize: 10 });

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

return {
  total: page.total,
  versions: page.items.map((v) => ({ version: v.version, title: v.title, changelog: v.changelog })),
};

getVersion

client.prompts.getVersion(id: string, versionId: string): Promise<PromptVersion>

Fetch a specific version of a prompt by its version-row id.

⚠️ Writes to your account. Cleans up after itself.
Pull a specific version 
const created = await client.prompts.create({
  title: "Docs demo: getVersion",
  task: "Original.",
  compiledPrompt: "Original.",
  isPublic: false,
});

const versions = await client.prompts.listVersions(created.id, { pageSize: 10 });
const first = versions.items[0];
if (!first) {
  await client.prompts.delete(created.id);
  return { error: "no versions found" };
}

const version = await client.prompts.getVersion(created.id, first.id);

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

return {
  versionId: version.id,
  version: version.version,
  title: version.title,
  task: version.task,
  changelog: version.changelog,
};