Inicio rápido

Esta página te lleva de cero a hacer llamadas que funcionan contra la API REST de StickyPrompts. Cada ejemplo está disponible en cURL, Python (requests) y JavaScript (fetch, Node 18 o posterior). La misma clave sirve también para el servidor MCP, así que, una vez que la tengas, también podrás conectar Claude Code o Cursor.

Todas las rutas REST son relativas a https://api.stickyprompts.com/api/v1.

Tutorial 12 de 14 · 1:53 The API Vídeo en inglés, grabado en la aplicación real

Consejo · 0:17 Ask a model from any script Vídeo en inglés, grabado en la aplicación real

1. Crea una clave de API

1. Abre Settings > API keys

   En la aplicación, ve a Settings y selecciona API keys. La página muestra las dos URL base y el header exacto que debes enviar.

   app.stickyprompts.com/settings#api 1 Crea una clave 2 URL base de REST 3 Endpoint MCP 4 Envía este header

2. Genera una clave con los permisos que necesitas

   Selecciona Generate key, ponle un nombre a la clave (por ejemplo, Quickstart) y marca sus permisos. Para esta página necesitas:

   • ai_models_get: consultar los modelos
   • custom_run: preguntar directamente a un modelo
   • conversations_manage: iniciar y continuar conversaciones
   • prompts_get y run_prompt: buscar y ejecutar prompts guardados
3. Copia la clave ahora

   La clave completa (STICKY-API- seguido de 64 caracteres) se muestra una sola vez. Cópiala directamente en tu gestor de secretos. Si la pierdes, elimina la clave y genera una nueva.

2. Guárdala en una variable de entorno

No pongas la clave en tu código. Todos los ejemplos de abajo la leen de STICKY_API_KEY.

export STICKY_API_KEY="STICKY-API-..."

Cada petición la envía como token Bearer:

Authorization: Bearer STICKY-API-...

3. Consulta los modelos que puedes usar

Los modelos se identifican por su ID numérico, que otros endpoints reciben como ai_model_id. Añade legacy=false para ocultar los modelos obsoletos y usa los modelos cuyo selectable sea true. Un valor false significa que las reglas de acceso a modelos o de residencia de datos de tu espacio de trabajo te lo bloquean.

curl "https://api.stickyprompts.com/api/v1/ai_model?legacy=false" \
  -H "Authorization: Bearer $STICKY_API_KEY"

import os
import requests

BASE = "https://api.stickyprompts.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"}

r = requests.get(f"{BASE}/ai_model", params={"legacy": "false"}, headers=HEADERS)
r.raise_for_status()
for m in r.json():
    if m["selectable"]:
        print(m["ID"], m["name"], m["powered_by"])

const BASE = "https://api.stickyprompts.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.STICKY_API_KEY}` };

const res = await fetch(`${BASE}/ai_model?legacy=false`, { headers });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
for (const m of await res.json()) {
  if (m.selectable) console.log(m.ID, m.name, m.powered_by);
}

La respuesta es un array JSON. Aquí se muestran solo los campos más útiles (los valores son ilustrativos):

[
  {
    "ID": 42,
    "name": "Claude Sonnet 5",
    "powered_by": "Anthropic",
    "description": "Balanced model for everyday work.",
    "flagship": true,
    "deprecated": false,
    "thinking_model": true,
    "reasoning_efforts": ["low", "medium", "high"],
    "tools": ["file_upload", "web_search", "remote_mcp"],
    "multiplier": "1",
    "stream_support": true,
    "selectable": true
  }
]

Fíjate en que las mayúsculas no son uniformes: ID va en mayúsculas y todo lo demás en snake_case. Los valores decimales, como multiplier, llegan como cadenas. Consulta Errores, paginación y cuotas.

4. Hazle una pregunta a un modelo

POST /run envía un texto a un modelo y devuelve su respuesta. No se guarda nada como conversación ni se añade ningún prompt de sistema, prompt del espacio de trabajo ni instrucciones de proyecto. El uso sí se registra.

curl -X POST https://api.stickyprompts.com/api/v1/run \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a one-line tagline for Northwind Analytics.", "ai_model_id": 42}'

r = requests.post(
    f"{BASE}/run",
    headers=HEADERS,
    json={"prompt": "Write a one-line tagline for Northwind Analytics.", "ai_model_id": 42},
)
r.raise_for_status()
print(r.json()["text"])

const res = await fetch(`${BASE}/run`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "Write a one-line tagline for Northwind Analytics.",
    ai_model_id: 42,
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log((await res.json()).text);

La respuesta es un objeto de mensaje sin guardar (su ID es 0). La respuesta del modelo está en text, en Markdown sin procesar:

{
  "ID": 0,
  "ai_model_id": 42,
  "text": "Northwind Analytics: see what sells before it sells out.",
  "isUser": false,
  "status": "finished",
  "ai_style": "prompty",
  "error_text": null,
  "error_id": null
}

5. Inicia una conversación y envía un mensaje de seguimiento

Una conversación se guarda y aparece en tu Chat History en la aplicación, igual que un chat que hayas iniciado allí. POST /conversation la crea, envía el primer mensaje y espera a tener la respuesta completa. Indica siempre un modelo: o bien ai_model_id, o bien auto_model_type (best, balanced o cheapest) para que StickyPrompts elija el mejor modelo para cada mensaje.

curl -X POST https://api.stickyprompts.com/api/v1/conversation \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Draft three subject lines for the Northwind Q4 newsletter.",
    "ai_model_id": 42
  }'

