--- title: "Create an Agent Observability prompt" method: POST path: "/api/v2/llm-obs/v1/prompts" tags: ["Agent Observability"] --- # Create an Agent Observability prompt `POST /api/v2/llm-obs/v1/prompts` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/llm-obs/v1/prompts` - 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 prompt (and its first version) in the Agent Observability prompt registry. > **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager. ## Request body - LLMObsCreatePromptRequest: Request to create an Agent Observability prompt. - `data` LLMObsCreatePromptData, required: Data object for creating an Agent Observability prompt. - `attributes` LLMObsCreatePromptDataAttributes, required: Attributes for creating an Agent Observability prompt and its first version. `prompt_id` and `template` are required; all other attributes are optional. If `config` is omitted, the first version stores an empty object. Configuration authoring must be enabled for your organization to supply `config`. Otherwise, supplying it, including an empty object, returns HTTP 403. - `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 the prompt. - `env_ids` string[]: Optional feature-flag environment UUIDs the service attempts to enable and configure to use the first version as their default after creation. - `labels` LLMObsPromptVersionLabel[]: Optional labels to attach to the first version. Do not use this attribute for new integrations. - `prompt_id` string, required: Customer-provided identifier for the new prompt. - `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. - … - `title` string: Optional title of the prompt. - `user_version` string: Optional user-supplied version identifier for the first version. - `type` 'prompt-templates', required: Resource type of an Agent Observability prompt. ## Response `200` OK - LLMObsCreatePromptResponse: Response returned after creating an Agent Observability prompt. - `data` LLMObsCreatePromptResponseData, required: Data object returned after creating an Agent Observability prompt. - `attributes` LLMObsCreatePromptResponseDataAttributes, required: Attributes returned after creating an Agent Observability prompt and its first version. 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 the prompt. - `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 when the prompt was created. - `created_from` string, required: Source that created the prompt, such as `ui-registry`, `sdk-registry`, or `sdk-instrumentation`. - `datasets` LLMObsPromptDataset[]: Datasets observed in runs associated with this prompt. - `id` string, required: Unique identifier of the dataset. - `name` string: Name of the dataset. - `description` string: Description of the prompt. - `extracted_from` string: Source prompt from which this prompt was extracted, when applicable. - `in_registry` boolean, required: Whether the prompt is a registry entry (as opposed to a code-discovered prompt). - `last_seen_at` string, date-time: Timestamp of the most recent observed run of this prompt. - `last_version_created_at` string, date-time: Timestamp when the most recent version of the prompt was created. - `ml_app` string: The ML application this prompt is associated with. - `ml_apps` string[]: ML applications observed running this prompt. - `num_versions` integer, required: Number of versions of the prompt. - `prompt_id` string, required: Customer-provided identifier of the prompt. - `source` 'registry' | 'code', required: Whether the prompt was created from the registry or discovered from observed LLM calls. - `tags` string[]: Tags observed on runs of this prompt. - `title` string: Title of the prompt. - `id` string, required: Unique identifier of the prompt. - `type` 'prompt-templates', required: Resource type of an Agent Observability prompt. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `409`: Conflict - `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)