Prompts y ejecuciones

Un prompt guardado es una plantilla reutilizable de tu biblioteca de prompts. Su texto contiene {{variables}} que rellenas cada vez que lo ejecutas. Con la API REST puedes crear prompts desde código, ejecutarlos con valores nuevos en el modelo que elijas y leer los resultados. Todas las solicitudes se ejecutan como el usuario propietario de la clave de API.

Todas las rutas son relativas a https://api.stickyprompts.com/api/v1. Los cuerpos de las solicitudes son JSON.

Conceptos clave

Un prompt es una plantilla con nombre. Su texto vive en una versión del prompt: cada prompt tiene una sola versión, y al enviar contenido nuevo se sobrescribe. Una versión tiene variables, que se referencian en el texto como {{slug}}, por ejemplo Write a {{tone}} summary of: {{text}}.

Para ejecutar un prompt, rellenas sus variables. Así se crea una instancia: una copia inmutable de la plantilla con los valores sustituidos. Después ejecutas la instancia con uno o varios modelos. Cada ejecución crea una conversación (en la API se llama conversation_context) en la que puedes seguir chateando mediante los endpoints de Conversaciones y mensajes.

prompt -> prompt_version (content with {{slug}} placeholders) -> variables
                    |
                    +-> instance (variable values, parsed content) -> run -> conversation

Los endpoints de atajo bajo /run/prompt/... crean la instancia y la ejecutan en una sola llamada. POST /run envía texto libre a un modelo sin ningún prompt.

Convenciones

• Paginación. Donde se indique, envía page (1 de forma predeterminada) y size (10 de forma predeterminada). Los headers de respuesta X-Page, X-Page-Size y X-Total-Count describen el resultado. Consulta Errores, paginación y cuotas.
• Ámbito de proyecto. Varios endpoints leen un header opcional X-Project-ID: <numeric id>. Un valor no numérico se trata como si no existiera.
• Mayúsculas en los campos. Los objetos de base de datos usan ID, CreatedAt, UpdatedAt y DeletedAt con mayúscula inicial junto a campos en snake_case. El resultado RunHistory usa id y created_at en minúsculas.
• Texto renderizado. Los campos result y thinking de una ejecución contienen HTML renderizado a partir del Markdown del modelo, no el Markdown original.
• Los errores tienen la forma {"error": "..."}. Los fallos de cuota son 429 {"error":"Quota exceeded","reason":"..."}. Los bloqueos de los guardrails añaden un código legible por máquina, por ejemplo {"error": "...", "code": "SENSITIVE_DATA_BLOCKED"}. Los fallos de residencia de datos usan los códigos EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED y NO_ENDPOINT_AVAILABLE.

El objeto Prompt

{
  "ID": 42,
  "CreatedAt": "2026-09-20T10:15:00Z",
  "UpdatedAt": "2026-09-20T10:15:00Z",
  "DeletedAt": null,
  "name": "Renewal check-in email",
  "slug": "k3j9x2qa",
  "user_id": 7,
  "project_id": null,
  "shared_with_workspace_id": null,
  "current_version_id": 88,
  "current_version": null,
  "ai_model_id": 12,
  "description": "Friendly renewal reminder for a Northwind customer",
  "is_favorite": false,
  "category_id": 3,
  "category": null,
  "example_output": "",
  "duplicated_from_id": null,
  "file_data": [],
  "tools": [{ "name": "web_search", "use": true }],
  "mcp_servers": [],
  "ai_style": "prompty"
}

• current_version es {ID, ..., prompt_id, content, variables[], current_instance_id, current_instance} cuando se carga; la mayoría de los endpoints de listado lo dejan en null.
• category es {ID, CreatedAt, UpdatedAt, DeletedAt, name} cuando se carga.
• file_data es un array de objetos File cuando se carga; si no, null. Un File es {ID, CreatedAt, UpdatedAt, DeletedAt, name, path, preview_path, public_path, user_id, workspace_id, project_id, fileType, partial}; atención a fileType, en camelCase.
• tools es [{"name", "use"}] o null. Nombres de herramientas: web_search, image_generation, video_generation, speech_generation, music_generation, remote_mcp.
• mcp_servers es un array de IDs de servidores MCP remotos.

