Skip to main content
Rendering a prompt for a call is covered in Rendering prompts. This page covers the lifecycle around it — creating and versioning prompts, reading a prompt’s label, reading skills, and managing the project’s environments.

Prompt lifecycle

The client.prompts namespace covers the prompt lifecycle. Each method takes a single options object.
  • Prompts: create, list, get, update, archive.
  • Versions: createVersion, listVersions, iterateVersions, getVersion. See Versions.
  • Labels on a prompt: listLabels, which returns a cursor page holding the one label a prompt has, latest, pointing at its newest version. Only createVersion moves it; there is no method to move a label.

Versions

Versions are listed as metadata and read one at a time with their content. listVersions returns summaries, newest first, paged by an opaque cursor. getVersion returns one version with its templateJson, variablesSchema, and modelConfig. createVersion returns the full version it created.

Listing versions

listVersions({ promptId, cursor?, limit? }) returns { items, pagination }: items is an array of PromptVersionSummary, and pagination is { nextCursor, limit }. limit defaults to 50 and is at most 100. Pass pagination.nextCursor back as cursor for the next, older page; on the last page it is null. There is no page number and no total. A summary carries no content, so a page of 100 versions costs one small request however large the versions are. To walk the whole history, use iterateVersions({ promptId, limit? }). It follows nextCursor until it is null and yields one PromptVersionSummary at a time; limit sets the page size of each request:
If the server ever returns a cursor it already returned, the iterator throws a To11aiError instead of looping. The same walk is available for any cursor list as iterateCursorItems(fetchPage) (items) and iterateCursorPages(fetchPage) (whole pages), exported from @to11ai/sdk.

Reading a version

getVersion({ promptId, versionNumber }) returns a PromptVersion: every summary field plus templateJson, variablesSchema, and modelConfig. templateJson is the content — { messages: [...] } for a chat prompt, { files: [...] } for a skill. variablesSchema is the schema of the variables the version takes, and modelConfig holds the model id and generation settings authored in the editor’s Config pane.

Skills

Two methods read skills across an organization:
  • listOrgPrompts({ orgId, query?, limit? }) lists the skills in every project of the organization that you may read prompts in, each with the version latest serves. query matches a skill’s name or slug, case-insensitively; limit defaults to 20 and is at most 50.
  • renderSkillVersion({ projectId, slug, version }) renders one exact version of a skill. Its files holds each file’s filename and content. Pass the version listOrgPrompts returned, so you get exactly the version you listed, whatever latest serves by then.
Storing a skill version is done with the to11 CLI.

Project environments

client.projectEnvironments manages a project’s environments, the named slots its prompts and skills publish to. It exposes list, iterate, get, create, update, archive, and restore. Each method takes a single options object that includes projectId; these methods do not default it from the client. list leaves archived environments out unless you pass includeArchived: true, and returns a cursor page like listVersions. Environments have no bearing on which prompt version render serves.