Saltar para o conteúdo principal
A API de Prompts permite armazenar, versionar e gerenciar templates de prompt de forma centralizada. Cada alteração de template cria uma versão imutável, proporcionando um histórico completo de mudanças com a possibilidade de reverter para qualquer versão anterior a qualquer momento. Os templates suportam placeholders {{variable}} que são renderizados no lado do servidor quando você recupera um prompt, permitindo reutilizar o mesmo template em diferentes contextos.

​
Criar um prompt

Crie um prompt com um nome e template. A primeira versão é criada automaticamente. 
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

​
Recuperar um prompt com variáveis renderizadas

Passe variables como parâmetro de consulta para renderizar o template com seus valores. Placeholders não correspondidos são mantidos como estão. 
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

Recupere uma lista paginada de todos os prompts. Use after para paginação baseada em 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) {
  // 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>' } });
}

​
Atualizar metadados do prompt

Atualize o nome, descrição ou metadados de um prompt. Para alterar o template, crie uma nova versão. 
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>' } });

​
Criar uma nova versão

Cada alteração de template cria uma nova versão. A nova versão se torna automaticamente a versão ativa. 
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

​
Visualizar histórico de versões

Liste todas as versões de um prompt para ver o histórico completo de alterações. 
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 uma versão específica

Busque uma única versão pelo seu número de versão. 
const v1 = await mka1.llm.prompts.getVersion({
  id: promptId,
  version: 1,
}, {
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
});

console.log(v1.template);

​
Reverter para uma versão anterior

O rollback define uma versão anterior como a versão ativa. Todas as versões são preservadas — o rollback não exclui versões mais recentes, então você sempre pode avançar novamente. 
// 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)

​
Excluir um prompt

Excluir um prompt remove ele e todas as suas versões permanentemente. 
const deleted = await mka1.llm.prompts.delete({
  id: promptId,
}, {
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
});

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

​
Exemplo completo: fluxo de versionamento e rollback

Este exemplo demonstra o ciclo de vida completo — criando um prompt, iterando no template, revisando o histórico e fazendo rollback. 
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 });

​
Detalhes de comportamento

AspectoDetalhe
VersionamentoImutável — cada alteração de template cria uma nova versão que não pode ser modificada
Versão ativaNovas versões são ativadas automaticamente; use rollback para mudar para uma versão diferente
RollbackNão destrutivo — define active_version sem excluir versões mais recentes
PaginaçãoBaseada em cursor para listagem de prompts — use o parâmetro after com first_id/last_id da resposta
Renderização de templateNo lado do servidor — passe o parâmetro de consulta variables; placeholders não correspondidos são preservados
PropriedadePor chave de API — prompts são isolados pelo contexto de autenticação
ConcorrênciaDetecção de conflitos — criação concorrente de versões retorna 409

​
Próximos passos