Prompts

GET /prompt

Lista tus propios prompts que no están en ningún proyecto, del más reciente al más antiguo. Con X-Project-ID, lista en su lugar los prompts de ese proyecto.

Respuesta. 200 con un array de objetos Prompt (sin cargar current_version, category ni file_data). Con X-Project-ID, cada elemento incluye además "can_delete": bool, que solo es true cuando puedes gestionar los prompts del proyecto y eres el propietario de ese prompt.

Errores. 404 {"error":"Project not found"}, 403 {"error":"You don't have access to this project"}.

GET /prompt/all

Devuelve en una sola lista tus propios prompts, los prompts compartidos contigo y los que has marcado como favoritos, ordenados según la última vez que ejecutaste cada uno (o, si no, por fecha de creación). Se excluyen los prompts que están dentro de un proyecto.

Respuesta. 200 con un array de objetos Prompt con file_data cargado, o [].

GET /prompt/last_used

Devuelve hasta 8 prompts que has ejecutado, empezando por el último que ejecutaste, con file_data cargado. Los prompts que nunca has ejecutado quedan fuera. Se incluyen los headers de paginación, pero page y size se ignoran.

GET /prompt/most_used

Devuelve hasta 8 prompts ordenados según la frecuencia con la que los has ejecutado. Sin headers de paginación.

GET /prompt/recently_added

Devuelve hasta 8 de tus propios prompts, del más reciente al más antiguo, con file_data cargado.

POST /prompt

Crea un prompt. El prompt nace sin versión: llama después a POST /prompt_version para darle contenido. El modelo sale de tus preferencias (o es el primer modelo del catálogo), y ai_style, también de tus preferencias (o prompty). Para cambiar cualquiera de los dos, llama después a PUT /prompt/:id.

ai_model_id, ai_style y slug se ignoran al crear; se genera un slug aleatorio.

curl -X POST https://api.stickyprompts.com/api/v1/prompt \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renewal check-in email", "description": "Friendly renewal reminder" }'

Respuesta. 201 con el objeto Prompt.

Errores. 400 si el JSON está mal formado, 404 {"error":"Project not found"}, 403 {"error":"You don't have access to manage prompts of this project"}, 409 {"error":"Entity already exists"}.

PUT /prompt/:id

Sustituye los campos editables de un prompt. Solo para tus propios prompts.

Se sobrescriben todos estos campos: name, description, ai_model_id, example_output, category_id y ai_style. Envía siempre los valores actuales de los campos que no quieras cambiar.

Respuesta. 200 con el objeto Prompt. Errores. 404 {"error":"Prompt not found"}, 400 {"error":"Name is required"}.

POST /prompt_version

Define el contenido de la plantilla de un prompt. La primera llamada crea la versión y la convierte en la actual; las siguientes sobrescriben content en esa misma versión. Las variables se crean con POST /variable, no en este cuerpo.

Respuesta. 201, tanto al crear como al actualizar:

{
  "ID": 88, "CreatedAt": "...", "UpdatedAt": "...", "DeletedAt": null,
  "prompt_id": 42,
  "content": "Write a renewal check-in email to {{customer_name}} about their {{plan}} plan.",
  "variables": null,
  "current_instance_id": null,
  "current_instance": null
}

En la actualización no se carga variables. Errores. 400 si el JSON está mal formado, 404 {"error":"Prompt not found"}.

DELETE /prompt/:id

Elimina de forma lógica (soft delete) uno de tus propios prompts y quita sus comparticiones y las marcas de favorito de todos los usuarios.

Respuesta. 204. Devuelve 404 con el cuerpo vacío cuando el prompt no existe o no es tuyo.

POST /prompt/:id/duplicate

