Avvio rapido

Questa pagina ti porta da zero alle prime chiamate funzionanti verso l’API REST di StickyPrompts. Ogni esempio è disponibile in cURL, Python (requests) e JavaScript (fetch, Node 18 o successivo). La stessa chiave funziona anche con il server MCP, quindi una volta ottenuta puoi collegare anche Claude Code o Cursor.

Tutti i percorsi REST sono relativi a https://api.stickyprompts.com/api/v1.

Tutorial 12 di 14 · 1:53 The API Video in inglese, registrato nell'app reale

Suggerimento · 0:17 Ask a model from any script Video in inglese, registrato nell'app reale

1. Crea una chiave API

1. Apri Settings > API keys

   Nell’app vai in Settings e seleziona API keys. La pagina mostra entrambi gli URL di base e l’header esatto da inviare.

   app.stickyprompts.com/settings#api 1 Crea una chiave 2 URL di base REST 3 Endpoint MCP 4 Invia questo header

2. Genera una chiave con le autorizzazioni necessarie

   Seleziona Generate key, dai un nome alla chiave (per esempio Quickstart) e spunta le sue autorizzazioni. Per questa pagina ti servono:

   • ai_models_get - elencare i modelli
   • custom_run - interrogare direttamente un modello
   • conversations_manage - avviare e proseguire conversazioni
   • prompts_get e run_prompt - trovare ed eseguire i prompt salvati
3. Copia subito la chiave

   La chiave completa (STICKY-API- seguito da 64 caratteri) viene mostrata una sola volta. Copiala subito nel tuo archivio di segreti. Se la perdi, elimina la chiave e generane una nuova.

2. Salvala in una variabile d’ambiente

Tieni la chiave fuori dal codice. Tutti gli esempi qui sotto la leggono da STICKY_API_KEY.

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

Ogni richiesta la invia come bearer token:

Authorization: Bearer STICKY-API-...

3. Elenca i modelli che puoi usare

I modelli sono identificati dal loro ID numerico, che gli altri endpoint accettano come ai_model_id. Aggiungi legacy=false per nascondere i modelli deprecati e usa i modelli con selectable a true: false significa che le regole di accesso ai modelli o di residenza dei dati del tuo workspace te li bloccano.

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 risposta è un array JSON, qui ridotto ai campi più utili (i valori sono indicativi):

[
  {
    "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
  }
]

Nota le maiuscole miste: ID ha l’iniziale maiuscola, tutto il resto è in snake_case. I valori decimali come multiplier arrivano come stringhe. Consulta Errori, paginazione e quote.

4. Fai una domanda a un modello

POST /run invia un testo a un modello e restituisce la sua risposta. Non viene salvata alcuna conversazione e non vengono aggiunti system prompt, prompt del workspace o istruzioni di progetto. L’utilizzo viene comunque registrato.

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 risposta è un oggetto messaggio non salvato (il suo ID è 0). La risposta del modello è in text, in Markdown grezzo:

{
  "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. Avvia una conversazione e invia un messaggio successivo

Una conversazione viene salvata e compare nella tua Chat History nell’app, proprio come una chat avviata lì. POST /conversation la crea, invia il primo messaggio e attende la risposta completa. Passa sempre un modello: ai_model_id, oppure auto_model_type (best, balanced o cheapest) per lasciare che StickyPrompts scelga il modello migliore per ogni messaggio.

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 risposta è il messaggio completo dell’IA. Il suo conversation_context_id è l’ID della nuova conversazione (estratto):

{
  "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": []
}

Per proseguire la stessa conversazione usa POST /conversation/{id}. I messaggi successivi accettano solo il messaggio (più, facoltativamente, allegati, knowledge base e strumenti); la conversazione mantiene il suo modello.

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 risposta ha la stessa forma di messaggio. Per le risposte lunghe puoi usare invece POST /conversation/stream, che restituisce subito l’ID della conversazione e consegna la risposta tramite WebSocket: consulta Conversazioni e messaggi.

6. Esegui un prompt salvato con le variabili

I prompt salvati contengono {{variables}}. Questo endpoint le compila ed esegue il prompt in un’unica chiamata, usando il modello e lo stile di risposta del prompt stesso. Crea una nuova conversazione.

Ti servono due tipi di ID:

• L’ID del prompt. Elenca i tuoi prompt con GET /prompt (autorizzazione prompts_get) e leggi l’ID di ciascuno.
• Gli ID delle variabili. Ogni elemento di variable_values indica una variabile tramite il suo variable_id numerico. Una chiave API non può leggere un singolo prompt con le sue variabili (GET /prompt/:id non è accessibile alle chiavi), quindi ricava gli ID da una di queste fonti: la cronologia delle esecuzioni del prompt (GET /prompt/:id/run_history elenca le variabili di ogni esecuzione con variable_id, slug e value), un’istanza (GET /instance/:id) oppure la risposta di POST /variable, se hai creato la variabile tramite l’API. Recuperali una volta e salvali nella tua configurazione. Consulta Prompt ed esecuzioni.

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);

Le variabili che ometti, o che invii vuote, assumono il loro valore predefinito. La risposta è un singolo oggetto di esecuzione (estratto):

{
  "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"
}

Tre cose da sapere:

• result è HTML generato dal Markdown del modello. Per il Markdown grezzo, leggi la conversazione con GET /conversation/16044.
• Un errore del provider restituisce comunque 200, con run_status: "error" e error_text / error_id valorizzati. Controlla run_status.
• Se devi cambiare un solo input, POST /run/prompt/:id con {"data": "..."} ripete l’ultima esecuzione del prompt con un nuovo testo nella sua variabile principale, senza bisogno degli ID delle variabili.

Passi successivi