Prompt lifecycle
Theclient.prompts namespace covers the prompt lifecycle. Each method takes keyword-only arguments.
- Prompts:
create,list,get,update,archive. - Versions:
create_version,list_versions,iter_versions,get_version. See Versions. - Labels on a prompt:
list_labels, which returns a cursor page holding the one label a prompt has,latest, pointing at its newest version. Onlycreate_versionmoves it; there is no method to move a label.
Versions
Versions are listed as metadata and read one at a time with their content.list_versions returns summaries, newest first, paged by an opaque cursor. get_version returns one version with its template_json, variables_schema, and model_config_. create_version returns the full version it created.
Listing versions
list_versions(prompt_id=..., cursor=None, limit=None) returns a page with items, a list of PromptVersionSummary, and pagination, which carries next_cursor and limit. limit defaults to 50 and is at most 100. Pass pagination.next_cursor back as cursor for the next, older page; on the last page it is None. 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
iter_versions(prompt_id=..., limit=None). It follows next_cursor until it is None 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 iter_cursor_items(fetch_page) (items) and iter_cursor_pages(fetch_page) (whole pages), exported from to11ai_sdk.
Reading a version
get_version(prompt_id=..., version_number=...) returns a PromptVersion: every summary field plus template_json, variables_schema, and model_config_. template_json is the content — {"messages": [...]} for a chat prompt, {"files": [...]} for a skill. variables_schema is the schema of the variables the version takes, and model_config_ holds the model id and generation settings authored in the editor’s Config pane. The trailing underscore keeps the field clear of pydantic’s own model_config.
Skills
Two methods read skills across an organization:list_org_prompts(org_id=..., query=None, limit=None)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.render_skill_version(project_id=..., slug=..., version=...)renders one exact version of a skill. Itsfilesholds each file’sfilenameandcontent. Pass theversionlist_org_promptsreturned, so you get exactly the version you listed, whateverlatestserves by then.
Project environments
client.project_environments manages a project’s environments, the named slots its prompts and skills publish to. It exposes list, iter, get, create, update, archive, and restore. Each method takes keyword-only arguments, including project_id; these methods do not default it from the client. list leaves archived environments out unless you pass include_archived=True, and returns a cursor page like list_versions. Environments have no bearing on which prompt version render serves.