Copia un prompt que es tuyo o al que tienes acceso (el catálogo público, los prompts compartidos contigo y los compartidos con tu espacio de trabajo). La copia incluye el nombre, la descripción, el modelo, el ejemplo de salida, las herramientas, el estilo, la categoría, el contenido de la versión y las variables (name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options). No se copian: mcp_servers, los archivos adjuntos ni los campos file_types y default_file_id de cada variable.

Respuesta. 200 con el nuevo objeto Prompt y current_version.variables rellenado.

Errores. 404 {"error":"Prompt not found"}, 403 {"error":"You don't have access to this prompt"}, 404 {"error":"Project not found"}, 403 {"error":"You don't have access to manage prompts of this project"}.

PUT /prompt/:id/move-to-project

Mueve un prompt a un proyecto, de un proyecto a otro o fuera de un proyecto. Sin cuerpo. Necesitas permiso para gestionar prompts en todos los proyectos implicados, y un prompt que se mueve a un proyecto debe ser tuyo.

Respuesta. 200 con el objeto Prompt y project cargado.

Errores. 404 {"error":"Prompt not found"} o {"error":"Prompt not found or you don't have access to it"}, 400 {"error":"Prompt is already not in a project"}, 400 {"error":"Prompt is already in this project"}, 404 {"error":"Project not found"}, 403 si no tienes permisos sobre el proyecto.

PUT /prompt/:id/share_with_workspace

Hace visible uno de tus propios prompts para todo tu espacio de trabajo, o vuelve a hacerlo privado.

Respuesta. 200 con el objeto Prompt; shared_with_workspace_id es el ID de tu espacio de trabajo o null. Errores. 404 {"error":"Prompt not found"}, 400 {"error":"User is not part of a workspace"}.

Favoritos

GET /prompt/favorite

Devuelve tus prompts favoritos en el orden en que los marcaste (del más antiguo al más reciente). Todos los elementos llevan "is_favorite": true; no se cargan la versión, la categoría ni los archivos. Sin paginación.

POST /prompt/:id/favorite

Marca un prompt como favorito. Debe ser tuyo, estar compartido directamente contigo o pertenecer al catálogo público. Un prompt compartido solo con tu espacio de trabajo devuelve 403.

Respuesta. 201. La clave del prompt anidado se escribe de verdad con mayúscula inicial, Prompt:

{ "ID": 311, "CreatedAt": "2026-09-28T09:00:00Z", "UpdatedAt": "2026-09-28T09:00:00Z", "DeletedAt": null,
  "user_id": 7, "prompt_id": 42, "Prompt": null }

Errores. 404 {"error":"Prompt not found"}, 403 {"error":"You don't have access to this prompt"}, 409 {"error":"This prompt is already marked as favorite"}.

DELETE /prompt/:id/favorite

Quita un favorito.

Respuesta. 204. Errores. 404 {"error":"Prompt not found in favorites"}.

Variables

Las variables pertenecen a una versión del prompt. El slug debe coincidir con un marcador {{slug}} del contenido y ser único dentro de la versión. Consulta Variables de prompt para ver cómo se comportan en la aplicación.

{
  "ID": 301, "CreatedAt": "...", "UpdatedAt": "...", "DeletedAt": null,
  "prompt_version_id": 88,
  "name": "Customer name",
  "slug": "customer_name",
  "description": "Who the email is addressed to",
  "data_type": "short_text",
  "default_value": "",
  "required": true,
  "sort": 0,
  "is_primary": true,
  "is_multi_select": false,
  "options": null,
  "file_types": "",
  "default_file_id": null,
  "default_file": null
}

• data_type es short_text, long_text, select, number, json o lov.
• options (en las variables de tipo selección) es [{"label": "...", "value": "..."}].
• is_primary marca la variable que rellenan los atajos /run/prompt/last y /run/prompt/:id.

POST /variable

Añade una variable a una versión del prompt. El prompt debe ser tuyo. El cuerpo es el objeto Variable sin ID ni marcas de tiempo; el servidor solo valida estos tres campos.

Respuesta. 201 con el objeto Variable.

