Prompts et exécutions

Un prompt enregistré est un template réutilisable de votre bibliothèque de prompts. Son texte contient des {{variables}} que vous renseignez à chaque exécution. L’API REST vous permet de construire des prompts depuis votre code, de les exécuter avec de nouvelles valeurs sur le modèle de votre choix, puis d’en récupérer les résultats. Chaque requête s’exécute au nom de l’utilisateur propriétaire de la clé API.

Tous les chemins sont relatifs à https://api.stickyprompts.com/api/v1. Les corps de requête sont en JSON.

Concepts clés

Un prompt est un template nommé. Son texte réside dans une version de prompt : il n’existe qu’une version par prompt, et l’envoi d’un nouveau contenu l’écrase. Une version comporte des variables, référencées dans le texte sous la forme {{slug}}, par exemple Write a {{tone}} summary of: {{text}}.

Pour exécuter un prompt, vous renseignez ses variables. Vous créez ainsi une instance : une copie immuable du template dans laquelle les valeurs ont été substituées. Vous exécutez ensuite l’instance sur un ou plusieurs modèles. Chaque exécution crée une conversation (appelée conversation_context dans l’API), que vous pouvez poursuivre avec les endpoints décrits dans Conversations et messages.

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

Les endpoints raccourcis sous /run/prompt/... créent l’instance et l’exécutent en un seul appel. POST /run envoie du texte brut à un modèle, sans aucun prompt.

Conventions

• Pagination. Lorsque c’est indiqué, envoyez page (par défaut 1) et size (par défaut 10). Les headers de réponse X-Page, X-Page-Size et X-Total-Count décrivent le résultat. Voir Erreurs, pagination et quotas.
• Portée projet. Plusieurs endpoints lisent un header facultatif X-Project-ID: <numeric id>. Une valeur non numérique est traitée comme absente.
• Casse des champs. Les objets de base de données utilisent ID, CreatedAt, UpdatedAt et DeletedAt avec une majuscule, à côté de champs en snake_case. Le résultat RunHistory utilise id et created_at en minuscules.
• Texte rendu. Les champs result et thinking d’une exécution contiennent du HTML rendu à partir du Markdown du modèle, et non le Markdown brut.
• Les erreurs ont la forme {"error": "..."}. Les dépassements de quota renvoient 429 {"error":"Quota exceeded","reason":"..."}. Les blocages par les garde-fous ajoutent un code machine, par exemple {"error": "...", "code": "SENSITIVE_DATA_BLOCKED"}. Les échecs liés à la résidence des données utilisent les codes EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED et NO_ENDPOINT_AVAILABLE.

L’objet 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 vaut {ID, ..., prompt_id, content, variables[], current_instance_id, current_instance} lorsqu’il est chargé ; la plupart des endpoints de liste le laissent à null.
• category vaut {ID, CreatedAt, UpdatedAt, DeletedAt, name} lorsqu’il est chargé.
• file_data est un tableau d’objets File lorsqu’il est chargé, sinon null. Un File a la forme {ID, CreatedAt, UpdatedAt, DeletedAt, name, path, preview_path, public_path, user_id, workspace_id, project_id, fileType, partial} ; notez le fileType en camelCase.
• tools vaut [{"name", "use"}] ou null. Noms d’outils : web_search, image_generation, video_generation, speech_generation, music_generation, remote_mcp.
• mcp_servers est un tableau d’ID de serveurs MCP distants.

Prompts

GET /prompt

Liste vos propres prompts qui n’appartiennent à aucun projet, du plus récent au plus ancien. Avec X-Project-ID, liste à la place les prompts de ce projet.

Réponse. 200 avec un tableau d’objets Prompt (current_version, category et file_data non chargés). Avec X-Project-ID, chaque élément comporte aussi "can_delete": bool, qui ne vaut true que si vous pouvez gérer les prompts du projet et que ce prompt vous appartient.

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

GET /prompt/all

Renvoie en une seule liste vos propres prompts, ceux qui sont partagés avec vous et ceux que vous avez mis en favoris, triés selon la date de votre dernière exécution de chacun (ou, à défaut, leur date de création). Les prompts appartenant à un projet sont exclus.

