> ## Documentation Index
> Fetch the complete documentation index at: https://to11.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt management

> Manage prompts, versions, and the label a prompt carries, read skills across an organization, and manage project environments.

Rendering a prompt for a call is covered in [Rendering prompts](https://to11.ai/docs/reference/python-sdk/rendering-prompts.md). 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 keyword-only arguments.

* Prompts: `create`, `list`, `get`, `update`, `archive`.
* Versions: `create_version`, `list_versions`, `iter_versions`, `get_version`. See [Versions](#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. Only `create_version` 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. `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.

| Field | Holds |
| - | - |
| `id` | The version's id. |
| `prompt_id` | The prompt it belongs to. |
| `version` | The version number, from `1` upward. `latest` points at the highest. |
| `format` | `text`, `chat` or `skill`, by the prompt's kind. |
| `changelog` | The note given when the version was created, or `None`. |
| `created_by_user_id` | The user or API key that created it. |
| `created_at` | When it was created. |
| `created_by_display_name` | The creator's display name. |
| `created_by_image` | The creator's avatar URL, or `None`. |

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:

```python theme={null}
for summary in client.prompts.iter_versions(prompt_id=prompt_id, limit=100):
    print(f"v{summary.version}", summary.changelog)
```

If the server ever returns a cursor it already returned, the iterator raises `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`.

```python theme={null}
page = client.prompts.list_versions(prompt_id=prompt_id, limit=1)
if page.items:
    version = client.prompts.get_version(
        prompt_id=prompt_id,
        version_number=page.items[0].version,
    )
    version.template_json  # the content the summary leaves out
```

## Skills

Two methods read [skills](https://to11.ai/docs/skills/concepts.md) 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 version `latest` serves. `query` matches a skill's name or slug, case-insensitively; `limit` defaults to 20 and is at most 50.
* `render_skill_version(project_id=..., slug=..., version=...)` renders one exact version of a skill. Its `files` holds each file's `filename` and `content`. Pass the `version` `list_org_prompts` returned, so you get exactly the version you listed, whatever `latest` serves by then.

```python theme={null}
listing = client.prompts.list_org_prompts(org_id="org_1", query="release")
row = listing.items[0]
skill = client.prompts.render_skill_version(project_id=row.project_id, slug=row.slug, version=row.version)
skill.files  # [RenderedSkillFile(filename="SKILL.md", content=..., ...)]
```

Storing a skill version is done with the [to11 CLI](https://to11.ai/docs/reference/cli/commands.md#to11-skill-store).

## Project environments

`client.project_environments` manages a project's [environments](https://to11.ai/docs/platform/environments.md), 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.