0
# Prompts
1

2
The Prompts API provides management of prompt templates in both text and chat formats, with support for versioning, labels, and configuration. Prompts can be retrieved by name with optional version or label filters.
3

4
## Capabilities
5

6
### PromptsClient
7

8
Client for managing prompt templates.
9

10
```java { .api }
11
/**
12
 * Get a prompt by name
13
 * Optionally filter by version or label
14
 *
15
 * @param promptName Name of the prompt
16
 * @param request Optional version/label filters
17
 * @param requestOptions Optional request configuration
18
 */
19
Prompt get(String promptName);
20
Prompt get(String promptName, GetPromptRequest request);
21
Prompt get(String promptName, GetPromptRequest request, RequestOptions requestOptions);
22

23
/**
24
 * List all prompts with metadata
25
 * Returns prompt names with their versions and labels
26
 *
27
 * @param request Optional filters (name, label, tag, date range, pagination)
28
 * @param requestOptions Optional request configuration
29
 */
30
PromptMetaListResponse list();
31
PromptMetaListResponse list(ListPromptsMetaRequest request);
32
PromptMetaListResponse list(ListPromptsMetaRequest request, RequestOptions requestOptions);
33

34
/**
35
 * Create a new version for a prompt
36
 * Creates a new version with the given name
37
 *
38
 * @param request Prompt definition (text or chat format)
39
 * @param requestOptions Optional request configuration
40
 */
41
Prompt create(CreatePromptRequest request);
42
Prompt create(CreatePromptRequest request, RequestOptions requestOptions);
43
```
44

45
**Usage Examples:**
46

47
```java
48
import com.langfuse.client.LangfuseClient;
49
import com.langfuse.client.resources.prompts.requests.*;
50
import com.langfuse.client.resources.prompts.types.*;
51
import java.util.List;
52

53
LangfuseClient client = LangfuseClient.builder()
54
    .url("https://cloud.langfuse.com")
55
    .credentials("pk-lf-...", "sk-lf-...")
56
    .build();
57

58
// Get latest version of a prompt
59
Prompt prompt = client.prompts().get("summarization-prompt");
60

61
// Get specific version
62
GetPromptRequest request = GetPromptRequest.builder()
63
    .version(2)
64
    .build();
65
Prompt v2 = client.prompts().get("summarization-prompt", request);
66

67
// Get by label
68
GetPromptRequest prodRequest = GetPromptRequest.builder()
69
    .label("production")
70
    .build();
71
Prompt prodPrompt = client.prompts().get("summarization-prompt", prodRequest);
72

73
// List all prompts
74
PromptMetaListResponse prompts = client.prompts().list();
75
for (PromptMeta meta : prompts.getData()) {
76
    System.out.println(meta.getName() + " v" + meta.getVersion());
77
}
78

79
// Create text prompt
80
CreateTextPromptRequest textPrompt = CreateTextPromptRequest.builder()
81
    .name("summarization-prompt")
82
    .prompt("Summarize the following text: {{text}}")
83
    .labels(List.of("production"))
84
    .tags(List.of("summarization", "text"))
85
    .build();
86
Prompt created = client.prompts().create(CreatePromptRequest.text(textPrompt));
87

88
// Create chat prompt
89
CreateChatPromptRequest chatPrompt = CreateChatPromptRequest.builder()
90
    .name("chat-assistant")
91
    .prompt(List.of(
92
        ChatMessage.builder()
93
            .role("system")
94
            .content("You are a helpful assistant.")
95
            .build(),
96
        ChatMessage.builder()
97
            .role("user")
98
            .content("{{user_message}}")
99
            .build()
100
    ))
101
    .labels(List.of("production"))
102
    .build();
103
Prompt chatCreated = client.prompts().create(CreatePromptRequest.chat(chatPrompt));
104
```
105

106
### PromptVersionClient
107

108
Client for updating specific prompt versions.
109

110
```java { .api }
111
/**
112
 * Update labels for a specific prompt version
113
 *
114
 * @param name Prompt name
115
 * @param version Version number
116
 * @param request Update request with new labels
117
 * @param requestOptions Optional request configuration
118
 */
119
Prompt update(String name, int version, UpdatePromptRequest request);
120
Prompt update(String name, int version, UpdatePromptRequest request, RequestOptions requestOptions);
121
```
122

