Prompt ed esecuzioni

Un prompt salvato è un modello riutilizzabile della tua libreria di prompt. Il suo testo contiene delle {{variables}} che compili a ogni esecuzione. Con l’API REST puoi creare prompt dal codice, eseguirli con valori sempre nuovi sul modello che preferisci e rileggerne i risultati. Ogni richiesta viene eseguita come l’utente proprietario della chiave API.

Tutti i percorsi sono relativi a https://api.stickyprompts.com/api/v1. I corpi delle richieste sono in JSON.

Concetti chiave

Un prompt è un modello con un nome. Il suo testo si trova in una versione del prompt: ogni prompt ha una sola versione e, quando invii nuovo contenuto, questo la sovrascrive. Una versione ha delle variabili, richiamate nel testo come {{slug}}, per esempio Write a {{tone}} summary of: {{text}}.

Per eseguire un prompt ne compili le variabili. Così crei un’istanza: una copia immutabile del modello con i valori sostituiti. Poi esegui l’istanza su uno o più modelli. Ogni esecuzione crea una conversazione (chiamata conversation_context nell’API) in cui puoi continuare a chattare tramite gli endpoint descritti in Conversazioni e messaggi.

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

Gli endpoint scorciatoia sotto /run/prompt/... creano l’istanza e la eseguono in un’unica chiamata. POST /run invia testo libero a un modello senza alcun prompt.

Convenzioni

• Paginazione. Dove indicato, invia page (predefinito 1) e size (predefinito 10). Gli header di risposta X-Page, X-Page-Size e X-Total-Count descrivono il risultato. Vedi Errori, paginazione e quote.
• Ambito di progetto. Diversi endpoint leggono un header facoltativo X-Project-ID: <numeric id>. Un valore non numerico viene trattato come assente.
• Maiuscole e minuscole nei campi. Gli oggetti del database usano ID, CreatedAt, UpdatedAt e DeletedAt con l’iniziale maiuscola accanto a campi in snake_case. Il risultato RunHistory usa invece id e created_at in minuscolo.
• Testo renderizzato. I campi result e thinking di un’esecuzione contengono HTML generato a partire dal Markdown del modello, non il Markdown originale.
• Errori: hanno la forma {"error": "..."}. Il superamento delle quote restituisce 429 {"error":"Quota exceeded","reason":"..."}. I blocchi dei guardrail aggiungono un codice leggibile dalle macchine, per esempio {"error": "...", "code": "SENSITIVE_DATA_BLOCKED"}. Gli errori di residenza dei dati usano i codici EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED e NO_ENDPOINT_AVAILABLE.

L’oggetto 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 è {ID, ..., prompt_id, content, variables[], current_instance_id, current_instance} quando viene caricato; la maggior parte degli endpoint di elenco lo lascia a null.
• category è {ID, CreatedAt, UpdatedAt, DeletedAt, name} quando viene caricato.
• file_data è un array di oggetti File quando viene caricato, altrimenti null. Un File ha la forma {ID, CreatedAt, UpdatedAt, DeletedAt, name, path, preview_path, public_path, user_id, workspace_id, project_id, fileType, partial}; nota fileType in camelCase.
• tools è [{"name", "use"}] oppure null. Nomi degli strumenti: web_search, image_generation, video_generation, speech_generation, music_generation, remote_mcp.
• mcp_servers è un array di ID di server MCP remoti.

Prompt

GET /prompt

Elenca i tuoi prompt che non appartengono a un progetto, dal più recente. Con X-Project-ID elenca invece i prompt di quel progetto.

Risposta. 200 con un array di oggetti Prompt (current_version, category e file_data non vengono caricati). Con X-Project-ID ogni elemento ha anche "can_delete": bool, che vale true solo se puoi gestire i prompt del progetto e quel prompt è tuo.

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

GET /prompt/all

Restituisce in un unico elenco i tuoi prompt, quelli condivisi con te e quelli che hai aggiunto ai preferiti, ordinati in base all’ultima volta in cui li hai eseguiti (in mancanza, in base alla data di creazione). I prompt che si trovano in un progetto sono esclusi.

