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

# Prompts

# PromptsClient

`adaline.prompts` creates, reads, updates, and deletes prompts. Related prompt-scoped resources — drafts, playgrounds, evaluators, and evaluations — are exposed through nested sub-clients.

## Access

```typescript theme={null}
import { Adaline } from '@adaline/client';

const adaline = new Adaline();
const prompts = adaline.prompts; // PromptsClient
```

The class is also exported directly:

```typescript theme={null}
import { PromptsClient } from '@adaline/client';
```

## Sub-clients

`PromptsClient` exposes four nested namespaces — evaluators and evaluations are here (not at the top level) because every URL is `/prompts/{promptId}/...`:

| Property                      | Client                                                                               | Covers                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `adaline.prompts.draft`       | [`PromptDraftClient`](/docs/reference/sdk/v2/typescript/classes/prompt-draft)             | Get the current draft                                                     |
| `adaline.prompts.playgrounds` | [`PromptPlaygroundsClient`](/docs/reference/sdk/v2/typescript/classes/prompt-playgrounds) | List / get playgrounds                                                    |
| `adaline.prompts.evaluators`  | [`PromptEvaluatorsClient`](/docs/reference/sdk/v2/typescript/classes/prompt-evaluators)   | CRUD for evaluators attached to the prompt                                |
| `adaline.prompts.evaluations` | [`PromptEvaluationsClient`](/docs/reference/sdk/v2/typescript/classes/prompt-evaluations) | Create / list / cancel evaluation runs (+ `.results` for per-row results) |

Types used below come from `@adaline/api`:

```typescript theme={null}
import type {
  Prompt,
  CreatePromptRequest,
  PatchPromptRequest,
  ListPromptsResponse,
  SortOrder,
} from '@adaline/api';
```

[`Prompt`](/docs/reference/api/v2/openapi/get-prompt) embeds a [`PromptSnapshot`](/docs/reference/sdk/v2/typescript/types/PromptSnapshot) with the latest config, [`PromptMessage[]`](/docs/reference/sdk/v2/typescript/types/PromptMessage), [`ToolFunction[]`](/docs/reference/sdk/v2/typescript/types/ToolFunction), and [`PromptVariable[]`](/docs/reference/sdk/v2/typescript/types/PromptVariable).

***

## list()

List all prompts in a project (paginated). Use `fields` to trim the response payload.

```typescript theme={null}
list(options: {
  projectId: string;
  limit?: number;
  cursor?: string;
  sort?: SortOrder;
  createdAfter?: number;
  createdBefore?: number;
  fields?: string;
}): Promise<ListPromptsResponse>
```

### Parameters

| Name            | Type        | Required | Description                                                                        |
| --------------- | ----------- | -------- | ---------------------------------------------------------------------------------- |
| `projectId`     | `string`    | Yes      | Project whose prompts should be returned.                                          |
| `limit`         | `number`    | No       | Page size (default 50, max 200).                                                   |
| `cursor`        | `string`    | No       | Opaque cursor from a previous response's `pagination.nextCursor`.                  |
| `sort`          | `SortOrder` | No       | `"createdAt:asc"` or `"createdAt:desc"`.                                           |
| `createdAfter`  | `number`    | No       | Unix milliseconds.                                                                 |
| `createdBefore` | `number`    | No       | Unix milliseconds.                                                                 |
| `fields`        | `string`    | No       | Comma-separated list of top-level fields to include (e.g. `"id,title,createdAt"`). |

### Returns

`Promise<ListPromptsResponse>` with shape `{ data: Prompt[]; pagination: { limit, returned, hasMore, nextCursor } }`.

### Example

```typescript theme={null}
const { data, pagination } = await adaline.prompts.list({
  projectId: 'project_abc123',
  limit: 50,
  sort: 'createdAt:desc',
  fields: 'id,title,createdAt',
});
```

***

## create()

Create a new prompt in a project. The optional `draft` seeds the prompt's initial config, messages, and tools.

```typescript theme={null}
create(options: { prompt: CreatePromptRequest }): Promise<Prompt>
```

### Parameters

| Name     | Type                                                             | Required | Description        |
| -------- | ---------------------------------------------------------------- | -------- | ------------------ |
| `prompt` | [`CreatePromptRequest`](/docs/reference/api/v2/openapi/create-prompt) | Yes      | Prompt definition. |

[`CreatePromptRequest`](/docs/reference/api/v2/openapi/create-prompt) (abbreviated):

```typescript theme={null}
interface CreatePromptRequest {
  projectId: string;
  title: string;
  icon?: BaseEntityIcon;
  draft?: {
    config: PromptSnapshotConfig;
    messages: PromptMessage[];
    tools?: ToolFunction[];
  };
}
```