Errores. 400 si el JSON está mal formado, 404 {"error":"Prompt version not found"}, 403 {"error":"You are not allowed to add variables to this prompt"}, 409 {"error":"Entity already exists"} (slug duplicado).

PUT /variable/:id

Sustituye los campos de una variable. La actualización sobrescribe todos los campos, así que envíalos todos: name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options, file_types y default_file_id.

El historial se conserva: si cambias name o slug en una variable que ya tiene valores guardados de ejecuciones anteriores, el servidor primero archiva la variable antigua (una copia eliminada de forma lógica cuyo slug recibe el sufijo _deleted_<timestamp>), le traslada esos valores y después actualiza la variable en su sitio. En ese caso, file_types y default_file_id no se actualizan.

Respuesta. 200 con el objeto Variable. Errores. 404 {"error":"Variable not found"}, 403 {"error":"You are not allowed to update variables of this prompt"}.

DELETE /variable/:id

Elimina una variable.

Respuesta. 204. Errores. 404 {"error":"Variable not found"}, 403 {"error":"You are not allowed to delete variables of this prompt"}.

Instancias

Una instancia es la plantilla con los valores ya rellenados. Cada {{slug}} se sustituye por el valor que envías o, si el valor está vacío o falta, por el default_value de la variable. Los marcadores que no corresponden a ninguna variable se quedan como están. Si tu espacio de trabajo tiene guardrails, se aplican a los valores y al contenido procesado antes de guardar nada, así que los valores pueden volver enmascarados.

{
  "ID": 5120, "CreatedAt": "...", "UpdatedAt": "...", "DeletedAt": null,
  "prompt_version_id": 88,
  "content": "Write a renewal check-in email to Northwind Traders about their Business plan.",
  "variable_values": [
    { "ID": 9001, "variable_id": 301, "prompt_version_instance_id": 5120, "value": "Northwind Traders", "file_id": null, "file": null }
  ]
}

POST /instance

Rellena las variables de una versión y guarda el resultado como una instancia nueva, que además pasa a ser la instancia actual de la versión.

curl -X POST https://api.stickyprompts.com/api/v1/instance \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt_version_id":88,"variable_values":[{"variable_id":301,"value":"Northwind Traders"},{"variable_id":302,"value":"Business"}]}'

Respuesta. 201 con el objeto de la instancia.

Errores. 404 {"error":"Prompt version not found"}, 400 {"error":"Invalid instance request"} cuando una variable obligatoria no tiene un valor no vacío, 400 {"error":"...","code":"SENSITIVE_DATA_BLOCKED"} cuando un guardrail bloquea la entrada.

GET /instance/:id

Devuelve una instancia con sus variable_values. Si no existe, 404 con el cuerpo vacío.

Ejecución de prompts

Cómo se elige el modelo

Ninguno de ellos usa el enrutamiento automático de modelos; eso corresponde a los endpoints de conversaciones. Todos los endpoints de ejecución comprueban el modelo elegido con las reglas de acceso a modelos de tu espacio de trabajo (400 {"error":"The selected AI model has been restricted by your organization"}, con un texto ligeramente distinto en los atajos) y con las de residencia de datos (400 con un code de residencia).

El objeto RunHistory

{
  "id": 7781,
  "created_at": "2026-09-28T09:12:03Z",
  "result": "<p>Hi Northwind team, your Business plan renews on ...</p>\n",
  "raw_text": null,
  "thinking": "",
  "runtime": 4210,
  "ai_model_id": 12,
  "input_prompt": "Write a renewal check-in email to {{customer_name}} about their {{plan}} plan.",
  "variables": [],
  "conversation_context_id": 16044,
  "conversation_context_slug": "q8w2m1zc",
  "conversation_context_name": "",
  "is_interactive": true,
  "input_file_data": [],
  "output_file_data": [],
  "error_text": null,
  "error_id": null,
  "run_status": "success"
}

Ninguna respuesta de ejecución incluye el uso ni los créditos.

POST /instance/:id/run