Risposta. 200 con un array di oggetti Prompt con file_data caricato, oppure [].

GET /prompt/last_used

Restituisce fino a 8 prompt che hai eseguito, a partire da quello eseguito più di recente, con file_data caricato. I prompt che non hai mai eseguito non compaiono. Gli header di paginazione sono presenti, ma page e size vengono ignorati.

GET /prompt/most_used

Restituisce fino a 8 prompt, ordinati in base a quante volte li hai eseguiti. Nessun header di paginazione.

GET /prompt/recently_added

Restituisce fino a 8 dei tuoi prompt, dal più recente, con file_data caricato.

POST /prompt

Crea un prompt. Il prompt nasce senza versione: chiama subito dopo POST /prompt_version per dargli un contenuto. Il modello viene preso dalle tue preferenze (o è il primo modello del catalogo) e ai_style dalle tue preferenze (o è prompty). Per cambiarli, chiama poi PUT /prompt/:id.

ai_model_id, ai_style e slug vengono ignorati alla creazione; lo slug viene generato in modo casuale.

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

Risposta. 201 con l’oggetto Prompt.

Errori. 400 JSON non valido, 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

Sostituisce i campi modificabili di un prompt. Solo per i tuoi prompt.

name, description, ai_model_id, example_output, category_id e ai_style vengono sovrascritti tutti, quindi invia sempre i valori attuali dei campi che non vuoi modificare.

Risposta. 200 con l’oggetto Prompt. Errori. 404 {"error":"Prompt not found"}, 400 {"error":"Name is required"}.

POST /prompt_version

Imposta il contenuto del modello di un prompt. La prima chiamata crea la versione e la rende quella corrente; le chiamate successive sovrascrivono content sulla stessa versione. Le variabili si creano con POST /variable, non tramite questo corpo.

Risposta. 201 sia alla creazione sia all’aggiornamento:

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

Nel percorso di aggiornamento variables non viene caricato. Errori. 400 JSON non valido, 404 {"error":"Prompt not found"}.

DELETE /prompt/:id

Esegue un’eliminazione logica (soft delete) di uno dei tuoi prompt e ne rimuove le condivisioni e la presenza tra i preferiti di tutti gli utenti.

Risposta. 204. 404 con corpo vuoto quando il prompt non esiste o non è tuo.

POST /prompt/:id/duplicate

Copia un prompt di tua proprietà o a cui hai accesso (il catalogo pubblico, i prompt condivisi con te, i prompt condivisi con il tuo workspace). La copia include nome, descrizione, modello, output di esempio, strumenti, stile, categoria, contenuto della versione e variabili (name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options). Non vengono copiati: mcp_servers, i file allegati e, per ogni variabile, file_types e default_file_id.

Risposta. 200 con il nuovo oggetto Prompt e current_version.variables compilato.

Errori. 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

Sposta un prompt in un progetto, da un progetto a un altro oppure fuori da un progetto. Nessun corpo. Ti serve l’autorizzazione a gestire i prompt in ogni progetto coinvolto, e un prompt spostato in un progetto deve essere tuo.

Risposta. 200 con l’oggetto Prompt e project caricato.

