> ## 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/typescript-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 a single options object.

* Prompts: `create`, `list`, `get`, `update`, `archive`.
* Versions: `createVersion`, `listVersions`, `iterateVersions`, `getVersion`. See [Versions](#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.

| Field | Holds |
| - | - |
| `id` | The version's id. |
| `promptId` | 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 `null`. |
| `createdByUserId` | The user or API key that created it. |
| `createdAt` | When it was created. |
| `createdByDisplayName` | The creator's display name. |
| `createdByImage` | The creator's avatar URL, or `null`. |

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:

```ts theme={null}
for await (const summary of to11.prompts.iterateVersions({ promptId, limit: 100 })) {
  console.log(`v${summary.version}`, summary.changelog);
}
```

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.

```ts theme={null}
const { items } = await to11.prompts.listVersions({ promptId, limit: 1 });
const newest = items[0];
if (newest) {
  const version = await to11.prompts.getVersion({
    promptId,
    versionNumber: newest.version,
  });
  version.templateJson; // the content the summary leaves out
}
```

## Skills

Two methods read [skills](https://to11.ai/docs/skills/concepts.md) 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.

```ts theme={null}
const { items } = await to11.prompts.listOrgPrompts({ orgId: "org_1", query: "release" });
const skill = await to11.prompts.renderSkillVersion({
  projectId: items[0].projectId,
  slug: items[0].slug,
  version: items[0].version,
});
skill.files; // [{ 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.projectEnvironments` manages a project's [environments](https://to11.ai/docs/platform/environments.md), 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.


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