---
title: "Create or replace prompt"
method: PUT
path: "/v1/prompt"
tags: ["Prompts"]
---

# Create or replace prompt

`PUT /v1/prompt`

Create or replace prompt. If there is an existing prompt in the project with the same slug as the one specified in the request, will replace the existing prompt with the provided fields

## Request body

- CreatePrompt
  - `project_id` string, uuid, required — Unique identifier for the project that the prompt belongs under
  - `name` string, required — Name of the prompt
  - `slug` string, required — Unique identifier for the prompt
  - `description` string, nullable — Textual description of the prompt
  - `prompt_data` PromptData, nullable — The prompt, model, and its parameters
    - `prompt` union
      - object
        - `type` 'completion', required
        - `content` string, required
      - object
        - `type` 'chat', required
        - `messages` ChatCompletionMessageParam[], required
          - union
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - `tools` string
      - object, nullable
    - `options` object, nullable
      - `model` string
      - `params` union
        - object
          - `use_cache` boolean
          - `temperature` number
          - `top_p` number
          - `max_tokens` number
          - `frequency_penalty` number
          - `presence_penalty` number
          - `response_format` object, nullable
            - `type` 'json_object', required
          - `tool_choice` union
            - 'auto'
            - 'none'
            - object
              - …
          - `function_call` union
            - 'auto'
            - 'none'
            - object
              - …
          - `n` number
          - `stop` string[]
        - object
          - `use_cache` boolean
          - `max_tokens` number, required
          - `temperature` number, required
          - `top_p` number
          - `top_k` number
          - `stop_sequences` string[]
          - `max_tokens_to_sample` number — This is a legacy parameter that should not be used.
        - object
          - `use_cache` boolean
          - `temperature` number
          - `maxOutputTokens` number
          - `topP` number
          - `topK` number
        - object
          - `use_cache` boolean
          - `temperature` number
          - `topK` number
        - object
          - `use_cache` boolean
      - `position` string
    - `parser` object, nullable
      - `type` 'llm_classifier', required
      - `use_cot` boolean, required
      - `choice_scores` object, required
    - `tool_functions` SavedFunctionId[], nullable
      - union
        - object
          - `type` 'function', required
          - `id` string, required
        - object
          - `type` 'global', required
          - `name` string, required
    - `origin` object, nullable
      - `prompt_id` string
      - `project_id` string
      - `prompt_version` string
  - `tags` string[], nullable — A list of tags for the prompt
  - `function_type` 'llm' | 'scorer' | 'task' | 'tool' | 'null', nullable

## Response `200`

Returns the new prompt object

- Prompt
  - `id` string, uuid, required — Unique identifier for the prompt
  - `_xact_id` string, required — The transaction id of an event is unique to the network operation that processed the event insertion. Transaction ids are monotonically increasing over time and can be used to retrieve a versioned snapshot of the prompt (see the `version` parameter)
  - `project_id` string, uuid, required — Unique identifier for the project that the prompt belongs under
  - `log_id` 'p', required — A literal 'p' which identifies the object as a project prompt
  - `org_id` string, uuid, required — Unique identifier for the organization
  - `name` string, required — Name of the prompt
  - `slug` string, required — Unique identifier for the prompt
  - `description` string, nullable — Textual description of the prompt
  - `created` string, date-time, nullable — Date of prompt creation
  - `prompt_data` PromptData, nullable — The prompt, model, and its parameters
    - `prompt` union
      - object
        - `type` 'completion', required
        - `content` string, required
      - object
        - `type` 'chat', required
        - `messages` ChatCompletionMessageParam[], required
          - union
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - `tools` string
      - object, nullable
    - `options` object, nullable
      - `model` string
      - `params` union
        - object
          - `use_cache` boolean
          - `temperature` number
          - `top_p` number
          - `max_tokens` number
          - `frequency_penalty` number
          - `presence_penalty` number
          - `response_format` object, nullable
            - `type` 'json_object', required
          - `tool_choice` union
            - 'auto'
            - 'none'
            - object
              - …
          - `function_call` union
            - 'auto'
            - 'none'
            - object
              - …
          - `n` number
          - `stop` string[]
        - object
          - `use_cache` boolean
          - `max_tokens` number, required
          - `temperature` number, required
          - `top_p` number
          - `top_k` number
          - `stop_sequences` string[]
          - `max_tokens_to_sample` number — This is a legacy parameter that should not be used.
        - object
          - `use_cache` boolean
          - `temperature` number
          - `maxOutputTokens` number
          - `topP` number
          - `topK` number
        - object
          - `use_cache` boolean
          - `temperature` number
          - `topK` number
        - object
          - `use_cache` boolean
      - `position` string
    - `parser` object, nullable
      - `type` 'llm_classifier', required
      - `use_cot` boolean, required
      - `choice_scores` object, required
    - `tool_functions` SavedFunctionId[], nullable
      - union
        - object
          - `type` 'function', required
          - `id` string, required
        - object
          - `type` 'global', required
          - `name` string, required
    - `origin` object, nullable
      - `prompt_id` string
      - `project_id` string
      - `prompt_version` string
  - `tags` string[], nullable — A list of tags for the prompt
  - `metadata` object, nullable — User-controlled metadata about the prompt
  - `function_type` 'llm' | 'scorer' | 'task' | 'tool' | 'null', nullable

## Other responses

- `400` — The request was unacceptable, often due to missing a required parameter
- `401` — No valid API key provided
- `403` — The API key doesn’t have permissions to perform the request
- `429` — Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500` — Something went wrong on Braintrust's end. (These are rare.)

---

[API](https://skmtc.net/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.net/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/9d216c8243fe/schema)