123
**Usage Example:**
124

125
```java
126
import com.langfuse.client.resources.promptversion.requests.UpdatePromptRequest;
127

128
// Update labels for a specific version
129
UpdatePromptRequest updateRequest = UpdatePromptRequest.builder()
130
    .newLabels(List.of("production", "verified"))
131
    .build();
132

133
Prompt updated = client.promptVersion()
134
    .update("summarization-prompt", 2, updateRequest);
135
```
136

137
## Request Types
138

139
### GetPromptRequest
140

141
```java { .api }
142
/**
143
 * Request parameters for getting a prompt
144
 * Use version OR label, not both
145
 */
146
public final class GetPromptRequest {
147
    Optional<Integer> getVersion();  // Specific version number
148
    Optional<String> getLabel();     // Label filter (e.g., "production")
149

150
    static Builder builder();
151
}
152
```
153

154
### ListPromptsMetaRequest
155

156
```java { .api }
157
import java.time.OffsetDateTime;
158

159
/**
160
 * Request parameters for listing prompts
161
 */
162
public final class ListPromptsMetaRequest {
163
    Optional<String> getName();                 // Filter by name
164
    Optional<String> getLabel();                // Filter by label
165
    Optional<String> getTag();                  // Filter by tag
166
    Optional<Integer> getPage();                // Page number (default: 1)
167
    Optional<Integer> getLimit();               // Items per page (default: 50)
168
    Optional<OffsetDateTime> getFromUpdatedAt(); // Filter from this datetime
169
    Optional<OffsetDateTime> getToUpdatedAt();   // Filter until this datetime
170

171
    static Builder builder();
172
}
173
```
174

175
### CreatePromptRequest
176

177
Union type for creating text or chat prompts.
178

179
```java { .api }
180
/**
181
 * Union type for creating prompts
182
 * Use factory methods to create text or chat prompts
183
 */
184
public final class CreatePromptRequest {
185
    static CreatePromptRequest text(CreateTextPromptRequest value);
186
    static CreatePromptRequest chat(CreateChatPromptRequest value);
187

188
    <T> T visit(Visitor<T> visitor);
189
}
190
```
191

192
### CreateTextPromptRequest
193

194
```java { .api }
195
/**
196
 * Request for creating a text prompt
197
 */
198
public final class CreateTextPromptRequest {
199
    String getName();                   // Prompt name
200
    String getPrompt();                 // Prompt template with {{variables}}
201
    Optional<Object> getConfig();       // Custom configuration
202
    Optional<List<String>> getLabels(); // Labels (e.g., "production")
203
    Optional<List<String>> getTags();   // Tags for categorization
204
    Optional<String> getCommitMessage(); // Commit message for this version
205

206
    static Builder builder();
207
}
208
```
209

210
### CreateChatPromptRequest
211

212
```java { .api }
213
/**
214
 * Request for creating a chat prompt
215
 */
216
public final class CreateChatPromptRequest {
217
    String getName();                    // Prompt name
218
    List<ChatMessage> getPrompt();       // Chat messages with roles
219
    Optional<Object> getConfig();        // Custom configuration
220
    Optional<List<String>> getLabels();  // Labels (e.g., "production")
221
    Optional<List<String>> getTags();    // Tags for categorization
222
    Optional<String> getCommitMessage(); // Commit message for this version
223

224
    static Builder builder();
225
}
226
```
227

228
### UpdatePromptRequest
229

230
```java { .api }
231
/**
232
 * Request for updating prompt labels
233
 */
234
public final class UpdatePromptRequest {
235
    List<String> getNewLabels();  // New labels to set
236

237
    static Builder builder();
238
}
239
```
240

241
## Response Types
242

243
### Prompt
244

245
Union type representing text or chat prompts. Use type checking methods and getters to safely access the underlying prompt type.
246

247
```java { .api }
248
/**
249
 * Union type for prompts
250
 * Discriminated by type field: "text" or "chat"
251
 *
252
 * Usage pattern:
253
 *   - Check type with isText() or isChat()
254
 *   - Access with getText() or getChat() which return Optional<T>
255
 *   - Or use visit() for type-safe pattern matching
256
 */
257
public final class Prompt {
258
    // Factory methods
259
    static Prompt text(TextPrompt value);
260
    static Prompt chat(ChatPrompt value);
261

262
    // Type checking
263
    boolean isText();
264
    boolean isChat();
265

266
    // Safe getters (return Optional)
267
    Optional<TextPrompt> getText();
268
    Optional<ChatPrompt> getChat();
269

270
    // Visitor pattern for type-safe access
271
    <T> T visit(Visitor<T> visitor);
272
}
273
```
274

