Skip to main content
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. 
import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const result = await mka1.llm.prompts.create({
  name: 'greeting',
  description: 'A simple greeting template',
  template: 'Hello, {{name}}! Welcome to {{company}}.',
  metadata: { team: 'onboarding' },
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

console.log(result.id);            // prompt_abc123...
console.log(result.activeVersion); // 1

​
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. 
const prompt = await mka1.llm.prompts.get({
  id: promptId,
  variables: JSON.stringify({ name: 'Alice', company: 'Acme' }),
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

console.log(prompt.renderedTemplate);
// "Hello, Alice! Welcome to Acme."

​
List prompts

Retrieve a paginated list of all prompts. Use after for cursor-based pagination. 
const list = await mka1.llm.prompts.list({
  limit: 10,
  order: 'desc',
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

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 mka1.llm.prompts.list({
    limit: 10,
    after: list.lastId,
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });
}

​
Update prompt metadata

Update the name, description, or metadata of a prompt. To change the template, create a new version instead. 
const updated = await mka1.llm.prompts.update({
  id: promptId,
  requestBody: {
    name: 'welcome-greeting',
    description: 'Updated greeting for the welcome flow',
    metadata: { team: 'onboarding', reviewed: true },
  },
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

​
Create a new version

Each template change creates a new version. The new version automatically becomes the active version. 
const version = await mka1.llm.prompts.createVersion({
  id: promptId,
  requestBody: {
    template: 'Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}.',
  },
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

console.log(version.version);  // 2
console.log(version.template); // The new template text

​
View version history

List all versions of a prompt to see its full change history. 
const versions = await mka1.llm.prompts.listVersions({
  id: promptId,
  order: 'desc',
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

for (const v of versions.data) {
  console.log(`v${v.version}: ${v.template.slice(0, 50)}...`);
}

​
Retrieve a specific version

Fetch a single version by its version number. 
const v1 = await mka1.llm.prompts.getVersion({
  id: promptId,
  version: 1,
}, {
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
});

console.log(v1.template);

​
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. 
// Currently on version 2, roll back to version 1
const rolledBack = await mka1.llm.prompts.rollback({
  id: promptId,
  requestBody: {
    version: 1,
  },
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

console.log(rolledBack.activeVersion);  // 1
console.log(rolledBack.latestVersion);  // 2 (still exists)

​
Delete a prompt

Deleting a prompt removes it and all of its versions permanently. 
const deleted = await mka1.llm.prompts.delete({
  id: promptId,
}, {
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
});

console.log(deleted.deleted); // true

​
Full example: versioning and rollback workflow

This example demonstrates the complete lifecycle — creating a prompt, iterating on the template, reviewing history, and rolling back. 
import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const headers = { 'X-On-Behalf-Of': 'user-123' };

// 1. Create a prompt with the initial template
const prompt = await mka1.llm.prompts.create({
  name: 'support-reply',
  template: 'Hi {{customer}}, thanks for contacting us about {{issue}}.',
}, { headers });

console.log('Created:', prompt.id, 'v1');

// 2. Ship v2 with a friendlier tone
const v2 = await mka1.llm.prompts.createVersion({
  id: prompt.id,
  requestBody: {
    template: 'Hey {{customer}}! We got your message about {{issue}} and are on it.',
  },
}, { headers });

console.log('Created v2:', v2.version);

// 3. Retrieve the prompt — active version is now v2
const current = await mka1.llm.prompts.get({
  id: prompt.id,
  variables: JSON.stringify({ customer: 'Alice', issue: 'billing' }),
}, { headers });

console.log('Active:', current.renderedTemplate);
// "Hey Alice! We got your message about billing and are on it."

// 4. Review version history
const history = await mka1.llm.prompts.listVersions({
  id: prompt.id,
  order: 'asc',
}, { headers });

for (const v of history.data) {
  console.log(`  v${v.version}: ${v.template}`);
}

// 5. Roll back to v1
const rolledBack = await mka1.llm.prompts.rollback({
  id: prompt.id,
  requestBody: {
    version: 1,
  },
}, { headers });

console.log('Rolled back to v' + rolledBack.activeVersion);
// active_version=1, latest_version=2

// 6. Clean up
await mka1.llm.prompts.delete({ id: prompt.id }, { headers });

​
Behavior details

AspectDetail
VersioningImmutable — each template change creates a new version that cannot be modified
Active versionNew versions auto-activate; use rollback to switch to a different version
RollbackNon-destructive — sets active_version without deleting newer versions
PaginationCursor-based for listing prompts — use after parameter with first_id/last_id from response
Template renderingServer-side — pass variables query parameter; unmatched placeholders preserved
OwnershipPer API key — prompts are isolated by authentication context
ConcurrencyConflict detection — concurrent version creation returns 409

​
Next steps