Prompt lifecycle
Theclient.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. OnlycreateVersionmoves 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:
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 versionlatestserves.querymatches a skill’s name or slug, case-insensitively;limitdefaults to 20 and is at most 50.renderSkillVersion({ projectId, slug, version })renders one exact version of a skill. Itsfilesholds each file’sfilenameandcontent. Pass theversionlistOrgPromptsreturned, so you get exactly the version you listed, whateverlatestserves by then.
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.