* `config` — see [PromptSnapshotConfig](/docs/reference/sdk/v2/typescript/types/PromptSnapshotConfig)
* `messages` — see [PromptMessage](/docs/reference/sdk/v2/typescript/types/PromptMessage) and the [MessageContent](/docs/reference/sdk/v2/typescript/types/MessageContent) union
* `tools` — see [ToolFunction](/docs/reference/sdk/v2/typescript/types/ToolFunction)

### Returns

`Promise<Prompt>` — the created prompt, including server-generated `id` and draft state.

### Example

```typescript theme={null}
const prompt = await adaline.prompts.create({
  prompt: {
    projectId: 'project_abc123',
    title: 'Customer support triage',
    icon: { type: 'emoji', value: '🎧' },
    draft: {
      config: {
        provider: 'openai',
        model: 'gpt-4o',
        settings: { temperature: 0.3 },
      },
      messages: [
        {
          role: 'system',
          content: [{ modality: 'text', value: 'You are a helpful triage assistant.' }],
        },
      ],
    },
  },
});

console.log(`Created prompt ${prompt.id}`);
```

***

## get()

Retrieve a single prompt by ID. Use `expand: 'playground'` to include the default playground inline. Use `fields` to trim the response.

```typescript theme={null}
get(options: {
  promptId: string;
  expand?: 'playground';
  fields?: string;
}): Promise<Prompt>
```

### Parameters

| Name       | Type           | Required | Description                                          |
| ---------- | -------------- | -------- | ---------------------------------------------------- |
| `promptId` | `string`       | Yes      | Prompt identifier.                                   |
| `expand`   | `'playground'` | No       | Include the default playground in the response.      |
| `fields`   | `string`       | No       | Comma-separated list of top-level fields to include. |

### Returns

`Promise<Prompt>` — full prompt with config, messages, tools, variables, and (if requested) playground data.

### Example

```typescript theme={null}
const prompt = await adaline.prompts.get({
  promptId: 'prompt_abc123',
  expand: 'playground',
});

console.log(`Model: ${prompt.config.provider}/${prompt.config.model}`);
console.log(`Messages: ${prompt.messages.length}`);
```

***

## update()

Partially update a prompt. You can update title, icon, config, messages, tools, or the default playground. Any field you omit is left untouched. Sent as `PATCH` under the hood.

```typescript theme={null}
update(options: {
  promptId: string;
  playgroundId?: string;
  prompt: PatchPromptRequest;
}): Promise<Prompt>
```

### Parameters

| Name           | Type                                                            | Required | Description                                                                    |
| -------------- | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `promptId`     | `string`                                                        | Yes      | Prompt identifier.                                                             |
| `playgroundId` | `string`                                                        | No       | When patching playground-scoped fields, identifies which playground to update. |
| `prompt`       | [`PatchPromptRequest`](/docs/reference/api/v2/openapi/update-prompt) | Yes      | Fields to update — all top-level keys are optional.                            |

### Returns

`Promise<Prompt>` — the full updated prompt.

### Example

```typescript theme={null}
const updated = await adaline.prompts.update({
  promptId: 'prompt_abc123',
  prompt: {
    title: 'Renamed prompt',
    config: {
      provider: 'openai',
      model: 'gpt-4o-mini',
      settings: { temperature: 0.7 },
    },
  },
});
```

***

## delete()

Permanently delete a prompt and all associated resources (drafts, playgrounds, deployments, evaluators, evaluations). Irreversible.

```typescript theme={null}
delete(options: { promptId: string }): Promise<void>
```

### Example

```typescript theme={null}
await adaline.prompts.delete({ promptId: 'prompt_abc123' });
```

***

## See Also

* [PromptDraftClient](/docs/reference/sdk/v2/typescript/classes/prompt-draft) — `adaline.prompts.draft.get(...)`
* [PromptPlaygroundsClient](/docs/reference/sdk/v2/typescript/classes/prompt-playgrounds) — `adaline.prompts.playgrounds.*`
* [PromptEvaluatorsClient](/docs/reference/sdk/v2/typescript/classes/prompt-evaluators) — `adaline.prompts.evaluators.*`
* [PromptEvaluationsClient](/docs/reference/sdk/v2/typescript/classes/prompt-evaluations) — `adaline.prompts.evaluations.*`
* [Adaline class](/docs/reference/sdk/v2/typescript/classes/adaline) — constructor and top-level methods
* [PromptSnapshot](/docs/reference/sdk/v2/typescript/types/PromptSnapshot) — the shape of `prompt.config` / messages / tools / variables
* API reference: [List prompts](/docs/reference/api/v2/openapi/list-prompts) · [Create](/docs/reference/api/v2/openapi/create-prompt) · [Get](/docs/reference/api/v2/openapi/get-prompt) · [Update](/docs/reference/api/v2/openapi/update-prompt) · [Delete](/docs/reference/api/v2/openapi/delete-prompt)