Ejecuta una instancia y espera a que el modelo termine. Se crea una conversación nueva con el mensaje del usuario (el contenido procesado de la instancia) y la respuesta de la IA, salvo que indiques conversation_context_id. Si esa conversación tiene una comparación de modelos activa, la instancia se ejecuta una vez en cada hilo y se devuelven todos los resultados.

curl -X POST https://api.stickyprompts.com/api/v1/instance/5120/run \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ai_model_ids":[12],"ai_style":"prompty","tools":[{"name":"web_search","use":true}]}'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/instance/5120/run",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={"ai_model_ids": [12], "ai_style": "prompty",
          "tools": [{"name": "web_search", "use": True}]},
    timeout=300,
)
r.raise_for_status()
for run in r.json():
    if run["run_status"] == "error":
        print("Failed:", run["error_text"], run["error_id"])
    else:
        print(run["conversation_context_id"], run["result"])  # result is HTML

const res = await fetch("https://api.stickyprompts.com/api/v1/instance/5120/run", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ai_model_ids: [12],
    ai_style: "prompty",
    tools: [{ name: "web_search", use: true }],
  }),
});
const runs = await res.json(); // one RunHistory per model
for (const run of runs) console.log(run.run_status, run.error_id ?? run.result);

Respuesta. 200 con un array de objetos RunHistory, uno por modelo.

Errores

POST /instance/:id/run/stream

Acepta la misma ruta, los mismos parámetros de consulta, headers y cuerpo que /run, y aplica la misma validación, pero no transmite en streaming por esta respuesta HTTP. En su lugar:

1. El servidor crea las ejecuciones y la conversación, inicia la generación en segundo plano y devuelve 200 de inmediato con un array de objetos RunHistory con run_status: "pending", result: "" y runtime: 0, cada uno con un conversation_context_id válido.
2. Los tokens se envían al WebSocket de la conversación, GET /conversation/{conversation_context_id}/ws. Este acepta el mismo header Authorization: Bearer y requiere el permiso conversations_get. Los clientes del lado del servidor pueden enviar ese header; los navegadores, no.
3. Cada trama es un mensaje de texto JSON {"type": ..., "data": ...}:

4. Después de ai_message_end, lee el estado final con GET /conversation/:id.

Los eventos enviados antes de que se conecte ningún cliente se guardan en búfer y se reenvían a la primera conexión, así que puedes abrir el socket justo después de que responda el POST. Tu propio mensaje de usuario no se reenvía. Una vez que el POST ha devuelto 200, los errores del proveedor solo llegan como tramas error_message; los errores anteriores a la generación (límite de modelos, plan gratuito, residencia de datos) se devuelven con los estados distintos de 200 indicados para /run. El endpoint SSE heredado GET /conversation/:id/stream no retransmite las instantáneas de los mensajes de estas ejecuciones, así que usa el WebSocket. Encontrarás todos los detalles del WebSocket y ejemplos de cliente en Conversaciones y mensajes.

POST /run/prompt/last

Repite tu ejecución de prompt más reciente con nuevos «datos principales». Está pensado para repeticiones rápidas, por ejemplo desde una extensión del navegador. Toma la ejecución más reciente de cualquier prompt que sea tuyo o esté compartido contigo, crea una instancia nueva en la que la variable principal (o la única variable) recibe data y las demás conservan el valor de esa ejecución (o su valor predeterminado), y la ejecuta con el mismo modelo y las mismas herramientas, y con el ai_style del prompt. Se crea una conversación interactiva nueva (origen extension).

Respuesta. 200 con un único objeto RunHistory, no un array.

Errores. 404 {"error":"No runs found"}, 400 {"error":"Invalid instance request"} cuando una variable obligatoria queda vacía, 400 si el modelo está restringido o hay un bloqueo de residencia de datos o de datos sensibles, 429 si se supera la cuota. Si la llamada al modelo falla antes de que se registre una ejecución, la solicitud falla con 500.

POST /run/prompt/:id

