For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sign inBook a demo
DocsReferenceChangelog
DocsReferenceChangelog
  • Introduction
    • Overview
    • Errors
  • SDK
    • Overview
    • Decorators
    • Run Evaluation
  • API
      • POSTLog to a Prompt
      • PATCHUpdate Prompt Log
      • STREAMCall Prompt
      • GETList Prompts
      • POSTUpsert Prompt
      • GETGet Prompt
      • DELDelete Prompt
      • PATCHMove Prompt
      • POSTPopulate Prompt template
      • GETList Versions of a Prompt
      • DELDelete Prompt Version
      • PATCHUpdate Prompt Version
      • POSTDeploy Prompt
      • DELRemove Deployment
      • GETList a Prompt's Environments
      • POSTUpdate Monitoring
      • GETSerialize
      • POSTDeserialize
LogoLogo
Sign inBook a demo
APIPrompts

Populate Prompt template

POST
https://api.humanloop.com/v5/prompts/:id/populate
POST
/v5/prompts/:id/populate
$curl -X POST https://api.humanloop.com/v5/prompts/id/populate \
>     -H "X-API-KEY: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "key": "value"
>}'
1{
2  "path": "path",
3  "id": "id",
4  "model": "model",
5  "name": "name",
6  "version_id": "version_id",
7  "created_at": "2024-01-15T09:30:00Z",
8  "updated_at": "2024-01-15T09:30:00Z",
9  "last_used_at": "2024-01-15T09:30:00Z",
10  "version_logs_count": 1,
11  "total_logs_count": 1,
12  "inputs": [
13    {
14      "name": "name"
15    }
16  ],
17  "directory_id": "directory_id",
18  "endpoint": "complete",
19  "template": "template",
20  "template_language": "default",
21  "provider": "anthropic",
22  "max_tokens": 1,
23  "temperature": 1.1,
24  "top_p": 1.1,
25  "stop": "stop",
26  "presence_penalty": 1.1,
27  "frequency_penalty": 1.1,
28  "other": {
29    "key": "value"
30  },
31  "seed": 1,
32  "response_format": {
33    "type": "json_object",
34    "json_schema": {
35      "key": "value"
36    }
37  },
38  "reasoning_effort": "high",
39  "tools": [
40    {
41      "name": "name",
42      "description": "description",
43      "strict": true,
44      "parameters": {
45        "key": "value"
46      }
47    }
48  ],
49  "linked_tools": [
50    {
51      "name": "name",
52      "description": "description",
53      "id": "id",
54      "version_id": "version_id",
55      "strict": true,
56      "parameters": {
57        "key": "value"
58      }
59    }
60  ],
61  "attributes": {
62    "key": "value"
63  },
64  "version_name": "version_name",
65  "version_description": "version_description",
66  "description": "description",
67  "tags": [
68    "tags"
69  ],
70  "readme": "readme",
71  "schema": {
72    "key": "value"
73  },
74  "type": "prompt",
75  "environments": [
76    {
77      "id": "id",
78      "created_at": "2024-01-15T09:30:00Z",
79      "name": "name",
80      "tag": "default"
81    }
82  ],
83  "created_by": {
84    "id": "id",
85    "email_address": "email_address",
86    "full_name": "full_name"
87  },
88  "evaluators": [
89    {
90      "version_reference": {
91        "file": {
92          "path": "path",
93          "id": "id",
94          "model": "model",
95          "name": "name",
96          "version_id": "version_id",
97          "created_at": "2024-01-15T09:30:00Z",
98          "updated_at": "2024-01-15T09:30:00Z",
99          "last_used_at": "2024-01-15T09:30:00Z",
100          "version_logs_count": 1,
101          "total_logs_count": 1,
102          "inputs": [
103            {
104              "name": "name"
105            }
106          ]
107        },
108        "environment": {
109          "id": "id",
110          "created_at": "2024-01-15T09:30:00Z",
111          "name": "name",
112          "tag": "default"
113        },
114        "type": "environment"
115      },
116      "state": "active",
117      "created_at": "2024-01-15T09:30:00Z",
118      "updated_at": "2024-01-15T09:30:00Z",
119      "version": {
120        "path": "path",
121        "id": "id",
122        "spec": {
123          "arguments_type": "target_free",
124          "return_type": "boolean",
125          "evaluator_type": "llm"
126        },
127        "name": "name",
128        "version_id": "version_id",
129        "created_at": "2024-01-15T09:30:00Z",
130        "updated_at": "2024-01-15T09:30:00Z",
131        "last_used_at": "2024-01-15T09:30:00Z",
132        "version_logs_count": 1,
133        "total_logs_count": 1,
134        "inputs": [
135          {
136            "name": "name"
137          }
138        ]
139      }
140    }
141  ],
142  "evaluator_aggregates": [
143    {
144      "value": 1.1,
145      "evaluator_id": "evaluator_id",
146      "evaluator_version_id": "evaluator_version_id",
147      "created_at": "2024-01-15T09:30:00Z",
148      "updated_at": "2024-01-15T09:30:00Z"
149    }
150  ],
151  "raw_file_content": "raw_file_content",
152  "populated_template": "populated_template"
153}