275
**Usage Example:**
276

277
```java
278
Prompt prompt = client.prompts().get("prompt-name");
279

280
// Option 1: Check type and access
281
if (prompt.isText()) {
282
    TextPrompt textPrompt = prompt.getText().orElseThrow();
283
    System.out.println("Text prompt: " + textPrompt.getName());
284
    System.out.println("Template: " + textPrompt.getPrompt());
285
} else if (prompt.isChat()) {
286
    ChatPrompt chatPrompt = prompt.getChat().orElseThrow();
287
    System.out.println("Chat prompt: " + chatPrompt.getName());
288
    for (ChatMessage msg : chatPrompt.getPrompt()) {
289
        System.out.println(msg.getRole() + ": " + msg.getContent());
290
    }
291
}
292

293
// Option 2: Using visitor pattern
294
String promptInfo = prompt.visit(new Prompt.Visitor<String>() {
295
    @Override
296
    public String visitText(TextPrompt text) {
297
        return "Text: " + text.getName();
298
    }
299

300
    @Override
301
    public String visitChat(ChatPrompt chat) {
302
        return "Chat: " + chat.getName() + " with " + chat.getPrompt().size() + " messages";
303
    }
304

305
    @Override
306
    public String _visitUnknown(Object unknownType) {
307
        return "Unknown prompt type";
308
    }
309
});
310
```
311

312
### TextPrompt
313

314
```java { .api }
315
/**
316
 * Text-based prompt
317
 */
318
public final class TextPrompt {
319
    String getName();
320
    int getVersion();
321
    String getPrompt();                       // Template string with {{variables}}
322
    Object getConfig();                       // Custom configuration
323
    List<String> getLabels();
324
    List<String> getTags();
325
    Optional<String> getCommitMessage();      // Commit message
326
    Optional<Map<String, Object>> getResolutionGraph(); // Dependency resolution graph
327

328
    static Builder builder();
329
}
330
```
331

332
### ChatPrompt
333

334
```java { .api }
335
/**
336
 * Chat-based prompt with messages
337
 */
338
public final class ChatPrompt {
339
    String getName();
340
    int getVersion();
341
    List<ChatMessage> getPrompt();            // List of chat messages
342
    Object getConfig();                       // Custom configuration
343
    List<String> getLabels();
344
    List<String> getTags();
345
    Optional<String> getCommitMessage();      // Commit message
346
    Optional<Map<String, Object>> getResolutionGraph(); // Dependency resolution graph
347

348
    static Builder builder();
349
}
350
```
351

352
### ChatMessage
353

354
```java { .api }
355
/**
356
 * Individual chat message in a chat prompt
357
 */
358
public final class ChatMessage {
359
    String getRole();     // "system", "user", "assistant", etc.
360
    String getContent();  // Message content with optional {{variables}}
361

362
    static Builder builder();
363
}
364
```
365

366
### PromptMetaListResponse
367

368
```java { .api }
369
/**
370
 * Paginated list of prompt metadata
371
 */
372
public final class PromptMetaListResponse {
373
    List<PromptMeta> getData();
374
    MetaResponse getMeta();  // Pagination metadata
375

376
    static Builder builder();
377
}
378
```
379

380
### PromptMeta
381

382
```java { .api }
383
/**
384
 * Metadata for a prompt
385
 */
386
public final class PromptMeta {
387
    String getName();
388
    int getVersion();
389
    List<String> getLabels();
390
    List<String> getTags();
391

392
    static Builder builder();
393
}
394
```
395

396
## Complete Prompt Management Example
397