Igual que /run/prompt/last, pero para un prompt concreto. Repite la ejecución más reciente del prompt con data en la variable principal. Si el prompt nunca se ha ejecutado y es tuyo, se crea una primera ejecución con los valores predeterminados de las variables y el ai_model_id del prompt. La ejecución que se repite es la más reciente del prompt en general, no solo la tuya, así que en un prompt compartido los valores de las variables no principales pueden proceder de la última ejecución de otro usuario.

curl -X POST https://api.stickyprompts.com/api/v1/run/prompt/42 \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"Northwind Traders"}'

Respuesta. 200 con un único objeto RunHistory. Errores. 404 {"error":"Prompt not found"}, además de los errores de /run/prompt/last.

POST /run/prompt/:id/variables

Ejecuta la versión actual de un prompt con un conjunto completo de valores de variables: crea la instancia y la ejecuta en una sola llamada. Usa el ai_model_id y el ai_style del prompt. La nueva instancia pasa a ser la instancia actual de la versión, y se crea una conversación interactiva nueva (origen extension).

curl -X POST https://api.stickyprompts.com/api/v1/run/prompt/42/variables \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variable_values":[{"variable_id":301,"value":"Northwind Traders"},{"variable_id":302,"value":"Business"}]}'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/run/prompt/42/variables",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={"variable_values": [
        {"variable_id": 301, "value": "Northwind Traders"},
        {"variable_id": 302, "value": "Business"},
    ]},
    timeout=300,
)
run = r.json()
print(run["run_status"], run["result"])

const run = await fetch("https://api.stickyprompts.com/api/v1/run/prompt/42/variables", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    variable_values: [
      { variable_id: 301, value: "Northwind Traders" },
      { variable_id: 302, value: "Business" },
    ],
  }),
}).then((r) => r.json());
console.log(run.run_status, run.result);

Respuesta. 200 con un único objeto RunHistory.

Errores. 404 {"error":"Prompt not found"}, 400 si el modelo está restringido o hay un bloqueo de residencia de datos o de datos sensibles, 429 si se supera la cuota, 503 {"error":"..."} si falla la ejecución.

La herramienta MCP run_prompt hace lo mismo con un mapa de slugs de variables a valores; solo devuelve el texto y no crea una conversación interactiva.

POST /run

Envía texto libre a un modelo y devuelve la respuesta, sin prompt, sin variables y sin conversación. La llamada es síncrona. No se añade ningún prompt de sistema, prompt del espacio de trabajo ni instrucciones de proyecto, el estilo es siempre prompty y no se guarda nada como conversación. El uso se registra igualmente.

curl -X POST https://api.stickyprompts.com/api/v1/run \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Suggest a subject line for a Northwind renewal email.","ai_model_id":12}'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/run",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={"prompt": "Suggest a subject line for a Northwind renewal email.", "ai_model_id": 12},
    timeout=300,
)
r.raise_for_status()
print(r.json()["text"])  # raw Markdown

const msg = await fetch("https://api.stickyprompts.com/api/v1/run", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt: "Suggest a subject line for a Northwind renewal email.", ai_model_id: 12 }),
}).then((r) => r.json());
console.log(msg.text); // raw Markdown

Respuesta. 200 con un objeto Message que no se guarda: su ID es 0 y sus marcas de tiempo tienen el valor cero. text contiene el Markdown original del modelo, a diferencia de los endpoints de ejecución, que devuelven HTML.

{
  "ID": 0, "CreatedAt": "0001-01-01T00:00:00Z", "UpdatedAt": "0001-01-01T00:00:00Z", "DeletedAt": null,
  "conversation_context_id": null,
  "ai_model_id": 12,
  "text": "Your Northwind plan renews soon - here is what is new",
  "isUser": false,
  "error_text": null, "error_id": null,
  "ai_style": "prompty",
  "status": "finished",
  "type": "normal"
}

Errores. 404 {"error":"AI model not found"}, 400 si el modelo está restringido o hay un bloqueo de residencia de datos o de datos sensibles, 429 si se supera la cuota, 500 {"error":"..."} cuando falla la llamada al modelo (este endpoint usa 500, no 503).

GET /prompt/:id/run_history

