Saltar al contenido principal
La API de Prompts te permite almacenar, versionar y gestionar plantillas de prompts de forma centralizada. Cada cambio en la plantilla crea una versión inmutable, dándote un historial completo de cambios con la capacidad de volver a cualquier versión anterior en cualquier momento. Las plantillas admiten marcadores de posición {{variable}} que se renderizan del lado del servidor cuando recuperas un prompt, por lo que puedes reutilizar la misma plantilla en diferentes contextos.

​
Crear un prompt

Crea un prompt con un nombre y una plantilla. La primera versión se crea automáticamente. 
import { SDK } from '@meetkai/mka1';

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

const result = await mka1.llm.prompts.create({
  name: 'greeting',
  description: 'Una plantilla de saludo simple',
  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

​
Recuperar un prompt con variables renderizadas

Pasa variables como un parámetro de consulta para renderizar la plantilla con tus valores. Los marcadores de posición no coincidentes se dejan tal cual. 
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."

​
Listar prompts

Recupera una lista paginada de todos los prompts. Usa after para paginación basada en cursor. 
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) {
  // Obtener la siguiente página usando el último ID como cursor
  const next = await mka1.llm.prompts.list({
    limit: 10,
    after: list.lastId,
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });
}

​
Actualizar metadatos del prompt

Actualiza el nombre, la descripción o los metadatos de un prompt. Para cambiar la plantilla, crea una nueva versión en su lugar. 
const updated = await mka1.llm.prompts.update({
  id: promptId,
  requestBody: {
    name: 'welcome-greeting',
    description: 'Saludo actualizado para el flujo de bienvenida',
    metadata: { team: 'onboarding', reviewed: true },
  },
}, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

​
Crear una nueva versión

Cada cambio en la plantilla crea una nueva versión. La nueva versión se activa automáticamente. 
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); // El nuevo texto de la plantilla

​
Ver historial de versiones

Lista todas las versiones de un prompt para ver su historial completo de cambios. 
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)}...`);
}

​
Recuperar una versión específica

Obtén una sola versión por su número de versión. 
const v1 = await mka1.llm.prompts.getVersion({
  id: promptId,
  version: 1,
}, {
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
});

console.log(v1.template);

​
Revertir a una versión anterior

La reversión establece una versión anterior como la versión activa. Todas las versiones se conservan — la reversión no elimina versiones más recientes, por lo que siempre puedes avanzar de nuevo. 
// Actualmente en la versión 2, volver a la versión 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 (sigue existiendo)

​
Eliminar un prompt

Eliminar un prompt lo elimina a él y a todas sus versiones de forma permanente. 
const deleted = await mka1.llm.prompts.delete({
  id: promptId,
}, {
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
});

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

​
Ejemplo completo: flujo de trabajo de versionado y reversión

Este ejemplo demuestra el ciclo de vida completo — crear un prompt, iterar sobre la plantilla, revisar el historial y revertir. 
import { SDK } from '@meetkai/mka1';

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

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

// 1. Crear un prompt con la plantilla inicial
const prompt = await mka1.llm.prompts.create({
  name: 'support-reply',
  template: 'Hi {{customer}}, thanks for contacting us about {{issue}}.',
}, { headers });

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

// 2. Publicar v2 con un tono más amigable
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('Creada v2:', v2.version);

// 3. Recuperar el prompt — la versión activa ahora es la v2
const current = await mka1.llm.prompts.get({
  id: prompt.id,
  variables: JSON.stringify({ customer: 'Alice', issue: 'billing' }),
}, { headers });

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

// 4. Revisar el historial de versiones
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. Revertir a v1
const rolledBack = await mka1.llm.prompts.rollback({
  id: prompt.id,
  requestBody: {
    version: 1,
  },
}, { headers });

console.log('Revertido a v' + rolledBack.activeVersion);
// active_version=1, latest_version=2

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

​
Detalles del comportamiento

AspectoDetalle
VersionadoInmutable — cada cambio en la plantilla crea una nueva versión que no puede ser modificada
Versión activaLas nuevas versiones se activan automáticamente; usa la reversión para cambiar de versión
ReversiónNo destructivo — establece active_version sin eliminar versiones más recientes
PaginaciónBasada en cursor para listar prompts — usa el parámetro after con first_id/last_id de la respuesta
Renderizado de plantillaDel lado del servidor — pasa el parámetro de consulta variables; los marcadores no coincidentes se conservan
PropiedadPor clave API — los prompts están aislados por contexto de autenticación
ConcurrenciaDetección de conflictos — la creación concurrente de versiones retorna 409

​
Próximos pasos