Prompts

Guarda tus prompts con variables y versiones: cada cambio crea una versión nueva y el historial queda completo.

¿Qué es un prompt versionado?

Un prompt tiene un nombre, un texto y un historial de versiones.

Variables. Todo lo que escribas como {{variable}} (letras, números y guion bajo) se detecta solo y se guarda en variables.
Versiones. Al crear el prompt nace la versión 1; cada actualización suma una y conserva las anteriores.
Dónde vive. Los prompts se guardan en la base de AstrApp, no en Opik.

En la app

Los prompts que creas aquí aparecen en Conversaciones › Prompts, la biblioteca de prompts de la app.

API

Rutas bajo /api/v1/projects/{projectId}. Funcionan solo con la sesión de la app.

GET/opik/prompts

Lista prompts con sus versiones

POST/opik/prompts

Crea un prompt

PUT/opik/prompts

Crea una versión nueva

Sin API key por ahora

Estas rutas leen y escriben con tu sesión de la app. Con una API key no ven tus prompts y no pueden crearlos.

Listar prompts

Sin parámetros, devuelve los prompts ligados al proyecto de la ruta y tus prompts sin proyecto.

Parámetro	Tipo	Descripción
`name`	texto	Devuelve solo el prompt con ese nombre.
`include_all`	true	Incluye todos tus prompts (de cualquier proyecto) y los públicos.

Respuesta 200

{
  "data": {
    "prompts": [
      {
        "id": "…",
        "name": "atencion-cliente",
        "description": "Prompt de soporte",
        "content": "Eres un asistente de {{company}}. Contexto: {{context}}…",
        "category": "system_prompt",
        "currentVersion": 2,
        "versions": [
          {
            "id": "…",
            "version": 2,
            "content": "Eres un asistente de {{company}}. Contexto: {{context}}…",
            "variables": ["company", "context", "question"],
            "metadata": {},
            "createdAt": "2026-09-20T12:00:00.000Z",
            "createdBy": "…"
          }
        ],
        "tags": ["soporte"],
        "isPublic": false,
        "isDefault": false,
        "projectId": "…",
        "createdAt": "2026-09-19T10:00:00.000Z",
        "updatedAt": "2026-09-20T12:00:00.000Z"
      }
    ]
  }
}

versions viene de la más nueva a la más vieja.

Crear un prompt

Campo	Tipo	Descripción
`name`	texto	Obligatorio.
`content`	texto	Obligatorio. El texto del prompt, con sus {{variables}}.
`description`	texto	Para qué sirve el prompt.
`category`	texto	system_prompt (por defecto), inference_prompt, evaluation_prompt o synthesis_prompt.
`tags`	texto[]	Etiquetas.
`isPublic / isDefault`	booleano	Por defecto false.
`metadata`	objeto	Datos libres.
`associateWithProject`	booleano	Con false, el prompt no se liga al proyecto de la ruta. Por defecto true.

Cuerpo

{
  "name": "atencion-cliente",
  "content": "Eres un asistente de soporte de {{company}}.\nEl cliente pregunta: {{question}}\nResponde con amabilidad.",
  "description": "Prompt de soporte",
  "tags": ["soporte"]
}

Responde 201 con data.prompt, que incluye "variables": ["company", "question"] y currentVersion: 1.

Crear una versión nueva

Identifica el prompt con prompt_id o con name y manda el nuevo content (obligatorio). También puedes cambiar description, tags y metadata.

Cuerpo

{
  "name": "atencion-cliente",
  "content": "Eres un asistente de {{company}}.\nContexto: {{context}}\nPregunta: {{question}}\nResponde con empatía.",
  "tags": ["soporte", "v2"]
}

Respuesta 200

{
  "data": {
    "promptId": "…",
    "name": "atencion-cliente",
    "content": "Eres un asistente de {{company}}…",
    "version": 2,
    "variables": ["company", "context", "question"],
    "message": "Prompt actualizado a versión 2"
  }
}

Límites y notas

Las respuestas de estas rutas traen solo data, sin success.
Solo ves y editas tus propios prompts, más los públicos en lectura. Si no encuentra el prompt que quieres versionar, responde 404.
Si falta name o content al crear, responde 400.