Errori. 404 {"error":"Prompt not found"} oppure {"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 senza le autorizzazioni sul progetto.

PUT /prompt/:id/share_with_workspace

Rende uno dei tuoi prompt visibile a tutto il workspace, oppure di nuovo privato.

Risposta. 200 con l’oggetto Prompt; shared_with_workspace_id è l’ID del tuo workspace oppure null. Errori. 404 {"error":"Prompt not found"}, 400 {"error":"User is not part of a workspace"}.

Preferiti

GET /prompt/favorite

Restituisce i tuoi prompt preferiti nell’ordine in cui li hai aggiunti (dal meno recente). Ogni elemento ha "is_favorite": true; versione, categoria e file non vengono caricati. Nessuna paginazione.

POST /prompt/:id/favorite

Aggiunge un prompt ai preferiti. Il prompt deve essere tuo, condiviso direttamente con te oppure un prompt del catalogo pubblico. Un prompt condiviso solo con il tuo workspace restituisce 403.

Risposta. 201. La chiave annidata del prompt è davvero Prompt, con la maiuscola:

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

Errori. 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

Rimuove un prompt dai preferiti.

Risposta. 204. Errori. 404 {"error":"Prompt not found in favorites"}.

Variabili

Le variabili appartengono a una versione del prompt. Lo slug deve corrispondere a un segnaposto {{slug}} nel contenuto ed essere univoco all’interno della versione. Per il loro funzionamento nell’app, vedi Variabili del prompt.

{
  "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 vale short_text, long_text, select, number, json o lov.
• options (per le variabili a selezione) è [{"label": "...", "value": "..."}].
• is_primary indica la variabile che viene compilata dalle scorciatoie /run/prompt/last e /run/prompt/:id.

POST /variable

Aggiunge una variabile a una versione del prompt. Il prompt deve essere tuo. Il corpo è l’oggetto Variable senza ID e timestamp; il server convalida solo i tre campi obbligatori.

Risposta. 201 con l’oggetto Variable.

Errori. 400 JSON non valido, 404 {"error":"Prompt version not found"}, 403 {"error":"You are not allowed to add variables to this prompt"}, 409 {"error":"Entity already exists"} (slug duplicato).

PUT /variable/:id

Sostituisce i campi di una variabile. L’aggiornamento sovrascrive tutti i campi, quindi inviali tutti: name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options, file_types e default_file_id.

La cronologia viene preservata: se cambi name o slug di una variabile che ha già valori salvati da esecuzioni precedenti, il server archivia prima la vecchia variabile (una copia eliminata logicamente, il cui slug riceve il suffisso _deleted_<timestamp>), sposta quei valori sulla copia e poi aggiorna la variabile sul posto. In questo caso file_types e default_file_id non vengono aggiornati.

Risposta. 200 con l’oggetto Variable. Errori. 404 {"error":"Variable not found"}, 403 {"error":"You are not allowed to update variables of this prompt"}.

DELETE /variable/:id

Elimina una variabile.

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

Istanze

Un’istanza è il modello con i valori compilati. Ogni {{slug}} viene sostituito dal valore che hai inviato, oppure dal default_value della variabile quando il valore è vuoto o manca. I segnaposto che non corrispondono ad alcuna variabile restano invariati. Se il tuo workspace ha dei guardrail, questi vengono applicati ai valori e al contenuto elaborato prima che venga salvato qualsiasi dato, quindi i valori possono tornare oscurati.

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

Compila le variabili di una versione e salva il risultato come nuova istanza, che diventa anche l’istanza corrente della versione.

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"}]}'

Risposta. 201 con l’oggetto istanza.

Errori. 404 {"error":"Prompt version not found"}, 400 {"error":"Invalid instance request"} quando una variabile obbligatoria non ha un valore non vuoto, 400 {"error":"...","code":"SENSITIVE_DATA_BLOCKED"} quando un guardrail blocca l’input.

GET /instance/:id

Restituisce un’istanza con i suoi variable_values. 404 con corpo vuoto se non esiste.

Eseguire i prompt

Come viene scelto il modello

Nessuno di questi endpoint usa la selezione automatica del modello, che è propria degli endpoint delle conversazioni. Ogni endpoint di esecuzione verifica il modello scelto rispetto alle regole di Accesso a modelli e provider del tuo workspace (400 {"error":"The selected AI model has been restricted by your organization"}, con una formulazione leggermente diversa nelle scorciatoie) e a quelle di Residenza dei dati (400 con un code relativo alla residenza).

L’oggetto 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"
}

Utilizzo e crediti non fanno parte di nessuna risposta di esecuzione.

POST /instance/:id/run

Esegue un’istanza e attende che il modello termini. Viene creata una nuova conversazione con il messaggio dell’utente (il contenuto elaborato dell’istanza) e la risposta dell’IA, a meno che tu non passi conversation_context_id. Se quella conversazione ha un confronto tra modelli attivo, l’istanza viene eseguita una volta in ogni thread e vengono restituiti tutti i risultati.

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

Risposta. 200 con un array di oggetti RunHistory, uno per modello.

Errori

POST /instance/:id/run/stream

Accetta gli stessi parametri di percorso e di query, gli stessi header e lo stesso corpo di /run ed esegue la stessa convalida, ma non trasmette in streaming su questa risposta HTTP. Funziona invece così:

1. Il server crea le esecuzioni e la conversazione, avvia la generazione in background e restituisce subito 200 con un array di oggetti RunHistory in run_status: "pending", result: "", runtime: 0, ciascuno con un conversation_context_id valido.
2. I token vengono inviati al WebSocket della conversazione, GET /conversation/{conversation_context_id}/ws. Accetta lo stesso header Authorization: Bearer e richiede l’autorizzazione conversations_get. I client lato server possono inviare quell’header; i browser no.
3. Ogni frame è un messaggio di testo JSON {"type": ..., "data": ...}:

4. Dopo ai_message_end, leggi lo stato finale con GET /conversation/:id.

Gli eventi inviati prima che si connetta un client vengono messi in buffer e riprodotti alla prima connessione, quindi puoi aprire il socket subito dopo la risposta della POST. Il tuo messaggio dell’utente non ti viene rimandato. Dopo che la POST ha restituito 200, gli errori del provider arrivano solo come frame error_message; gli errori che precedono la generazione (limite di modelli, piano gratuito, residenza dei dati) vengono restituiti con gli stati diversi da 200 elencati per /run. L’endpoint SSE legacy GET /conversation/:id/stream non inoltra gli snapshot dei messaggi per queste esecuzioni, quindi usa il WebSocket. Tutti i dettagli sul WebSocket e gli esempi di client si trovano in Conversazioni e messaggi.

POST /run/prompt/last

Ripete la tua esecuzione di prompt più recente con nuovi «dati primari». È pensato per riesecuzioni rapide, per esempio da un’estensione del browser. Prende l’esecuzione più recente di un qualsiasi prompt tuo o condiviso con te, crea una nuova istanza in cui la variabile primaria (o l’unica variabile) riceve data e ogni altra variabile mantiene il valore di quell’esecuzione (o il proprio valore predefinito), e la esegue con lo stesso modello, gli stessi strumenti e l’ai_style del prompt. Viene creata una nuova conversazione interattiva (origine extension).

Risposta. 200 con un singolo oggetto RunHistory, non un array.

Errori. 404 {"error":"No runs found"}, 400 {"error":"Invalid instance request"} quando una variabile obbligatoria resta vuota, 400 per un modello soggetto a restrizioni o per un blocco di residenza dei dati o di dati sensibili, 429 al superamento della quota. Se la chiamata al modello non riesce prima che venga registrata un’esecuzione, la richiesta fallisce con 500.

POST /run/prompt/:id

Funziona come /run/prompt/last, ma per un singolo prompt. Ripete l’esecuzione più recente del prompt con data nella variabile primaria. Se il prompt non è mai stato eseguito ed è tuo, viene creata una prima esecuzione con i valori predefiniti delle variabili e l’ai_model_id del prompt. L’esecuzione ripetuta è l’ultima esecuzione del prompt in assoluto, non solo tra le tue: su un prompt condiviso, quindi, i valori delle variabili non primarie possono provenire dall’ultima esecuzione di un altro utente.

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

Risposta. 200 con un singolo oggetto RunHistory. Errori. 404 {"error":"Prompt not found"}, più gli errori di /run/prompt/last.

POST /run/prompt/:id/variables

Esegue la versione corrente di un prompt con un insieme completo di valori delle variabili: creazione dell’istanza ed esecuzione in un’unica chiamata. Usa l’ai_model_id e l’ai_style del prompt. La nuova istanza diventa l’istanza corrente della versione e viene creata una nuova conversazione interattiva (origine 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);

Risposta. 200 con un singolo oggetto RunHistory.

Errori. 404 {"error":"Prompt not found"}, 400 per un modello soggetto a restrizioni o per un blocco di residenza dei dati o di dati sensibili, 429 al superamento della quota, 503 {"error":"..."} se l’esecuzione non riesce.

Lo strumento MCP run_prompt svolge lo stesso compito con una mappa che associa gli slug delle variabili ai valori; restituisce solo il testo e non crea una conversazione interattiva.

POST /run

Invia testo libero a un modello e restituisce la risposta, senza prompt, senza variabili e senza conversazione. La chiamata è sincrona. Non vengono aggiunti né un prompt di sistema, né il prompt del workspace, né le istruzioni del progetto, lo stile è fisso su prompty e nulla viene salvato come conversazione. 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":"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

Risposta. 200 con un oggetto Message che non viene salvato: il suo ID è 0 e i suoi timestamp sono a zero. text contiene il Markdown originale del modello, a differenza degli endpoint di esecuzione, che restituiscono 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"
}

