Pull Prompt by Version

(v2)

GET

Retrieves the prompt commit released as version.

GET/v2/prompts/{promptId}/versions/{version}

curl -X GET "https://api.confident-ai.com/v2/prompts/{promptId}/versions/{version}" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"

200

{
  "success": true,
  "data": {
    "text": "Hello, {{name}}! How can I help you today?",
    "alias": "greeting",
    "id": "<COMMIT-ID>",
    "hash": "bab04ce",
    "version": "00.00.01",
    "label": "production",
    "type": "TEXT",
    "interpolationType": "MUSTACHE",
    "modelSettings": {
      "provider": "OPEN_AI",
      "name": "gpt-4o",
      "temperature": 0.7,
      "maxTokens": 1024,
      "topP": 1,
      "topK": 40,
      "frequencyPenalty": 0,
      "presencePenalty": 0,
      "stopSequence": [
        "\n\nHuman:",
        "###"
      ],
      "reasoningEffort": "MINIMAL",
      "verbosity": "LOW"
    },
    "outputType": "TEXT",
    "outputSchema": {
      "title": "Greeting",
      "type": "object",
      "properties": {
        "greeting": {
          "type": "string"
        }
      },
      "required": [
        "greeting"
      ],
      "additionalProperties": false
    },
    "tools": [
      {
        "id": "<TOOL-ID>",
        "name": "get_customer_name",
        "description": "Looks up the customer's name by id.",
        "mode": "ALLOW_ADDITIONAL",
        "version": "00.00.01",
        "schema": {
          "type": "object",
          "properties": {
            "customerId": {
              "type": "string",
              "description": "The id of the customer to look up."
            },
            "nameFormat": {
              "type": "string",
              "enum": [
                "FULL",
                "FIRST"
              ],
              "description": "Whether to return the full name or only the first name."
            }
          },
          "required": [
            "customerId"
          ]
        }
      }
    ]
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

promptIdstringRequired
The unique id of the prompt.
versionstringRequired
The version number of the prompt to pull.

Response

Pull Prompt by Version succeeded.

successboolean
Indicates if the request was successful.
dataobject | object
A single commit of a prompt, as pulled by version, commit hash, or label. It carries text when the prompt is a text prompt and messages when it is a messages prompt, never both.
Show 2 variantsHide 2 variants
- Text Promptobject
  A pulled prompt whose content is a single text template.
  Show 12 propertiesHide 12 properties
  - textstring
    This is the text content of the prompt.
  - aliasstring
    This is the alias of the prompt, which is unique within your project.
  - idstring
    This is the id of the commit pulled, generated by Confident AI, not to be confused with the prompt id, the version number, or the commit hash.
  - hashstring
    This is the commit hash of the prompt pulled.
  - versionstring
    The version number of the prompt, present when the commit pulled has been released as a version.
  - labelstring
    The user-defined label of the version pulled, present when the version carries one.
  - typeenum
    This is the type of the prompt, which can be either a simple text or a list of messages.
    Show 2 enum valuesHide 2 enum values
    TEXT
    LIST
  - interpolationTypeenum
    The type of interpolation format used in the prompt to insert dynamic variables.
    Show 5 enum valuesHide 5 enum values
    MUSTACHE
    MUSTACHE_WITH_SPACE
    FSTRING
    DOLLAR_BRACKETS
    JINJA
  - modelSettingsobject
    This is the model settings the prompt was authored for.
    Show 11 propertiesHide 11 properties
    providerenum
    This is the provider of the model.
    Show 21 enum valuesHide 21 enum values
    OPEN_AI
    CUSTOM
    CONFIDENT_AI
    BEDROCK
    ANTHROPIC
    GEMINI
    X_AI
    DEEPSEEK
    MOONSHOT_AI
    VERTEX_AI
    AZURE
    MISTRAL
    PERPLEXITY
    OPEN_ROUTER
    PORTKEY
    LITE_LLM
    TRUE_FOUNDRY
    HUGGING_FACE
    TYPE_SAFE
    FAL
    Z_AI
    namestring
    This is the name of the model.
    temperaturenumber
    This controls randomness in the model's output. Higher values make output more random.
    maxTokensnumber
    This is the maximum number of tokens to generate.
    topPnumber
    This controls diversity via nucleus sampling. Lower values focus on more likely tokens.
    topKnumber
    This limits sampling to the K most likely tokens at each step.
    frequencyPenaltynumber
    This is the penalty for tokens based on their frequency in the text so far.
    presencePenaltynumber
    This is the penalty for tokens based on whether they appear in the text so far.
    stopSequencelist of strings
    This is the sequences where the model will stop generating further tokens.
    reasoningEffortenum
    This is the level of reasoning effort for the model.
    Show 4 enum valuesHide 4 enum values
    MINIMAL
    LOW
    MEDIUM
    HIGH
    verbosityenum
    This is the verbosity level for model output.
    Show 3 enum valuesHide 3 enum values
    LOW
    MEDIUM
    HIGH
  - outputTypeenum
    The type of output expected from the prompt.
    Show 3 enum valuesHide 3 enum values
    TEXT
    JSON
    SCHEMA
  - outputSchemaobject
    The JSON Schema the prompt's output must match, used when outputType is SCHEMA. It can describe objects (properties and required), arrays (items), and string, integer, number, boolean and null values. title names it, additionalProperties can only be false, and any other keyword is rejected.
  - toolslist of objects
    The tools available to the prompt, at the versions this commit pinned.
    Show 6 propertiesHide 6 properties
    idstring
    The id of the tool, generated by Confident AI.
    namestring
    The name of the tool, unique within the project.
    descriptionstring | null
    What the tool does.
    modeenum
    This is the mode for your tool input fields, which controls whether fields outside the schema are allowed.
    Show 3 enum valuesHide 3 enum values
    ALLOW_ADDITIONAL
    NO_ADDITIONAL
    STRICT
    versionstring
    The version of the tool. A pulled prompt returns the version its commit pinned.
    schemaobject
    The JSON Schema for the tool's input. List each parameter under properties with a type, and name the mandatory ones in required. A parameter can also have a description, an enum of allowed values, or items for an array. Whether extra properties are allowed is set by mode.
- OR
- Messages Promptobject
  A pulled prompt whose content is a list of messages.
  Show 12 propertiesHide 12 properties
  - messageslist of objects
    This is the list of messages that make up the prompt.
    Show 4 propertiesHide 4 properties
    rolestring
    This is the role of the message, which can be user, assistant, system, or developer.
    contentstring
    This is the text content of the message.
    tool_callslist of objects
    Tool calls made by an assistant message, in the OpenAI chat format.
    Show 3 propertiesHide 3 properties
    idstring
    typeenum
    Show 1 enum valueHide 1 enum value
    function
    functionobject
    Show 2 propertiesHide 2 properties
    namestring
    argumentsstring
    JSON-encoded arguments passed to the tool.
    tool_call_idstring
    For tool messages, the id of the assistant tool call this result answers.
  - aliasstring
    This is the alias of the prompt, which is unique within your project.
  - idstring
    This is the id of the commit pulled, generated by Confident AI, not to be confused with the prompt id, the version number, or the commit hash.
  - hashstring
    This is the commit hash of the prompt pulled.
  - versionstring
    The version number of the prompt, present when the commit pulled has been released as a version.
  - labelstring
    The user-defined label of the version pulled, present when the version carries one.
  - typeenum
    This is the type of the prompt, which can be either a simple text or a list of messages.
    Show 2 enum valuesHide 2 enum values
    TEXT
    LIST
  - interpolationTypeenum
    The type of interpolation format used in the prompt to insert dynamic variables.
    Show 5 enum valuesHide 5 enum values
    MUSTACHE
    MUSTACHE_WITH_SPACE
    FSTRING
    DOLLAR_BRACKETS
    JINJA
  - modelSettingsobject
    This is the model settings the prompt was authored for.
    Show 11 propertiesHide 11 properties
    providerenum
    This is the provider of the model.
    Show 21 enum valuesHide 21 enum values
    OPEN_AI
    CUSTOM
    CONFIDENT_AI
    BEDROCK
    ANTHROPIC
    GEMINI
    X_AI
    DEEPSEEK
    MOONSHOT_AI
    VERTEX_AI
    AZURE
    MISTRAL
    PERPLEXITY
    OPEN_ROUTER
    PORTKEY
    LITE_LLM
    TRUE_FOUNDRY
    HUGGING_FACE
    TYPE_SAFE
    FAL
    Z_AI
    namestring
    This is the name of the model.
    temperaturenumber
    This controls randomness in the model's output. Higher values make output more random.
    maxTokensnumber
    This is the maximum number of tokens to generate.
    topPnumber
    This controls diversity via nucleus sampling. Lower values focus on more likely tokens.
    topKnumber
    This limits sampling to the K most likely tokens at each step.
    frequencyPenaltynumber
    This is the penalty for tokens based on their frequency in the text so far.
    presencePenaltynumber
    This is the penalty for tokens based on whether they appear in the text so far.
    stopSequencelist of strings
    This is the sequences where the model will stop generating further tokens.
    reasoningEffortenum
    This is the level of reasoning effort for the model.
    Show 4 enum valuesHide 4 enum values
    MINIMAL
    LOW
    MEDIUM
    HIGH
    verbosityenum
    This is the verbosity level for model output.
    Show 3 enum valuesHide 3 enum values
    LOW
    MEDIUM
    HIGH
  - outputTypeenum
    The type of output expected from the prompt.
    Show 3 enum valuesHide 3 enum values
    TEXT
    JSON
    SCHEMA
  - outputSchemaobject
    The JSON Schema the prompt's output must match, used when outputType is SCHEMA. It can describe objects (properties and required), arrays (items), and string, integer, number, boolean and null values. title names it, additionalProperties can only be false, and any other keyword is rejected.
  - toolslist of objects
    The tools available to the prompt, at the versions this commit pinned.
    Show 6 propertiesHide 6 properties
    idstring
    The id of the tool, generated by Confident AI.
    namestring
    The name of the tool, unique within the project.
    descriptionstring | null
    What the tool does.
    modeenum
    This is the mode for your tool input fields, which controls whether fields outside the schema are allowed.
    Show 3 enum valuesHide 3 enum values
    ALLOW_ADDITIONAL
    NO_ADDITIONAL
    STRICT
    versionstring
    The version of the tool. A pulled prompt returns the version its commit pinned.
    schemaobject
    The JSON Schema for the tool's input. List each parameter under properties with a type, and name the mandatory ones in required. A parameter can also have a description, an enum of allowed values, or items for an array. Whether extra properties are allowed is set by mode.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI