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

# Prompts

> Manage prompts with the TypeScript SDK

# Prompts SDK

Manage prompts programmatically with full type safety.

## List Prompts

```typescript theme={null}
const result = await client.prompt.listPrompts({
  limit: 20,
  offset: 0,
  isLatest: true,
});

for await (const page of result) {
  const { data, total, hasNext } = page.result;
  data.forEach(p => console.log(p.name, 'v' + p.version));
}
```

You can filter by `name`, `version`, `isLatest`, or `createdBy`:

```typescript theme={null}
const result = await client.prompt.listPrompts({
  name: 'support',
  isLatest: true,
  createdBy: 'user@example.com',
});
```

## Create Prompt

MutagenT supports three prompt formats. Use `humanPrompt` for template-based prompts, `systemPrompt` + `humanPrompt` for structured prompts, or `rawPrompt` for plain text.

<CodeGroup>
  ```typescript Structured (System + Human) theme={null}
  const prompt = await client.prompt.createPrompt({
    name: 'Support Assistant',
    systemPrompt: 'You are a helpful support agent for {company}.',
    humanPrompt: 'The customer asks: {question}',
    description: 'Customer support prompt',
    inputSchema: {
      type: 'object',
      properties: {
        company: { type: 'string' },
        question: { type: 'string' },
      },
    },
    tags: ['production', 'support'],
  });

  console.log('Created:', prompt.id, 'v' + prompt.version);
  ```

  ```typescript Human Prompt Only theme={null}
  const prompt = await client.prompt.createPrompt({
    name: 'Summarizer',
    humanPrompt: 'Summarize the following text:\n\n{text}',
    inputSchema: {
      type: 'object',
      properties: {
        text: { type: 'string' },
      },
    },
  });
  ```

  ```typescript Raw Prompt theme={null}
  const prompt = await client.prompt.createPrompt({
    name: 'Simple Greeting',
    rawPrompt: 'Hello, welcome to our service!',
    inputSchema: {},
  });
  ```
</CodeGroup>

<Note>
  Template variables use single braces: `{variable}`. Define matching keys in `inputSchema` for validation.
</Note>

## Get Prompt by ID

```typescript theme={null}
const prompt = await client.prompt.getPrompt({ id: 123 });

console.log(prompt.name, 'v' + prompt.version);
console.log('System:', prompt.systemPrompt);
console.log('Human:', prompt.humanPrompt);
console.log('Latest:', prompt.isLatest);
```

## Update Prompt

```typescript theme={null}
const updated = await client.prompt.updatePrompt({
  id: 123,
  body: {
    description: 'Updated description',
    humanPrompt: 'Revised prompt for {company}.',
    isLatest: true,
    tags: ['production', 'v2'],
  },
});
```

The `body` object accepts all optional fields:

| Field          | Type       | Description                   |
| -------------- | ---------- | ----------------------------- |
| `description`  | `string`   | Updated description           |
| `isLatest`     | `boolean`  | Mark as latest version        |
| `systemPrompt` | `string`   | Updated system prompt         |
| `humanPrompt`  | `string`   | Updated human prompt template |
| `rawPrompt`    | `string`   | Updated raw prompt            |
| `outputSchema` | `object`   | Updated output schema         |
| `metadata`     | `object`   | Updated metadata              |
| `tags`         | `string[]` | Updated tags                  |

## Delete Prompt

```typescript theme={null}
const result = await client.prompt.deletePrompt({ id: 123 });
```

## Create New Version

Create a new version of an existing prompt with optional changes to its content:

```typescript theme={null}
const newVersion = await client.prompt.createPromptVersion({
  id: 123,
  body: {
    newVersion: '2.0.0',
    changes: {
      humanPrompt: 'Improved prompt for {company}: {question}',
      isLatest: true,
    },
  },
});

console.log('New version:', newVersion.version);
```

## List Prompt's Datasets

```typescript theme={null}
const datasets = await client.promptDatasets.listDatasetsForPrompt({
  id: 123,
});

datasets.forEach(d => console.log(d.name, d.promptGroupId));
```

## Prompt Lifecycle

<Mermaid>
  flowchart LR
  A\[createPrompt] --> B\[Prompt v1.0.0]
  B --> C\[updatePrompt]
  C --> D\[Updated Prompt]
  B --> E\[createPromptVersion]
  E --> F\[Prompt v2.0.0]
  F --> G\[isLatest: true]
</Mermaid>

## Type Definitions

```typescript theme={null}
interface Prompt {
  id: number;
  name: string;
  description: string | null;
  version: string;
  isLatest: boolean;
  systemPrompt: string | null;
  humanPrompt: string | null;
  rawPrompt: string | null;
  inputSchema: any;
  outputSchema: any;
  metadata: any;
  createdAt: string | null;
  updatedAt: string | null;
  createdBy: string | null;
  tags: string[] | null;
}
```

## Method Reference

| Method                              | Description                   | Returns                             |
| ----------------------------------- | ----------------------------- | ----------------------------------- |
| `listPrompts(request?)`             | List all prompts (paginated)  | `PageIterator<ListPromptsResponse>` |
| `createPrompt(body)`                | Create a new prompt           | `Prompt`                            |
| `getPrompt({ id })`                 | Get prompt by ID              | `Prompt`                            |
| `updatePrompt({ id, body })`        | Update prompt fields          | `Prompt`                            |
| `deletePrompt({ id })`              | Delete prompt                 | `PromptSuccessResponse`             |
| `createPromptVersion({ id, body })` | Create new version            | `Prompt`                            |
| `listPromptTags()`                  | List all distinct prompt tags | `string[]`                          |
| `listPromptVersions({ id })`        | List all versions of a prompt | `Prompt[]`                          |