398
```java
399
import com.langfuse.client.LangfuseClient;
400
import com.langfuse.client.resources.prompts.requests.*;
401
import com.langfuse.client.resources.prompts.types.*;
402
import com.langfuse.client.resources.promptversion.requests.UpdatePromptRequest;
403
import java.util.List;
404

405
public class PromptManagementExample {
406
    public static void main(String[] args) {
407
        LangfuseClient client = LangfuseClient.builder()
408
            .url("https://cloud.langfuse.com")
409
            .credentials("pk-lf-...", "sk-lf-...")
410
            .build();
411

412
        // 1. Create a text prompt for summarization
413
        CreateTextPromptRequest textPrompt = CreateTextPromptRequest.builder()
414
            .name("article-summarizer")
415
            .prompt("Summarize the following article in {{max_words}} words or less:\n\n{{article_text}}")
416
            .labels(List.of("development"))
417
            .tags(List.of("summarization", "articles"))
418
            .build();
419

420
        Prompt created = client.prompts().create(CreatePromptRequest.text(textPrompt));
421
        System.out.println("Created prompt v" +
422
            ((TextPrompt) created.visit(Prompt.Visitor.text())).getVersion());
423

424
        // 2. Create a chat prompt for customer support
425
        CreateChatPromptRequest chatPrompt = CreateChatPromptRequest.builder()
426
            .name("support-bot")
427
            .prompt(List.of(
428
                ChatMessage.builder()
429
                    .role("system")
430
                    .content("You are a helpful customer support assistant for {{company_name}}. " +
431
                             "Be professional, empathetic, and concise.")
432
                    .build(),
433
                ChatMessage.builder()
434
                    .role("user")
435
                    .content("{{customer_query}}")
436
                    .build()
437
            ))
438
            .labels(List.of("development"))
439
            .tags(List.of("support", "chat"))
440
            .build();
441

442
        Prompt chatCreated = client.prompts().create(CreatePromptRequest.chat(chatPrompt));
443

444
        // 3. List all prompts
445
        ListPromptsMetaRequest listRequest = ListPromptsMetaRequest.builder()
446
            .limit(10)
447
            .build();
448

449
        PromptMetaListResponse prompts = client.prompts().list(listRequest);
450
        for (PromptMeta meta : prompts.getData()) {
451
            System.out.println("Prompt: " + meta.getName() +
452
                             " v" + meta.getVersion() +
453
                             " Labels: " + meta.getLabels());
454
        }
455

456
        // 4. Get specific prompt by label
457
        GetPromptRequest getRequest = GetPromptRequest.builder()
458
            .label("development")
459
            .build();
460

461
        Prompt devPrompt = client.prompts().get("article-summarizer", getRequest);
462

463
        // 5. Update prompt to production
464
        UpdatePromptRequest updateRequest = UpdatePromptRequest.builder()
465
            .newLabels(List.of("production", "verified"))
466
            .build();
467

468
        Prompt updated = client.promptVersion().update(
469
            "article-summarizer",
470
            1,
471
            updateRequest
472
        );
473

474
        // 6. Get production version
475
        GetPromptRequest prodRequest = GetPromptRequest.builder()
476
            .label("production")
477
            .build();
478

479
        Prompt prodPrompt = client.prompts().get("article-summarizer", prodRequest);
480

481
        // Access prompt template
482
        if (prodPrompt.visit(Prompt.Visitor.text()) != null) {
483
            TextPrompt textPromptData = prodPrompt.visit(Prompt.Visitor.text());
484
            System.out.println("Template: " + textPromptData.getPrompt());
485

486
            // Use template (replace variables manually or with a template engine)
487
            String rendered = textPromptData.getPrompt()
488
                .replace("{{max_words}}", "100")
489
                .replace("{{article_text}}", "...");
490
        }
491
    }
492
}
493
```
494

495
## Best Practices
496

497
1. **Use Labels for Environments**: Tag prompts with labels like "development", "staging", "production"
498
2. **Version Control**: Create new versions instead of updating existing ones for reproducibility
499
3. **Template Variables**: Use `{{variable_name}}` syntax for substitution points
500
4. **Tags for Organization**: Use tags to categorize prompts by use case or feature
501
5. **Commit Messages**: Use commit messages to document changes and rationale for each version
502
6. **Retrieve by Label**: In production, retrieve prompts by label ("production") rather than version number
503
7. **Test Before Promotion**: Test prompts with "development" label before promoting to "production"
504

505
## Related Documentation
506

507
- [Common Types](./common-types.md) - Shared type definitions
508
- [Pagination](./pagination.md) - Pagination utilities
509