Errori. 404 {"error":"AI model not found"}, 400 per un modello soggetto a restrizioni o per un blocco di residenza dei dati o di dati sensibili, 429 al superamento della quota, 500 {"error":"..."} quando la chiamata al modello non riesce (questo endpoint usa 500, non 503).

GET /prompt/:id/run_history

Restituisce la cronologia delle tue esecuzioni in Prompt Studio per un prompt, a partire dalla conversazione più recente. Sono incluse solo le conversazioni avviate da te con is_prompt_studio: true.

Risposta. 200 con un array di array di oggetti RunHistory: un array interno per conversazione, con più elementi quando quell’esecuzione ha confrontato più modelli. Qui variables è compilato. [] quando non c’è nulla.

File del prompt

I file allegati al prompt stesso. I modelli con protocollo OpenAI li usano tramite la ricerca nei file; i modelli Together li ricevono come messaggio aggiuntivo dell’utente; per gli altri provider, il loro utilizzo non è documentato. Carica prima i file con POST /file.

POST /prompt/:id/file

Collega file caricati a un prompt. I file collegati in precedenza restano collegati.

Risposta. 200 con l’oggetto Prompt; file_data elenca solo i file aggiunti in questa chiamata.

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

GET /prompt/:id/file

Restituisce un array degli oggetti File collegati al prompt. 400 se id non è numerico.