r = requests.post(
    f"{BASE}/conversation",
    headers=HEADERS,
    json={
        "message": "Draft three subject lines for the Northwind Q4 newsletter.",
        "ai_model_id": 42,
    },
)
r.raise_for_status()
reply = r.json()
conversation_id = reply["conversation_context_id"]
print(reply["raw_text"])

const res = await fetch(`${BASE}/conversation`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    message: "Draft three subject lines for the Northwind Q4 newsletter.",
    ai_model_id: 42,
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const reply = await res.json();
const conversationId = reply.conversation_context_id;
console.log(reply.raw_text);

La respuesta es el mensaje terminado de la IA. Su conversation_context_id es el ID de la nueva conversación (versión abreviada):

{
  "ID": 90412,
  "CreatedAt": "2026-09-28T09:14:03.512Z",
  "conversation_context_id": 5120,
  "ai_model_id": 42,
  "is_auto_model": false,
  "text": "Here are three options for the subject line: ...",
  "raw_text": "Here are three options for the subject line: ...",
  "isUser": false,
  "status": "finished",
  "error_text": null,
  "error_id": null,
  "response_duration_ms": 6210,
  "attachments": []
}

Para enviar un mensaje de seguimiento a la misma conversación, usa POST /conversation/{id}. Los mensajes de seguimiento solo reciben el mensaje (y, opcionalmente, archivos adjuntos, bases de conocimiento y herramientas); la conversación conserva su modelo.

curl -X POST https://api.stickyprompts.com/api/v1/conversation/5120 \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Make the second one shorter and more playful."}'

r = requests.post(
    f"{BASE}/conversation/{conversation_id}",
    headers=HEADERS,
    json={"message": "Make the second one shorter and more playful."},
)
r.raise_for_status()
print(r.json()["raw_text"])

const res2 = await fetch(`${BASE}/conversation/${conversationId}`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Make the second one shorter and more playful." }),
});
if (!res2.ok) throw new Error(`${res2.status} ${await res2.text()}`);
console.log((await res2.json()).raw_text);

La respuesta tiene la misma estructura de mensaje. Para respuestas largas puedes usar en su lugar POST /conversation/stream, que devuelve el ID de la conversación de inmediato y entrega la respuesta por un WebSocket (consulta Conversaciones y mensajes).

6. Ejecuta un prompt guardado con variables

Los prompts guardados contienen {{variables}}. Este endpoint las rellena y ejecuta el prompt en una sola llamada, con el modelo y el estilo de respuesta del propio prompt. Crea una nueva conversación.

Necesitas dos tipos de ID:

• El ID del prompt. Lista tus prompts con GET /prompt (permiso prompts_get) y lee el ID de cada uno.
• Los ID de las variables. Cada elemento de variable_values identifica una variable por su variable_id numérico. Una clave de API no puede leer un prompt concreto con sus variables (GET /prompt/:id no está disponible para las claves), así que obtén los ID de una de estas fuentes: el historial de ejecuciones del prompt (GET /prompt/:id/run_history muestra las variables de cada ejecución con variable_id, slug y value), una instancia (GET /instance/:id) o la respuesta de POST /variable si creaste la variable mediante la API. Búscalos una vez y guárdalos en tu configuración. Consulta Prompts y ejecuciones.

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": "Bluebird Market"},
      {"variable_id": 302, "value": "Growth plan renewal"}
    ]
  }'

r = requests.post(
    f"{BASE}/run/prompt/42/variables",
    headers=HEADERS,
    json={
        "variable_values": [
            {"variable_id": 301, "value": "Bluebird Market"},
            {"variable_id": 302, "value": "Growth plan renewal"},
        ]
    },
)
r.raise_for_status()
run = r.json()
print(run["run_status"], run["result"])

const res3 = await fetch(`${BASE}/run/prompt/42/variables`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    variable_values: [
      { variable_id: 301, value: "Bluebird Market" },
      { variable_id: 302, value: "Growth plan renewal" },
    ],
  }),
});
if (!res3.ok) throw new Error(`${res3.status} ${await res3.text()}`);
const run = await res3.json();
console.log(run.run_status, run.result);

Las variables que omitas, o que envíes vacías, toman su valor predeterminado. La respuesta es un único objeto de ejecución (versión abreviada):

{
  "id": 7781,
  "created_at": "2026-09-28T09:12:03Z",
  "result": "<p>Hi Sarah, it has been a great year with Bluebird Market ...</p>\n",
  "raw_text": null,
  "runtime": 4210,
  "ai_model_id": 42,
  "conversation_context_id": 16044,
  "conversation_context_slug": "q8w2m1zc",
  "error_text": null,
  "error_id": null,
  "run_status": "success"
}

Tres cosas que debes saber:

• result es HTML generado a partir del Markdown del modelo. Para obtener el Markdown sin procesar, lee la conversación con GET /conversation/16044.
• Un fallo del proveedor sigue devolviendo 200, con run_status: "error" y con error_text / error_id informados. Comprueba run_status.
• Si solo necesitas cambiar una entrada, POST /run/prompt/:id con {"data": "..."} repite la última ejecución del prompt con un texto nuevo en su variable principal, sin necesidad de ID de variables.

Próximos pasos