Réponse. 200 avec un tableau d’objets Prompt dont file_data est chargé, ou [].

GET /prompt/last_used

Renvoie jusqu’à 8 prompts que vous avez exécutés, du plus récemment exécuté au plus ancien, avec file_data chargé. Les prompts que vous n’avez jamais exécutés sont omis. Les headers de pagination sont présents, mais page et size sont ignorés.

GET /prompt/most_used

Renvoie jusqu’à 8 prompts, triés selon la fréquence à laquelle vous les avez exécutés. Pas de headers de pagination.

GET /prompt/recently_added

Renvoie jusqu’à 8 de vos propres prompts, du plus récent au plus ancien, avec file_data chargé.

POST /prompt

Crée un prompt. Celui-ci démarre sans version : appelez ensuite POST /prompt_version pour lui donner un contenu. Le modèle provient de vos préférences (ou, à défaut, du premier modèle du catalogue), et ai_style de vos préférences (ou prompty). Pour modifier l’un ou l’autre, appelez ensuite PUT /prompt/:id.

ai_model_id, ai_style et slug sont ignorés à la création ; un slug aléatoire est généré.

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

Réponse. 201 avec l’objet Prompt.

Erreurs. 400 JSON mal formé, 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

Remplace les champs modifiables d’un prompt. Uniquement pour vos propres prompts.

Tous les champs name, description, ai_model_id, example_output, category_id et ai_style sont écrasés : envoyez donc toujours les valeurs actuelles des champs que vous ne souhaitez pas modifier.

Réponse. 200 avec l’objet Prompt. Erreurs. 404 {"error":"Prompt not found"}, 400 {"error":"Name is required"}.

POST /prompt_version

Définit le contenu du template d’un prompt. Le premier appel crée la version et en fait la version courante ; les appels suivants écrasent content sur cette même version. Créez les variables avec POST /variable, et non par ce corps.

Réponse. 201, aussi bien à la création qu’à la mise à jour :

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

variables n’est pas chargé lors d’une mise à jour. Erreurs. 400 JSON mal formé, 404 {"error":"Prompt not found"}.

DELETE /prompt/:id

Supprime de façon logique l’un de vos propres prompts, et le retire de ses partages comme des favoris de tous les utilisateurs.

Réponse. 204. 404 avec un corps vide si le prompt n’existe pas ou ne vous appartient pas.

POST /prompt/:id/duplicate

Copie un prompt qui vous appartient ou auquel vous avez accès (catalogue public, prompts partagés avec vous, prompts partagés avec votre espace de travail). La copie reprend le nom, la description, le modèle, l’exemple de sortie, les outils, le style, la catégorie, le contenu de la version et les variables (name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options). Ne sont pas copiés : mcp_servers, les fichiers joints, ainsi que les champs file_types et default_file_id de chaque variable.

Réponse. 200 avec le nouvel objet Prompt, current_version.variables renseigné.

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

Déplace un prompt dans un projet, d’un projet à un autre, ou hors d’un projet. Sans corps. Vous devez être autorisé à gérer les prompts de chaque projet concerné, et un prompt déplacé dans un projet doit vous appartenir.

Réponse. 200 avec l’objet Prompt, project chargé.