Devuelve tu historial de ejecuciones de Prompt Studio para un prompt, empezando por la conversación más reciente. Solo se incluyen las conversaciones que tú iniciaste con is_prompt_studio: true.

Respuesta. 200 con un array de arrays de objetos RunHistory: un array interno por conversación, con varios elementos cuando esa ejecución comparó modelos. Aquí sí se rellena variables. Si no hay nada, [].

Archivos de prompts

Archivos adjuntos al propio prompt. Los modelos con protocolo OpenAI los usan mediante búsqueda de archivos; los modelos de Together los reciben como un mensaje adicional del usuario; para otros proveedores, no está documentado cómo se usan. Sube primero los archivos con POST /file.

POST /prompt/:id/file

Vincula archivos subidos a un prompt. Los archivos vinculados anteriormente siguen vinculados.

Respuesta. 200 con el objeto Prompt; file_data solo incluye los archivos añadidos en esta llamada.

Errores. 400 {"error":"Invalid request body"}, 400 {"error":"Invalid prompt ID"}, 404 {"error":"Prompt not found"}, 400 {"error":"File not found"}.

GET /prompt/:id/file

Devuelve un array de objetos File vinculados al prompt. 400 si id no es numérico.

DELETE /prompt/:id/file/:fileId

Desvincula un archivo de uno de tus propios prompts. Si ningún otro prompt ni mensaje usa el archivo, también se elimina el archivo almacenado.

Respuesta. 204. Errores. 404 {"error":"Prompt not found"}, 403 {"error":"You do not have permission to delete this file from the prompt"}, 404 {"error":"File not found"}, 502 {"error":"Failed to delete file"}.

Compartir con usuarios concretos

GET /share

Devuelve los prompts compartidos contigo, del más reciente al más antiguo.

Respuesta. 200 con un array de objetos Prompt, cada uno con un objeto shared_by. scope=workspace sin espacio de trabajo devuelve []; en los demás ámbitos, un resultado vacío es null, no [].

[{ "ID": 42, "name": "Renewal check-in email", "...": "...",
   "shared_by": { "email": "john.smith@northwind.example", "first_name": "John", "last_name": "Smith" } }]

Errores. 400 {"error":"Invalid scope parameter"}.

GET /prompt/:id/share

Lista los usuarios con los que se comparte un prompt. Cada Share incluye un objeto user completo.

[{ "ID": 55, "CreatedAt": "...", "UpdatedAt": "...", "DeletedAt": null,
   "user_id": 19, "user": { "ID": 19, "email": "anna@northwind.example", "first_name": "Anna", "status": "active", "...": "..." },
   "prompt_id": 42, "read_only": true }]

POST /share/:id

Comparte el prompt :id en modo de solo lectura con un usuario, mediante su correo electrónico. Si no existe ninguna cuenta con ese correo, el servidor crea una cuenta invitada y envía un correo de invitación; a un usuario ya invitado se le vuelve a enviar la invitación.

Respuesta. 200 con el cuerpo vacío. Errores. 404 {"error":"prompt not found"}, 400 {"error":"invalid email format"}, 400 {"error":"share already exists"}, 400 {"error":"..."} cuando falla la invitación.

POST /share/:id/resend

Vuelve a enviar el correo de invitación a un usuario que aún no se ha registrado.

Respuesta. 204. Errores. 400 {"error":"invalid email format"}, 404 {"error":"prompt not found"}, 404 {"error":"user not found"}, 400 {"error":"user not invited or already registered"}, 404 {"error":"share not found"}.

DELETE /share/:id

Elimina una compartición y cancela las invitaciones pendientes de ese usuario.

Respuesta. 204. Errores. 404 {"error":"share not found"}.

Contenido relacionado

• Conversaciones y mensajes - continúa la conversación de una ejecución y recibe las respuestas en streaming.
• Biblioteca de prompts y Variables de prompt - las mismas funciones en la aplicación.
• Referencia de herramientas de MCP - list_prompts, get_prompt, run_prompt, custom_run.