> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompt templates
> Manage versioned prompt templates with change history, rollback, and variable rendering through the Prompts API.
The Prompts API lets you store, version, and manage prompt templates centrally.
Every template change creates an immutable version, giving you a full change history
with the ability to roll back to any previous version at any time.
Templates support `{{variable}}` placeholders that are rendered server-side when you
retrieve a prompt, so you can reuse the same template across different contexts.
## Create a prompt
Create a prompt with a name and template. The first version is created automatically.
```ts TypeScript SDK theme={null}
import { SDK } from '@meetkai/mka1';
const sdk = new SDK({ bearerAuth: 'Bearer ' });
const result = await sdk.llm.prompts.create({
xOnBehalfOf: '', // optional — attribute the request to one of your end users
createPromptRequest: {
name: 'greeting',
description: 'A simple greeting template',
template: 'Hello, {{name}}! Welcome to {{company}}.',
metadata: { team: 'onboarding' },
},
});
console.log(result.id); // prompt_abc123...
console.log(result.activeVersion); // 1
console.log(result.version?.version); // 1
const promptId = result.id; // used in the examples below
```
```python Python SDK theme={null}
from meetkai_mka1 import SDK
sdk = SDK(bearer_auth="Bearer ")
result = sdk.llm.prompts.create(
name="greeting",
description="A simple greeting template",
template="Hello, {{name}}! Welcome to {{company}}.",
metadata={"team": "onboarding"},
)
print(result.id) # prompt_abc123...
print(result.active_version) # 1
print(result.version.version) # 1
```
```csharp C# SDK theme={null}
using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using MeetKai.MKA1.Types.Requests;
var sdk = new SDK(bearerAuth: "Bearer ");
var result = await sdk.Llm.Prompts.CreateAsync(
new CreatePromptRequest
{
Name = "greeting",
Description = "A simple greeting template",
Template = "Hello, {{name}}! Welcome to {{company}}.",
Metadata = new Dictionary { { "team", "onboarding" } },
}
);
Console.WriteLine(result.CreatePromptResponseValue!.Id); // prompt_abc123...
Console.WriteLine(result.CreatePromptResponseValue!.ActiveVersion); // 1
Console.WriteLine(result.CreatePromptResponseValue!.Version!.Version); // 1
```
```bash CLI theme={null}
mka1 llm prompts create \
--body '{
"name": "greeting",
"description": "A simple greeting template",
"template": "Hello, {{name}}! Welcome to {{company}}.",
"metadata": { "team": "onboarding" }
}' \
-H 'X-On-Behalf-Of: '
```
```bash Bash theme={null}
curl https://apigw.mka1.com/api/v1/llm/prompts \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: ' \
--data '{
"name": "greeting",
"description": "A simple greeting template",
"template": "Hello, {{name}}! Welcome to {{company}}.",
"metadata": { "team": "onboarding" }
}'
```
## Retrieve a prompt with rendered variables
Pass `variables` as a query parameter to render the template with your values.
Unmatched placeholders are left as-is.
Optionally, pass `version` to retrieve (and render) a specific version. If omitted,
the active version is returned.
The response always includes `active_template` (`activeTemplate` in the TypeScript SDK) — the raw
template text of the requested version, with `{{placeholders}}` intact. When you pass `variables`,
the response also includes `rendered_template` (`renderedTemplate`) with the substituted result;
it is absent when no variables are provided.
```ts TypeScript SDK theme={null}
const prompt = await sdk.llm.prompts.get({
xOnBehalfOf: '',
id: promptId,
variables: JSON.stringify({ name: 'Alice', company: 'Acme' }),
});
console.log(prompt.renderedTemplate);
// "Hello, Alice! Welcome to Acme."
```
```python Python SDK theme={null}
prompt = sdk.llm.prompts.get(
id=prompt_id,
variables='{"name": "Alice", "company": "Acme"}',
)
print(prompt.rendered_template)
# "Hello, Alice! Welcome to Acme."
```
```csharp C# SDK theme={null}
var prompt = await sdk.Llm.Prompts.GetAsync(
id: promptId,
variables: "{\"name\":\"Alice\",\"company\":\"Acme\"}"
);
Console.WriteLine(prompt.GetPromptResponseValue!.RenderedTemplate);
// "Hello, Alice! Welcome to Acme."
```
```bash CLI theme={null}
mka1 llm prompts get \
--id prompt_abc123 \
--variables '{"name":"Alice","company":"Acme"}'
```
```bash Bash theme={null}
# URL-encode the variables JSON
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123?variables=%7B%22name%22%3A%22Alice%22%2C%22company%22%3A%22Acme%22%7D" \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: '
```
## List prompts
Retrieve a paginated list of all prompts. Use `after` for cursor-based pagination.
```ts TypeScript SDK theme={null}
const list = await sdk.llm.prompts.list({
xOnBehalfOf: '',
limit: 10,
order: 'desc',
});
for (const prompt of list.data) {
console.log(prompt.name, `v${prompt.activeVersion}`);
}
if (list.hasMore) {
// Fetch next page using the last ID as cursor
const next = await sdk.llm.prompts.list({
xOnBehalfOf: '',
limit: 10,
after: list.lastId,
});
}
```
```python Python SDK theme={null}
prompts = sdk.llm.prompts.list()
for prompt in prompts.data:
print(prompt.name, f"v{prompt.active_version}")
```
```csharp C# SDK theme={null}
var prompts = await sdk.Llm.Prompts.ListAsync();
Console.WriteLine(prompts);
```
```bash CLI theme={null}
mka1 llm prompts list --limit 10 --order desc
```
```bash Bash theme={null}
curl "https://apigw.mka1.com/api/v1/llm/prompts?limit=10&order=desc" \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: '
```
## Update prompt metadata
Update the name, description, or metadata of a prompt. To change the template,
create a new version instead.
Note: `metadata` replaces the existing metadata object (it is not merged). To clear a description, pass `null`.
```ts TypeScript SDK theme={null}
const updated = await sdk.llm.prompts.update({
xOnBehalfOf: '',
id: promptId,
requestBody: {
name: 'welcome-greeting',
description: 'Updated greeting for the welcome flow',
metadata: { team: 'onboarding', reviewed: true },
},
});
```
```python Python SDK theme={null}
updated = sdk.llm.prompts.update(
id=prompt_id,
name="welcome-greeting",
description="Updated greeting for the welcome flow",
metadata={"team": "onboarding", "reviewed": True},
)
```
```csharp C# SDK theme={null}
var updated = await sdk.Llm.Prompts.UpdateAsync(
id: promptId,
body: new UpdatePromptRequestBody
{
Name = "welcome-greeting",
Description = "Updated greeting for the welcome flow",
Metadata = new Dictionary
{
{ "team", "onboarding" },
{ "reviewed", true },
},
}
);
```
```bash CLI theme={null}
mka1 llm prompts update \
--id prompt_abc123 \
--body '{
"name": "welcome-greeting",
"description": "Updated greeting for the welcome flow",
"metadata": { "team": "onboarding", "reviewed": true }
}'
```
```bash Bash theme={null}
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123" \
--request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: ' \
--data '{
"name": "welcome-greeting",
"description": "Updated greeting for the welcome flow",
"metadata": { "team": "onboarding", "reviewed": true }
}'
```
## Create a new version
Each template change creates a new version. The new version automatically becomes the active version.
```ts TypeScript SDK theme={null}
const version = await sdk.llm.prompts.createVersion({
xOnBehalfOf: '',
id: promptId,
requestBody: {
template: 'Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}.',
},
});
console.log(version.version); // 2
console.log(version.template); // The new template text
```
```python Python SDK theme={null}
version = sdk.llm.prompts.create_version(
id=prompt_id,
template="Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}.",
)
print(version.version) # 2
print(version.template) # The new template text
```
```csharp C# SDK theme={null}
var version = await sdk.Llm.Prompts.CreateVersionAsync(
id: promptId,
body: new CreatePromptVersionRequestBody
{
Template = "Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}.",
}
);
Console.WriteLine(version.CreateVersionResponse!.Version); // 2
Console.WriteLine(version.CreateVersionResponse!.Template); // The new template text
```
```bash CLI theme={null}
mka1 llm prompts create-version \
--id prompt_abc123 \
--body '{
"template": "Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}."
}'
```
```bash Bash theme={null}
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions" \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: ' \
--data '{
"template": "Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}."
}'
```
## View version history
List all versions of a prompt to see its full change history.
```ts TypeScript SDK theme={null}
const versions = await sdk.llm.prompts.listVersions({
xOnBehalfOf: '',
id: promptId,
order: 'desc',
});
for (const v of versions.data) {
console.log(`v${v.version}: ${v.template.slice(0, 50)}...`);
}
```
```python Python SDK theme={null}
versions = sdk.llm.prompts.list_versions(id=prompt_id)
for v in versions.data:
print(f"v{v.version}: {v.template[:50]}...")
```
```csharp C# SDK theme={null}
var versions = await sdk.Llm.Prompts.ListVersionsAsync(
id: promptId,
order: ListPromptVersionsOrder.Desc
);
foreach (var v in versions.ListVersionsResponse!.Data)
{
Console.WriteLine($"v{v.Version}: {v.Template.Substring(0, 50)}...");
}
```
```bash CLI theme={null}
mka1 llm prompts list-versions --id prompt_abc123 --order desc
```
```bash Bash theme={null}
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions?order=desc" \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: '
```
## Retrieve a specific version
Fetch a single version by its version number.
```ts TypeScript SDK theme={null}
const v1 = await sdk.llm.prompts.getVersion({
xOnBehalfOf: '',
id: promptId,
version: 1,
});
console.log(v1.template);
```
```python Python SDK theme={null}
v1 = sdk.llm.prompts.get_version(id=prompt_id, version=1)
print(v1.template)
```
```csharp C# SDK theme={null}
var v1 = await sdk.Llm.Prompts.GetVersionAsync(
id: promptId,
version: 1
);
Console.WriteLine(v1.CreateVersionResponse!.Template);
```
```bash CLI theme={null}
mka1 llm prompts get-version --id prompt_abc123 --version-param 1
```
```bash Bash theme={null}
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions/1" \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: '
```
## Roll back to a previous version
Rollback sets an earlier version as the active version. All versions are preserved — rollback
does not delete newer versions, so you can always roll forward again.
```ts TypeScript SDK theme={null}
// Currently on version 2, roll back to version 1
const rolledBack = await sdk.llm.prompts.rollback({
xOnBehalfOf: '',
id: promptId,
requestBody: {
version: 1,
},
});
console.log(rolledBack.activeVersion); // 1
console.log(rolledBack.latestVersion); // 2 (still exists)
```
```python Python SDK theme={null}
# Currently on version 2, roll back to version 1
rolled_back = sdk.llm.prompts.rollback(id=prompt_id, version=1)
print(rolled_back.active_version) # 1
print(rolled_back.latest_version) # 2 (still exists)
```
```csharp C# SDK theme={null}
// Currently on version 2, roll back to version 1
var rolledBack = await sdk.Llm.Prompts.RollbackAsync(
id: promptId,
body: new RollbackPromptRequestBody { Version = 1 }
);
Console.WriteLine(rolledBack.UpdatePromptResponse!.ActiveVersion); // 1
Console.WriteLine(rolledBack.UpdatePromptResponse!.LatestVersion); // 2 (still exists)
```
```bash CLI theme={null}
# Currently on version 2, roll back to version 1
mka1 llm prompts rollback --id prompt_abc123 --version-param 1
```
```bash Bash theme={null}
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/rollback" \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: ' \
--data '{ "version": 1 }'
```
## Delete a prompt
Deleting a prompt removes it and all of its versions permanently.
```ts TypeScript SDK theme={null}
const deleted = await sdk.llm.prompts.delete({
xOnBehalfOf: '',
id: promptId,
});
console.log(deleted.deleted); // true
```
```python Python SDK theme={null}
deleted = sdk.llm.prompts.delete(id=prompt_id)
print(deleted.deleted) # True
```
```csharp C# SDK theme={null}
var deleted = await sdk.Llm.Prompts.DeleteAsync(id: promptId);
Console.WriteLine(deleted.DeletePromptResponseValue!.Deleted); // True
```
```bash CLI theme={null}
mka1 llm prompts delete --id prompt_abc123
```
```bash Bash theme={null}
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123" \
--request DELETE \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: '
```
## Full example: versioning and rollback workflow
This example demonstrates the complete lifecycle — creating a prompt, iterating on the
template, reviewing history, and rolling back.
```ts TypeScript SDK theme={null}
// 1. Create a prompt with the initial template
const prompt = await sdk.llm.prompts.create({
xOnBehalfOf: 'user-123',
createPromptRequest: {
name: 'support-reply',
template: 'Hi {{customer}}, thanks for contacting us about {{issue}}.',
},
});
console.log('Created:', prompt.id, 'v1');
// 2. Ship v2 with a friendlier tone
const v2 = await sdk.llm.prompts.createVersion({
xOnBehalfOf: 'user-123',
id: prompt.id,
requestBody: {
template: 'Hey {{customer}}! We got your message about {{issue}} and are on it.',
},
});
console.log('Created v2:', v2.version);
// 3. Retrieve the prompt — active version is now v2
const current = await sdk.llm.prompts.get({
xOnBehalfOf: 'user-123',
id: prompt.id,
variables: JSON.stringify({ customer: 'Alice', issue: 'billing' }),
});
console.log('Active:', current.renderedTemplate);
// "Hey Alice! We got your message about billing and are on it."
// 4. Review version history
const history = await sdk.llm.prompts.listVersions({
xOnBehalfOf: 'user-123',
id: prompt.id,
order: 'asc',
});
for (const v of history.data) {
console.log(` v${v.version}: ${v.template}`);
}
// 5. Roll back to v1
const rolledBack = await sdk.llm.prompts.rollback({
xOnBehalfOf: 'user-123',
id: prompt.id,
requestBody: {
version: 1,
},
});
console.log('Rolled back to v' + rolledBack.activeVersion);
// activeVersion=1, latestVersion=2
// 6. Clean up
await sdk.llm.prompts.delete({ xOnBehalfOf: 'user-123', id: prompt.id });
```
```python Python SDK theme={null}
# 1. Create a prompt with the initial template
prompt = sdk.llm.prompts.create(
name="support-reply",
template="Hi {{customer}}, thanks for contacting us about {{issue}}.",
)
print("Created:", prompt.id, "v1")
# 2. Ship v2 with a friendlier tone
v2 = sdk.llm.prompts.create_version(
id=prompt.id,
template="Hey {{customer}}! We got your message about {{issue}} and are on it.",
)
print("Created v2:", v2.version)
# 3. Retrieve the prompt — active version is now v2
current = sdk.llm.prompts.get(
id=prompt.id,
variables='{"customer": "Alice", "issue": "billing"}',
)
print("Active:", current.rendered_template)
# "Hey Alice! We got your message about billing and are on it."
# 4. Review version history
history = sdk.llm.prompts.list_versions(id=prompt.id)
for v in history.data:
print(f" v{v.version}: {v.template}")
# 5. Roll back to v1
rolled_back = sdk.llm.prompts.rollback(id=prompt.id, version=1)
print("Rolled back to v" + str(rolled_back.active_version))
# active_version=1, latest_version=2
# 6. Clean up
sdk.llm.prompts.delete(id=prompt.id)
```
```csharp C# SDK theme={null}
// 1. Create a prompt with the initial template
var prompt = await sdk.Llm.Prompts.CreateAsync(
new CreatePromptRequest
{
Name = "support-reply",
Template = "Hi {{customer}}, thanks for contacting us about {{issue}}.",
}
);
var promptId = prompt.CreatePromptResponseValue!.Id;
Console.WriteLine($"Created: {promptId} v1");
// 2. Ship v2 with a friendlier tone
var v2 = await sdk.Llm.Prompts.CreateVersionAsync(
id: promptId,
body: new CreatePromptVersionRequestBody
{
Template = "Hey {{customer}}! We got your message about {{issue}} and are on it.",
}
);
Console.WriteLine($"Created v2: {v2.CreateVersionResponse!.Version}");
// 3. Retrieve the prompt with rendered variables
var current = await sdk.Llm.Prompts.GetAsync(
id: promptId,
variables: "{\"customer\":\"Alice\",\"issue\":\"billing\"}"
);
Console.WriteLine($"Active: {current.GetPromptResponseValue!.RenderedTemplate}");
// 4. Review version history
var history = await sdk.Llm.Prompts.ListVersionsAsync(
id: promptId,
order: ListPromptVersionsOrder.Asc
);
foreach (var v in history.ListVersionsResponse!.Data)
{
Console.WriteLine($" v{v.Version}: {v.Template}");
}
// 5. Roll back to v1
var rolledBack = await sdk.Llm.Prompts.RollbackAsync(
id: promptId,
body: new RollbackPromptRequestBody { Version = 1 }
);
Console.WriteLine($"Rolled back to v{rolledBack.UpdatePromptResponse!.ActiveVersion}");
// 6. Clean up
await sdk.Llm.Prompts.DeleteAsync(id: promptId);
```
```bash CLI theme={null}
# 1. Create a prompt with the initial template
mka1 llm prompts create \
--body '{
"name": "support-reply",
"template": "Hi {{customer}}, thanks for contacting us about {{issue}}."
}'
# → { "id": "prompt_abc123", "active_version": 1, "version": { "version": 1, ... }, ... }
# 2. Ship v2 with a friendlier tone
mka1 llm prompts create-version \
--id prompt_abc123 \
--body '{
"template": "Hey {{customer}}! We got your message about {{issue}} and are on it."
}'
# 3. Retrieve the prompt with rendered variables
mka1 llm prompts get \
--id prompt_abc123 \
--variables '{"customer":"Alice","issue":"billing"}'
# 4. Review version history
mka1 llm prompts list-versions --id prompt_abc123 --order asc
# 5. Roll back to v1
mka1 llm prompts rollback --id prompt_abc123 --version-param 1
# 6. Clean up
mka1 llm prompts delete --id prompt_abc123
```
```bash Bash theme={null}
# 1. Create a prompt
curl https://apigw.mka1.com/api/v1/llm/prompts \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: user-123' \
--data '{
"name": "support-reply",
"template": "Hi {{customer}}, thanks for contacting us about {{issue}}."
}'
# → { "id": "prompt_abc123", "active_version": 1, "version": { "version": 1, ... }, ... }
# 2. Create v2 with a friendlier tone
curl https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: user-123' \
--data '{
"template": "Hey {{customer}}! We got your message about {{issue}} and are on it."
}'
# 3. Get the prompt with rendered variables
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123?variables=%7B%22customer%22%3A%22Alice%22%2C%22issue%22%3A%22billing%22%7D" \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: user-123'
# 4. View version history
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions?order=asc" \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: user-123'
# 5. Roll back to v1
curl https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/rollback \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: user-123' \
--data '{ "version": 1 }'
# 6. Delete the prompt
curl https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123 \
--request DELETE \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: user-123'
```
## Behavior details
| Aspect | Detail |
| - | - |
| Versioning | Immutable — each template change creates a new version that cannot be modified |
| Active version | New versions auto-activate; use rollback to switch to a different version |
| Rollback | Non-destructive — sets `active_version` without deleting newer versions |
| Pagination | Cursor-based for listing prompts — use `after` parameter with `last_id` from response |
| Template rendering | Server-side — pass `variables` query parameter; unmatched placeholders preserved |
| Ownership | Per API key — prompts are isolated by authentication context |
| Concurrency | Conflict detection — concurrent version creation returns 409 |
## Next steps
* [Generate a response](/docs/generate-a-response) — use rendered prompts as input to the Responses API
* [Structured data](/docs/extract-structured-data) — combine prompts with structured extraction
* [Conversations](/docs/conversations) — manage multi-turn exchanges with versioned system prompts
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.