Retrieve the Prompt with the given ID, including the populated template.

By default, the deployed version of the Prompt is returned. Use the query parameters version_id or environment to target a specific version of the Prompt.

Was this page helpful?
Previous

List Versions of a Prompt

Next
Built with

Authentication

X-API-KEYstring
API Key authentication via header

Path parameters

idstringRequired
Unique identifier for Prompt.

Query parameters

version_idstringOptional
A specific Version ID of the Prompt to retrieve to populate the template.
environmentstringOptional
Name of the Environment to retrieve a deployed Version from to populate the template.

Request

This endpoint expects a map from strings to any.

Response

Successful Response
pathstring
Path of the Prompt, including the name, which is used as a unique identifier.
idstring
Unique identifier for the Prompt.
modelstring

The model instance used, e.g. gpt-4. See supported models

namestring
Name of the Prompt.
version_idstring
Unique identifier for the specific Prompt Version. If no query params provided, the default deployed Prompt Version is returned.
created_atdatetime
updated_atdatetime
last_used_atdatetime
version_logs_countinteger
The number of logs that have been generated for this Prompt Version
total_logs_countinteger
The number of logs that have been generated across all Prompt Versions
inputslist of objects
Inputs associated to the Prompt. Inputs correspond to any of the variables used within the Prompt template.
directory_idstring
ID of the directory that the file is in on Humanloop.
endpointenum
The provider model endpoint used.
Allowed values:
templatestring or list of objects

The template contains the main structure and instructions for the model, including input variables for dynamic values.

For chat models, provide the template as a ChatTemplate (a list of messages), e.g. a system message, followed by a user message with an input variable. For completion models, provide a prompt template as a string.

Input variables should be specified with double curly bracket syntax: {{input_name}}.

template_languageenum
The template language to use for rendering the template.
Allowed values:
providerenum
The company providing the underlying model service.
max_tokensintegerDefaults to -1

The maximum number of tokens to generate. Provide max_tokens=-1 to dynamically calculate the maximum number of tokens to generate given the length of the prompt

temperaturedoubleDefaults to 1
What sampling temperature to use when making a generation. Higher values means the model will be more creative.
top_pdoubleDefaults to 1

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.

stopstring or list of strings

The string (or list of strings) after which the model will stop generating. The returned text will not contain the stop sequence.

presence_penaltydoubleDefaults to 0

Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the generation so far.

frequency_penaltydoubleDefaults to 0

Number between -2.0 and 2.0. Positive values penalize new tokens based on how frequently they appear in the generation so far.

othermap from strings to any
Other parameter values to be passed to the provider call.
seedinteger
If specified, model will make a best effort to sample deterministically, but it is not guaranteed.
response_formatobject

The format of the response. Only {"type": "json_object"} is currently supported for chat.

reasoning_effortenum or integer

Guidance on how many reasoning tokens it should generate before creating a response to the prompt. OpenAI reasoning models (o1, o3-mini) expect a OpenAIReasoningEffort enum. Anthropic reasoning models expect an integer, which signifies the maximum token budget.

toolslist of objects
The tool specification that the model can choose to call if Tool calling is supported.
linked_toolslist of objects
The tools linked to your prompt that the model can call.
attributesmap from strings to any
Additional fields to describe the Prompt. Helpful to separate Prompt versions from each other with details on how they were created or used.
version_namestring
Unique name for the Prompt version. Version names must be unique for a given Prompt.
version_descriptionstring
Description of the version, e.g., the changes made in this version.
descriptionstring
Description of the Prompt.
tagslist of strings
List of tags associated with the file.
readmestring
Long description of the file.
schemamap from strings to any
The JSON schema for the Prompt.
type"prompt"
environmentslist of objects
The list of environments the Prompt Version is deployed to.
created_byany
The user who created the Prompt.
evaluatorslist of objects
Evaluators that have been attached to this Prompt that are used for monitoring logs.
evaluator_aggregateslist of objects
Aggregation of Evaluator results for the Prompt Version.
raw_file_contentstring
The raw content of the Prompt. Corresponds to the .prompt file.
populated_templatestring or list of objects
The template populated with the input values you provided in the request. Returns None if no template exists.

Errors

422
Populate Prompts ID Populate Post Request Unprocessable Entity Error