--- title: "Create a new Agent Observability prompt version" method: POST path: "/api/v2/llm-obs/v1/prompts/{prompt_id}/versions" tags: ["Agent Observability"] --- # Create a new Agent Observability prompt version `POST /api/v2/llm-obs/v1/prompts/{prompt_id}/versions` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/llm-obs/v1/prompts/{prompt_id}/versions` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a new version of an existing Agent Observability prompt. > **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager. ## Path parameters - `prompt_id` string, required ## Request body - LLMObsCreatePromptVersionRequest: Request to create a new version of an Agent Observability prompt. - `data` LLMObsCreatePromptVersionData, required: Data object for creating an Agent Observability prompt version. - `attributes` LLMObsCreatePromptVersionDataAttributes, required: Attributes for creating a new version of an Agent Observability prompt. `template` is required; all other attributes are optional. If `config` is omitted, the latest version's configuration is carried forward. An explicit empty object clears it. Configuration authoring must be enabled for your organization to supply `config`. Otherwise, supplying it, including an empty object, returns HTTP 403. Omitting `config` still carries forward the latest configuration. - `config` LLMObsPromptConfig: Versioned prompt configuration is in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. Customer-owned configuration delivered with a prompt version. Datadog stores and returns the object without interpolating it, validating provider-specific keys, or applying it to model calls. Do not include secrets. - `description` string: Optional description of this version. - `env_ids` string[]: Optional feature-flag environment UUIDs the service attempts to enable and configure to use this version as their default after creation. - `labels` LLMObsPromptVersionLabel[]: Optional labels to attach to this version. Do not use this attribute for new integrations. - `template` union, required: A text template, a list of chat messages and named message placeholders, or an authored chat object. Text can include an exact prompt version with `{{>prompt-id version=N}}`; other text, including `{{>...}}` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages. **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager. Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - string: A text prompt template. - LLMObsPromptChatTemplateItem[]: A chat prompt template containing messages and optional named message placeholders. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - union: A chat message or a named message placeholder in a prompt template. - LLMObsPromptChatMessage: A single chat message in a prompt template. - … - LLMObsPromptMessagePlaceholder: A named placeholder that inserts a list of messages when a compatible SDK formats the prompt. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - … - LLMObsPromptAuthoringMessagesTemplate: A chat prompt whose authored items are stored under `messages`. - `messages` LLMObsPromptAuthoringItem[], required: A chat prompt containing messages, references to specific versions of other prompts, or both. - union: A chat message or a reference to a specific version of another prompt. A chat message must not contain an `include` field; the API rejects items that combine both forms. - … - `user_version` string: Optional user-supplied version identifier for this version. - `type` 'prompt-template-versions', required: Resource type of an Agent Observability prompt version. ## Response `200` OK - LLMObsPromptVersionResponse: Response containing a specific version of an Agent Observability prompt. - `data` LLMObsPromptVersionData, required: Data object for a specific version of an Agent Observability prompt. - `attributes` LLMObsPromptVersionDataAttributes, required: Attributes of a specific version of an Agent Observability prompt. For a composed version, `authoring_template` contains its pinned include-bearing source; ordinary versions omit that attribute. Empty `config` is omitted when configuration authoring is disabled for the organization. Non-empty saved configuration is always returned. - `author` string: UUID of the user who authored this version. - `authoring_template` union: A text template, a list of chat messages and named message placeholders, or an authored chat object. Text can include an exact prompt version with `{{>prompt-id version=N}}`; other text, including `{{>...}}` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages. **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager. Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - string: A text prompt template. - LLMObsPromptChatTemplateItem[]: A chat prompt template containing messages and optional named message placeholders. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - union: A chat message or a named message placeholder in a prompt template. - LLMObsPromptChatMessage: A single chat message in a prompt template. - … - LLMObsPromptMessagePlaceholder: A named placeholder that inserts a list of messages when a compatible SDK formats the prompt. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - … - LLMObsPromptAuthoringMessagesTemplate: A chat prompt whose authored items are stored under `messages`. - `messages` LLMObsPromptAuthoringItem[], required: A chat prompt containing messages, references to specific versions of other prompts, or both. - union: A chat message or a reference to a specific version of another prompt. A chat message must not contain an `include` field; the API rejects items that combine both forms. - … - `config` LLMObsPromptConfig: Versioned prompt configuration is in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. Customer-owned configuration delivered with a prompt version. Datadog stores and returns the object without interpolating it, validating provider-specific keys, or applying it to model calls. Do not include secrets. - `created_at` string, date-time: Timestamp stored on this prompt version. - `datasets` LLMObsPromptDataset[]: Datasets observed in runs associated with this prompt version. - `id` string, required: Unique identifier of the dataset. - `name` string: Name of the dataset. - `description` string: Description of this version. - `labels` string[]: Labels attached to this version (for example `development`, `staging`, `production`). - `last_seen_at` string, date-time: Timestamp of the most recent observed run of this prompt version. - `ml_app` string: The ML application this prompt is associated with. - `ml_apps` string[]: ML applications observed running this prompt version. - `prompt_id` string, required: Customer-provided identifier of the parent prompt. - `prompt_uuid` string, required: Unique identifier of the parent prompt. - `tags` string[]: Tags observed on runs of this prompt version. - `template` union, required: A text template, a list of chat messages and named message placeholders, or an authored chat object. Text can include an exact prompt version with `{{>prompt-id version=N}}`; other text, including `{{>...}}` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages. **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager. Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - string: A text prompt template. - LLMObsPromptChatTemplateItem[]: A chat prompt template containing messages and optional named message placeholders. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - union: A chat message or a named message placeholder in a prompt template. - LLMObsPromptChatMessage: A single chat message in a prompt template. - … - LLMObsPromptMessagePlaceholder: A named placeholder that inserts a list of messages when a compatible SDK formats the prompt. **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager. - … - LLMObsPromptAuthoringMessagesTemplate: A chat prompt whose authored items are stored under `messages`. - `messages` LLMObsPromptAuthoringItem[], required: A chat prompt containing messages, references to specific versions of other prompts, or both. - union: A chat message or a reference to a specific version of another prompt. A chat message must not contain an `include` field; the API rejects items that combine both forms. - … - `user_version` string: User-supplied identifier for this version. - `version` integer, required: Sequential version number. - `version_created_at` string, date-time: Timestamp when this version was created. - `id` string, required: Unique identifier of the prompt version. - `type` 'prompt-template-versions', required: Resource type of an Agent Observability prompt version. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `429`: Too many requests --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)