Erreurs. 404 {"error":"Prompt not found"} ou {"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 sans autorisation sur les projets.

PUT /prompt/:id/share_with_workspace

Rend l’un de vos propres prompts visible par tout votre espace de travail, ou de nouveau privé.

Réponse. 200 avec l’objet Prompt ; shared_with_workspace_id contient l’ID de votre espace de travail ou null. Erreurs. 404 {"error":"Prompt not found"}, 400 {"error":"User is not part of a workspace"}.

Favoris

GET /prompt/favorite

Renvoie vos prompts favoris dans l’ordre où vous les avez ajoutés (du plus ancien au plus récent). Chaque élément comporte "is_favorite": true ; la version, la catégorie et les fichiers ne sont pas chargés. Pas de pagination.

POST /prompt/:id/favorite

Ajoute un prompt à vos favoris. Il doit vous appartenir, être partagé directement avec vous ou faire partie du catalogue public. Un prompt partagé uniquement avec votre espace de travail renvoie 403.

Réponse. 201. La clé du prompt imbriqué s’écrit bel et bien Prompt, avec une majuscule :

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

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

Retire un prompt de vos favoris.

Réponse. 204. Erreurs. 404 {"error":"Prompt not found in favorites"}.

Variables

Les variables appartiennent à une version de prompt. Le slug doit correspondre à un emplacement {{slug}} du contenu et être unique au sein de la version. Consultez Variables de prompt pour leur comportement dans l’application.

{
  "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 vaut short_text, long_text, select, number, json ou lov.
• options (pour les variables à choix) vaut [{"label": "...", "value": "..."}].
• is_primary désigne la variable que renseignent les raccourcis /run/prompt/last et /run/prompt/:id.

POST /variable

Ajoute une variable à une version de prompt. Le prompt doit vous appartenir. Le corps est l’objet Variable sans ID ni horodatages ; le serveur ne valide que les trois premiers champs ci-dessous.

Réponse. 201 avec l’objet Variable.

Erreurs. 400 JSON mal formé, 404 {"error":"Prompt version not found"}, 403 {"error":"You are not allowed to add variables to this prompt"}, 409 {"error":"Entity already exists"} (slug en double).

PUT /variable/:id

Remplace les champs d’une variable. La mise à jour écrase tous les champs : envoyez-les donc tous, à savoir name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options, file_types et default_file_id.

L’historique est préservé : si vous modifiez name ou slug sur une variable qui possède déjà des valeurs enregistrées lors d’exécutions précédentes, le serveur archive d’abord l’ancienne variable (une copie supprimée de façon logique dont le slug reçoit le suffixe _deleted_<timestamp>), y transfère ces valeurs, puis met à jour la variable sur place. Dans ce cas, file_types et default_file_id ne sont pas mis à jour.

Réponse. 200 avec l’objet Variable. Erreurs. 404 {"error":"Variable not found"}, 403 {"error":"You are not allowed to update variables of this prompt"}.

DELETE /variable/:id

Supprime une variable.

Réponse. 204. Erreurs. 404 {"error":"Variable not found"}, 403 {"error":"You are not allowed to delete variables of this prompt"}.

Instances

Une instance est le template dont les valeurs ont été renseignées. Chaque {{slug}} est remplacé par la valeur que vous avez envoyée, ou par la default_value de la variable lorsque la valeur est vide ou absente. Les emplacements qui ne correspondent à aucune variable restent tels quels. Si votre espace de travail utilise des garde-fous, ceux-ci s’appliquent aux valeurs et au contenu après substitution avant tout enregistrement : les valeurs peuvent donc revenir masquées.

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

Renseigne les variables d’une version et enregistre le résultat comme nouvelle instance, qui devient aussi l’instance courante de la version.

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

Réponse. 201 avec l’objet instance.

Erreurs. 404 {"error":"Prompt version not found"}, 400 {"error":"Invalid instance request"} lorsqu’une variable obligatoire n’a pas de valeur non vide, 400 {"error":"...","code":"SENSITIVE_DATA_BLOCKED"} lorsqu’un garde-fou bloque l’entrée.

GET /instance/:id

Renvoie une instance avec ses variable_values. 404 avec un corps vide si elle n’existe pas.

Exécuter des prompts

Choix du modèle

Aucun de ces endpoints n’utilise le routage automatique des modèles, réservé aux endpoints de conversation. Chaque endpoint d’exécution vérifie le modèle choisi au regard des règles d’accès aux modèles de votre espace de travail (400 {"error":"The selected AI model has been restricted by your organization"}, formulé légèrement différemment sur les raccourcis) et de ses règles de résidence des données (400 avec un code de résidence).

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

L’utilisation et les crédits ne figurent dans aucune réponse d’exécution.

POST /instance/:id/run

Exécute une instance et attend que le modèle ait terminé. Une nouvelle conversation contenant le message utilisateur (le contenu de l’instance après substitution) et la réponse de l’IA est créée, sauf si vous passez conversation_context_id. Si cette conversation comporte une comparaison de modèles active, l’instance est exécutée une fois dans chaque fil et tous les résultats sont renvoyés.

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

Réponse. 200 avec un tableau d’objets RunHistory, un par modèle.

Erreurs

POST /instance/:id/run/stream

Accepte les mêmes chemin, paramètres de requête, header et corps que /run et applique la même validation, mais ne diffuse rien dans cette réponse HTTP. À la place :

1. Le serveur crée les exécutions et la conversation, lance la génération en arrière-plan et renvoie aussitôt 200 avec un tableau d’objets RunHistory en run_status: "pending", result: "", runtime: 0, chacun avec un conversation_context_id valide.
2. Les tokens sont transmis au WebSocket de la conversation, GET /conversation/{conversation_context_id}/ws. Celui-ci accepte le même header Authorization: Bearer et nécessite l’autorisation conversations_get. Les clients côté serveur peuvent envoyer ce header ; les navigateurs, non.
3. Chaque trame est un message texte JSON {"type": ..., "data": ...} :

4. Après ai_message_end, lisez l’état final avec GET /conversation/:id.

Les événements envoyés avant la connexion d’un client sont mis en mémoire tampon et rejoués à la première connexion : vous pouvez donc ouvrir le socket juste après le retour du POST. Votre propre message utilisateur ne vous est pas renvoyé en écho. Une fois que le POST a renvoyé 200, les erreurs du fournisseur n’arrivent plus que sous forme de trames error_message ; les erreurs antérieures à la génération (limite du nombre de modèles, offre gratuite, résidence) reviennent avec les statuts autres que 200 listés pour /run. L’ancien endpoint SSE GET /conversation/:id/stream ne relaie pas les instantanés de message pour ces exécutions : utilisez donc le WebSocket. Tous les détails sur le WebSocket, ainsi que des exemples de clients, figurent dans Conversations et messages.

POST /run/prompt/last

Rejoue votre exécution de prompt la plus récente avec de nouvelles « données principales ». Conçu pour relancer rapidement un prompt, par exemple depuis une extension de navigateur. L’endpoint retient l’exécution la plus récente parmi tous les prompts qui vous appartiennent ou qui sont partagés avec vous, construit une nouvelle instance dans laquelle la variable principale (ou la seule variable) reçoit data tandis que chaque autre variable conserve sa valeur de cette exécution (ou sa valeur par défaut), puis l’exécute avec le même modèle, les mêmes outils et le ai_style du prompt. Une nouvelle conversation interactive est créée (source extension).

Réponse. 200 avec un objet RunHistory unique, et non un tableau.

Erreurs. 404 {"error":"No runs found"}, 400 {"error":"Invalid instance request"} lorsqu’une variable obligatoire se retrouve vide, 400 pour un modèle soumis à restriction ou un blocage lié à la résidence ou aux données sensibles, 429 en cas de dépassement de quota. Si l’appel au modèle échoue avant l’enregistrement d’une exécution, la requête échoue avec 500.

POST /run/prompt/:id

Identique à /run/prompt/last, mais pour un prompt précis. Rejoue la dernière exécution du prompt en plaçant data dans la variable principale. Si le prompt n’a jamais été exécuté et qu’il vous appartient, une première exécution est construite à partir des valeurs par défaut des variables et du ai_model_id du prompt. L’exécution rejouée est la dernière exécution du prompt tous utilisateurs confondus, et pas seulement la vôtre : sur un prompt partagé, les valeurs non principales peuvent donc provenir de la dernière exécution d’un autre utilisateur.

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

Réponse. 200 avec un objet RunHistory unique. Erreurs. 404 {"error":"Prompt not found"}, ainsi que les erreurs de /run/prompt/last.

POST /run/prompt/:id/variables

Exécute la version courante d’un prompt avec un jeu complet de valeurs de variables : création de l’instance et exécution en un seul appel. Utilise le ai_model_id et le ai_style du prompt. La nouvelle instance devient l’instance courante de la version, et une nouvelle conversation interactive est créée (source 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);

Réponse. 200 avec un objet RunHistory unique.

Erreurs. 404 {"error":"Prompt not found"}, 400 pour un modèle soumis à restriction ou un blocage lié à la résidence ou aux données sensibles, 429 en cas de dépassement de quota, 503 {"error":"..."} en cas d’échec de l’exécution.

L’outil MCP run_prompt remplit la même fonction à partir d’une table associant les slugs des variables à leurs valeurs ; il ne renvoie que le texte et ne crée pas de conversation interactive.

POST /run

Envoie du texte libre à un modèle et renvoie la réponse, sans prompt, sans variables et sans conversation. L’appel est synchrone. Aucun prompt système, prompt d’espace de travail ni instruction de projet n’est ajouté, le style est fixé à prompty et rien n’est enregistré comme conversation. L’utilisation est tout de même comptabilisée.

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

Réponse. 200 avec un objet Message non enregistré : son ID vaut 0 et ses horodatages sont à zéro. text contient le Markdown brut du modèle, contrairement aux endpoints d’exécution, qui renvoient du 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"
}

Erreurs. 404 {"error":"AI model not found"}, 400 pour un modèle soumis à restriction ou un blocage lié à la résidence ou aux données sensibles, 429 en cas de dépassement de quota, 500 {"error":"..."} en cas d’échec de l’appel au modèle (cet endpoint utilise 500, et non 503).

GET /prompt/:id/run_history

Renvoie votre historique d’exécutions Prompt Studio pour un prompt, de la conversation la plus récente à la plus ancienne. Seules les conversations que vous avez démarrées avec is_prompt_studio: true sont incluses.

Réponse. 200 avec un tableau de tableaux d’objets RunHistory : un tableau interne par conversation, avec plusieurs éléments lorsque cette exécution comparait des modèles. variables est renseigné ici. [] s’il n’y a rien.

Fichiers de prompt

Il s’agit des fichiers joints au prompt lui-même. Les modèles utilisant le protocole OpenAI s’en servent via la recherche de fichiers ; les modèles Together les reçoivent sous forme de message utilisateur supplémentaire ; pour les autres fournisseurs, leur utilisation n’est pas documentée. Envoyez d’abord les fichiers avec POST /file.

POST /prompt/:id/file

Associe des fichiers envoyés à un prompt. Les fichiers associés auparavant le restent.

Réponse. 200 avec l’objet Prompt ; file_data ne liste que les fichiers ajoutés par cet appel.

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

GET /prompt/:id/file

Renvoie un tableau des objets File associés au prompt. 400 si id n’est pas numérique.

DELETE /prompt/:id/file/:fileId

Dissocie un fichier de l’un de vos propres prompts. Si aucun autre prompt ni message n’utilise ce fichier, le fichier stocké est également supprimé.

Réponse. 204. Erreurs. 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"}.

Partage avec des utilisateurs

GET /share

Renvoie les prompts partagés avec vous, du plus récent au plus ancien.

Réponse. 200 avec un tableau d’objets Prompt, chacun accompagné d’un objet shared_by. scope=workspace sans espace de travail renvoie [] ; dans les autres portées, un résultat vide vaut null, et non [].

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

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

GET /prompt/:id/share

Liste les utilisateurs avec lesquels un prompt est partagé. Chaque Share comporte un objet user complet.

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

Partage le prompt :id en lecture seule avec un utilisateur, par e-mail. Si aucun compte n’existe pour cette adresse, le serveur crée un compte invité et envoie un e-mail d’invitation ; un utilisateur déjà invité reçoit de nouveau l’invitation.

Réponse. 200 avec un corps vide. Erreurs. 404 {"error":"prompt not found"}, 400 {"error":"invalid email format"}, 400 {"error":"share already exists"}, 400 {"error":"..."} lorsque l’invitation échoue.

POST /share/:id/resend

Renvoie l’e-mail d’invitation à un utilisateur qui ne s’est pas encore inscrit.

Réponse. 204. Erreurs. 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

Supprime un partage et annule les invitations en attente de cet utilisateur.

Réponse. 204. Erreurs. 404 {"error":"share not found"}.

Voir aussi

• Conversations et messages - poursuivre la conversation d’une exécution et recevoir les réponses en streaming.
• Bibliothèque de prompts et Variables de prompt - les mêmes fonctionnalités dans l’application.
• Référence des outils du serveur MCP - list_prompts, get_prompt, run_prompt, custom_run.