DELETE /prompt/:id/file/:fileId

Scollega un file da uno dei tuoi prompt. Se nessun altro prompt o messaggio usa quel file, viene eliminato anche il file archiviato.

Risposta. 204. Errori. 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"}.

Condivisione con singoli utenti

GET /share

Restituisce i prompt condivisi con te, dal più recente.

Risposta. 200 con un array di oggetti Prompt, ciascuno con un oggetto shared_by. scope=workspace senza un workspace restituisce []; negli altri ambiti un risultato vuoto è null, non [].

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

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

GET /prompt/:id/share

Elenca gli utenti con cui è condiviso un prompt. Ogni Share contiene un oggetto 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

Condivide il prompt :id in sola lettura con un utente, tramite email. Se non esiste un account per quell’indirizzo, il server crea un account invitato e invia un’email di invito; un utente già invitato riceve di nuovo l’invito.

Risposta. 200 con un corpo vuoto. Errori. 404 {"error":"prompt not found"}, 400 {"error":"invalid email format"}, 400 {"error":"share already exists"}, 400 {"error":"..."} quando l’invito non riesce.

POST /share/:id/resend

Invia di nuovo l’email di invito a un utente che non si è ancora registrato.

Risposta. 204. Errori. 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

Rimuove una condivisione e annulla gli eventuali inviti in sospeso di quell’utente.

Risposta. 204. Errori. 404 {"error":"share not found"}.

Pagine correlate

• Conversazioni e messaggi - prosegui la conversazione di un’esecuzione e ricevi le risposte in streaming.
• Libreria di prompt e Variabili del prompt - le stesse funzionalità nell’app.
• Riferimento degli strumenti - list_prompts, get_prompt, run_prompt, custom_run.