Prompts und Ausführungen

Ein gespeicherter Prompt ist eine wiederverwendbare Vorlage aus Ihrer Prompt-Bibliothek. Sein Text enthält {{variables}}, die Sie bei jeder Ausführung neu befüllen. Mit der REST-API erstellen Sie Prompts per Code, führen sie mit frischen Werten auf dem Modell Ihrer Wahl aus und lesen die Ergebnisse zurück. Jeder Request läuft im Namen des Benutzers, dem der API-Schlüssel gehört.

Alle Pfade sind relativ zu https://api.stickyprompts.com/api/v1. Request-Bodys sind JSON.

Grundbegriffe

Ein Prompt ist eine benannte Vorlage. Sein Text steckt in einer Prompt-Version: Pro Prompt gibt es genau eine Version, und neuer Inhalt überschreibt sie. Eine Version hat Variablen, die im Text als {{slug}} referenziert werden, zum Beispiel Write a {{tone}} summary of: {{text}}.

Um einen Prompt auszuführen, füllen Sie seine Variablen aus. Dabei entsteht eine Instanz: eine unveränderliche Kopie der Vorlage, in die die Werte eingesetzt sind. Mit dieser Instanz starten Sie dann eine Ausführung auf einem oder mehreren Modellen. Jede Ausführung legt eine Unterhaltung an (in der API conversation_context genannt), in der Sie über die Endpunkte unter Unterhaltungen und Nachrichten weiterchatten können.

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

Die Abkürzungs-Endpunkte unter /run/prompt/... legen die Instanz an und führen sie in einem einzigen Aufruf aus. POST /run schickt reinen Text an ein Modell, ganz ohne Prompt.

Konventionen

• Paginierung. Wo angegeben, senden Sie page (Standard 1) und size (Standard 10). Die Response-Header X-Page, X-Page-Size und X-Total-Count beschreiben das Ergebnis. Siehe Fehler, Paginierung und Kontingente.
• Projektbezug. Mehrere Endpunkte lesen einen optionalen Header X-Project-ID: <numeric id>. Ein nicht numerischer Wert gilt als nicht gesetzt.
• Schreibweise der Felder. Datenbankobjekte verwenden großgeschriebene ID, CreatedAt, UpdatedAt und DeletedAt neben Feldern in snake_case. Das RunHistory-Ergebnis verwendet kleingeschriebene id und created_at.
• Gerenderter Text. Die Felder result und thinking einer Ausführung enthalten HTML, das aus dem Markdown des Modells gerendert wurde, nicht das rohe Markdown.
• Fehler haben die Form {"error": "..."}. Kontingentfehler lauten 429 {"error":"Quota exceeded","reason":"..."}. Sperren durch Guardrails enthalten zusätzlich einen maschinenlesbaren Code, zum Beispiel {"error": "...", "code": "SENSITIVE_DATA_BLOCKED"}. Fehler wegen der Datenresidenz verwenden die Codes EU_INFERENCE_REQUIRED, ZERO_RETENTION_REQUIRED, NO_PROVIDER_ASSIGNED und NO_ENDPOINT_AVAILABLE.

Das Prompt-Objekt

{
  "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 hat im geladenen Zustand die Form {ID, ..., prompt_id, content, variables[], current_instance_id, current_instance}; die meisten Listen-Endpunkte lassen es auf null.
• category hat im geladenen Zustand die Form {ID, CreatedAt, UpdatedAt, DeletedAt, name}.
• file_data ist im geladenen Zustand ein Array aus File-Objekten, sonst null. Ein File hat die Form {ID, CreatedAt, UpdatedAt, DeletedAt, name, path, preview_path, public_path, user_id, workspace_id, project_id, fileType, partial}; beachten Sie das camelCase-Feld fileType.
• tools ist [{"name", "use"}] oder null. Tool-Namen: web_search, image_generation, video_generation, speech_generation, music_generation, remote_mcp.
• mcp_servers ist ein Array aus IDs von Remote-MCP-Servern.

Prompts

GET /prompt

Listet Ihre eigenen Prompts auf, die keinem Projekt angehören, die neuesten zuerst. Mit X-Project-ID werden stattdessen die Prompts dieses Projekts aufgelistet.

Antwort. 200 mit einem Array aus Prompt-Objekten (current_version, category und file_data nicht geladen). Mit X-Project-ID hat jedes Element zusätzlich "can_delete": bool. Der Wert ist nur dann true, wenn Sie die Prompts des Projekts verwalten dürfen und Ihnen der Prompt gehört.

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

GET /prompt/all

Gibt Ihre eigenen Prompts, mit Ihnen geteilte Prompts und Ihre favorisierten Prompts in einer einzigen Liste zurück, sortiert danach, wann Sie den jeweiligen Prompt zuletzt ausgeführt haben (ersatzweise nach dem Erstellungszeitpunkt). Prompts in Projekten sind ausgeschlossen.

Antwort. 200 mit einem Array aus Prompt-Objekten mit geladenem file_data, oder [].

GET /prompt/last_used

Gibt bis zu 8 Prompts zurück, die Sie ausgeführt haben, die zuletzt ausgeführten zuerst, mit geladenem file_data. Prompts, die Sie nie ausgeführt haben, fehlen. Paginierungs-Header werden gesetzt, page und size aber ignoriert.

GET /prompt/most_used

Gibt bis zu 8 Prompts zurück, sortiert danach, wie oft Sie sie ausgeführt haben. Keine Paginierungs-Header.

GET /prompt/recently_added

Gibt bis zu 8 Ihrer eigenen Prompts zurück, die neuesten zuerst, mit geladenem file_data.

POST /prompt

Legt einen Prompt an. Er beginnt ohne Version: Rufen Sie als Nächstes POST /prompt_version auf, um ihm Inhalt zu geben. Das Modell stammt aus Ihren Voreinstellungen (sonst das erste Modell im Katalog), ai_style ebenfalls aus Ihren Voreinstellungen (sonst prompty). Um eines davon zu ändern, rufen Sie anschließend PUT /prompt/:id auf.

ai_model_id, ai_style und slug werden beim Anlegen ignoriert; der Server erzeugt einen zufälligen Slug.

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

Antwort. 201 mit dem Prompt-Objekt.

Fehler. 400 bei fehlerhaftem JSON, 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

Ersetzt die bearbeitbaren Felder eines Prompts. Nur bei Ihren eigenen Prompts möglich.

Alle Felder name, description, ai_model_id, example_output, category_id und ai_style werden überschrieben. Senden Sie daher immer die aktuellen Werte der Felder mit, die Sie nicht ändern möchten.

Antwort. 200 mit dem Prompt-Objekt. Fehler. 404 {"error":"Prompt not found"}, 400 {"error":"Name is required"}.

POST /prompt_version

Legt den Vorlageninhalt eines Prompts fest. Der erste Aufruf erstellt die Version und macht sie zur aktuellen; spätere Aufrufe überschreiben content in derselben Version. Variablen legen Sie mit POST /variable an, nicht über diesen Body.

Antwort. 201 beim Anlegen wie beim Aktualisieren:

{
  "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 wird beim Aktualisieren nicht geladen. Fehler. 400 bei fehlerhaftem JSON, 404 {"error":"Prompt not found"}.

DELETE /prompt/:id

Löscht einen Ihrer eigenen Prompts per Soft Delete und entfernt seine Freigaben sowie die Favoriten-Markierungen aller Benutzer.

Antwort. 204. 404 mit leerem Body, wenn der Prompt nicht existiert oder Ihnen nicht gehört.

POST /prompt/:id/duplicate

Kopiert einen Prompt, der Ihnen gehört oder auf den Sie Zugriff haben (der öffentliche Katalog, mit Ihnen geteilte Prompts, mit Ihrem Workspace geteilte Prompts). Die Kopie umfasst Name, Beschreibung, Modell, Beispielausgabe, Tools, Stil, Kategorie, Versionsinhalt und Variablen (name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options). Nicht kopiert werden mcp_servers, angehängte Dateien sowie file_types und default_file_id der einzelnen Variablen.

Antwort. 200 mit dem neuen Prompt-Objekt, current_version.variables ist befüllt.

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

Verschiebt einen Prompt in ein Projekt, zwischen Projekten oder aus einem Projekt heraus. Kein Body. Sie benötigen für jedes beteiligte Projekt die Berechtigung, Prompts zu verwalten, und ein Prompt, den Sie in ein Projekt verschieben, muss Ihnen gehören.

Antwort. 200 mit dem Prompt-Objekt, project geladen.

Fehler. 404 {"error":"Prompt not found"} oder {"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 ohne Projektberechtigungen.

PUT /prompt/:id/share_with_workspace

Macht einen Ihrer eigenen Prompts für Ihren gesamten Workspace sichtbar oder wieder privat.

Antwort. 200 mit dem Prompt-Objekt; shared_with_workspace_id ist Ihre Workspace-ID oder null. Fehler. 404 {"error":"Prompt not found"}, 400 {"error":"User is not part of a workspace"}.

Favoriten

GET /prompt/favorite

Gibt Ihre favorisierten Prompts in der Reihenfolge zurück, in der Sie sie favorisiert haben (älteste zuerst). Jedes Element hat "is_favorite": true; Version, Kategorie und Dateien werden nicht geladen. Keine Paginierung.

POST /prompt/:id/favorite

Markiert einen Prompt als Favoriten. Er muss Ihnen gehören, direkt mit Ihnen geteilt sein oder ein öffentlicher Katalog-Prompt sein. Ein Prompt, der nur mit Ihrem Workspace geteilt ist, ergibt 403.

Antwort. 201. Der Schlüssel des verschachtelten Prompts heißt tatsächlich großgeschrieben 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 }

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

Entfernt einen Favoriten.

Antwort. 204. Fehler. 404 {"error":"Prompt not found in favorites"}.

Variablen

Variablen gehören zu einer Prompt-Version. Der slug muss einem Platzhalter {{slug}} im Inhalt entsprechen und innerhalb der Version eindeutig sein. Wie sich Variablen in der App verhalten, lesen Sie unter Prompt-Variablen.

{
  "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 ist short_text, long_text, select, number, json oder lov.
• options (für Auswahlvariablen) hat die Form [{"label": "...", "value": "..."}].
• is_primary markiert die Variable, die die Abkürzungen /run/prompt/last und /run/prompt/:id befüllen.

POST /variable

Fügt einer Prompt-Version eine Variable hinzu. Der Prompt muss Ihnen gehören. Der Body ist das Variable-Objekt ohne ID und Zeitstempel; der Server validiert nur die folgenden drei Pflichtfelder.

Antwort. 201 mit dem Variable-Objekt.

Fehler. 400 bei fehlerhaftem JSON, 404 {"error":"Prompt version not found"}, 403 {"error":"You are not allowed to add variables to this prompt"}, 409 {"error":"Entity already exists"} (doppelter Slug).

PUT /variable/:id

Ersetzt die Felder einer Variablen. Die Aktualisierung überschreibt jedes Feld, senden Sie also alle mit: name, slug, description, data_type, default_value, required, sort, is_primary, is_multi_select, options, file_types und default_file_id.

Der Verlauf bleibt erhalten: Ändern Sie name oder slug einer Variablen, für die bereits Werte aus früheren Ausführungen gespeichert sind, archiviert der Server zuerst die alte Variable (eine per Soft Delete gelöschte Kopie, deren Slug das Suffix _deleted_<timestamp> erhält), verschiebt diese Werte dorthin und aktualisiert dann die Variable an Ort und Stelle. In diesem Fall werden file_types und default_file_id nicht aktualisiert.

Antwort. 200 mit dem Variable-Objekt. Fehler. 404 {"error":"Variable not found"}, 403 {"error":"You are not allowed to update variables of this prompt"}.

DELETE /variable/:id

Löscht eine Variable.

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

Instanzen

Eine Instanz ist die Vorlage mit eingesetzten Werten. Jedes {{slug}} wird durch den gesendeten Wert ersetzt oder, wenn der Wert leer ist oder fehlt, durch den default_value der Variablen. Platzhalter, zu denen keine Variable passt, bleiben unverändert. Hat Ihr Workspace Guardrails, werden sie auf die Werte und den geparsten Inhalt angewendet, bevor etwas gespeichert wird. Werte können daher geschwärzt zurückkommen.

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

Füllt die Variablen einer Version aus und speichert das Ergebnis als neue Instanz, die zugleich zur aktuellen Instanz der Version wird.

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

Antwort. 201 mit dem Instanzobjekt.

Fehler. 404 {"error":"Prompt version not found"}, 400 {"error":"Invalid instance request"}, wenn eine Pflichtvariable leer bleibt, 400 {"error":"...","code":"SENSITIVE_DATA_BLOCKED"}, wenn eine Guardrail die Eingabe blockiert.

GET /instance/:id

Gibt eine Instanz mit ihren variable_values zurück. 404 mit leerem Body, wenn sie nicht existiert.

Prompts ausführen

So wird das Modell gewählt

Keiner dieser Endpunkte nutzt die automatische Modellwahl; sie gehört zu den Endpunkten für Unterhaltungen. Jeder Ausführungs-Endpunkt prüft das gewählte Modell gegen die Regeln Ihres Workspace für Modellzugriff (400 {"error":"The selected AI model has been restricted by your organization"}, bei den Abkürzungen leicht anders formuliert) und für Datenresidenz (400 mit einem code zur Datenresidenz).

Das RunHistory-Objekt

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

Nutzung und Credits sind in keiner Antwort einer Ausführung enthalten.

POST /instance/:id/run

Führt eine Instanz aus und wartet, bis das Modell fertig ist. Dabei entsteht eine neue Unterhaltung mit der Benutzernachricht (dem geparsten Instanzinhalt) und der KI-Antwort, es sei denn, Sie übergeben conversation_context_id. Läuft in dieser Unterhaltung ein aktiver Modellvergleich, wird die Instanz in jedem Thread einmal ausgeführt, und Sie erhalten alle Ergebnisse zurück.

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

Antwort. 200 mit einem Array aus RunHistory-Objekten, eines pro Modell.

Fehler

POST /instance/:id/run/stream

Akzeptiert denselben Pfad, dieselben Query-Parameter, Header und denselben Body wie /run und führt dieselbe Validierung aus, streamt aber nicht über diese HTTP-Antwort. Stattdessen läuft es so ab:

1. Der Server legt die Ausführungen und die Unterhaltung an, startet die Generierung im Hintergrund und gibt sofort 200 zurück, mit einem Array aus RunHistory-Objekten im Zustand run_status: "pending", result: "", runtime: 0, jedes mit einer gültigen conversation_context_id.
2. Die Tokens gehen an den WebSocket der Unterhaltung, GET /conversation/{conversation_context_id}/ws. Er erwartet denselben Header Authorization: Bearer und benötigt die Berechtigung conversations_get. Serverseitige Clients können diesen Header senden, Browser nicht.
3. Jeder Frame ist eine JSON-Textnachricht {"type": ..., "data": ...}:

4. Lesen Sie nach ai_message_end den Endzustand mit GET /conversation/:id.

Events, die gesendet werden, bevor sich ein Client verbindet, werden gepuffert und der ersten Verbindung nachgeliefert. Sie können den Socket also direkt nach der Rückkehr des POST öffnen. Ihre eigene Benutzernachricht wird nicht zurückgespielt. Sobald der POST mit 200 zurückgekehrt ist, kommen Anbieterfehler nur noch als error_message-Frames; Fehler vor der Generierung (Modelllimit, Free-Tarif, Datenresidenz) kommen mit den Statuscodes ungleich 200, die für /run aufgeführt sind. Der veraltete SSE-Endpunkt GET /conversation/:id/stream leitet für diese Ausführungen keine Nachrichten-Snapshots weiter, verwenden Sie also den WebSocket. Alle Details zum WebSocket und Client-Beispiele finden Sie unter Unterhaltungen und Nachrichten.

POST /run/prompt/last

Wiederholt Ihre letzte Prompt-Ausführung mit neuen „Primärdaten“. Gedacht für schnelle Wiederholungen, zum Beispiel aus einer Browsererweiterung. Der Endpunkt nimmt die neueste Ausführung eines beliebigen Prompts, der Ihnen gehört oder mit Ihnen geteilt ist. Daraus baut er eine neue Instanz: Die primäre Variable (oder die einzige Variable) erhält data, jede andere Variable behält ihren Wert aus dieser Ausführung (oder ihren Standardwert). Ausgeführt wird sie mit demselben Modell, denselben Tools und dem ai_style des Prompts. Dabei entsteht eine neue interaktive Unterhaltung (Quelle extension).

Antwort. 200 mit einem einzelnen RunHistory-Objekt, nicht mit einem Array.

Fehler. 404 {"error":"No runs found"}, 400 {"error":"Invalid instance request"}, wenn eine Pflichtvariable am Ende leer ist, 400 bei einem eingeschränkten Modell oder einer Sperre wegen Datenresidenz oder sensibler Daten, 429 bei überschrittenem Kontingent. Schlägt der Modellaufruf fehl, bevor eine Ausführung gespeichert ist, scheitert der Request mit 500.

POST /run/prompt/:id

Wie /run/prompt/last, aber für einen bestimmten Prompt. Der Endpunkt wiederholt die letzte Ausführung des Prompts mit data in der primären Variablen. Wurde der Prompt noch nie ausgeführt und ist er Ihr eigener, wird eine erste Ausführung aus den Standardwerten der Variablen und dem ai_model_id des Prompts gebildet. Wiederholt wird die insgesamt letzte Ausführung des Prompts, nicht nur Ihre eigene. Bei einem geteilten Prompt können die nicht primären Werte daher aus der letzten Ausführung eines anderen Benutzers stammen.

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

Antwort. 200 mit einem einzelnen RunHistory-Objekt. Fehler. 404 {"error":"Prompt not found"} sowie die Fehler von /run/prompt/last.

POST /run/prompt/:id/variables

Führt die aktuelle Version eines Prompts mit einem vollständigen Satz an Variablenwerten aus: Instanzerstellung und Ausführung in einem Aufruf. Verwendet ai_model_id und ai_style des Prompts. Die neue Instanz wird zur aktuellen Instanz der Version, und es entsteht eine neue interaktive Unterhaltung (Quelle 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);

Antwort. 200 mit einem einzelnen RunHistory-Objekt.

Fehler. 404 {"error":"Prompt not found"}, 400 bei einem eingeschränkten Modell oder einer Sperre wegen Datenresidenz oder sensibler Daten, 429 bei überschrittenem Kontingent, 503 {"error":"..."}, wenn die Ausführung fehlschlägt.

Das MCP-Tool run_prompt erledigt dieselbe Aufgabe mit einer Zuordnung von Variablen-Slugs zu Werten; es gibt nur den Text zurück und legt keine interaktive Unterhaltung an.

POST /run

Schickt freien Text an ein Modell und gibt die Antwort zurück, ohne Prompt, ohne Variablen und ohne Unterhaltung. Der Aufruf ist synchron. Es werden weder Systemprompt noch Workspace-Prompt oder Projektanweisungen ergänzt, der Stil ist fest auf prompty eingestellt, und nichts wird als Unterhaltung gespeichert. Die Nutzung wird trotzdem erfasst.

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

Antwort. 200 mit einem Message-Objekt, das nicht gespeichert wird: Seine ID ist 0, seine Zeitstempel sind Nullwerte. text enthält das rohe Markdown des Modells, anders als bei den Ausführungs-Endpunkten, die HTML zurückgeben.

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

Fehler. 404 {"error":"AI model not found"}, 400 bei einem eingeschränkten Modell oder einer Sperre wegen Datenresidenz oder sensibler Daten, 429 bei überschrittenem Kontingent, 500 {"error":"..."}, wenn der Modellaufruf fehlschlägt (dieser Endpunkt verwendet 500, nicht 503).

GET /prompt/:id/run_history

Gibt Ihren Ausführungsverlauf aus dem Prompt Studio für einen Prompt zurück, die neueste Unterhaltung zuerst. Enthalten sind nur Unterhaltungen, die Sie mit is_prompt_studio: true gestartet haben.

Antwort. 200 mit einem Array aus Arrays von RunHistory-Objekten: ein inneres Array pro Unterhaltung, mit mehreren Elementen, wenn bei dieser Ausführung Modelle verglichen wurden. variables ist hier befüllt. [], wenn nichts vorhanden ist.

Prompt-Dateien

Dateien, die an den Prompt selbst angehängt sind. Modelle mit OpenAI-Protokoll nutzen sie über die Dateisuche, Together-Modelle erhalten sie als zusätzliche Benutzernachricht; wie andere Anbieter sie verwenden, ist nicht dokumentiert. Laden Sie Dateien zuerst mit POST /file hoch.

POST /prompt/:id/file

Verknüpft hochgeladene Dateien mit einem Prompt. Bereits verknüpfte Dateien bleiben verknüpft.

Antwort. 200 mit dem Prompt-Objekt; file_data listet nur die in diesem Aufruf hinzugefügten Dateien.

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

GET /prompt/:id/file

Gibt ein Array aus File-Objekten zurück, die mit dem Prompt verknüpft sind. 400, wenn id nicht numerisch ist.

DELETE /prompt/:id/file/:fileId

Löst eine Datei von einem Ihrer eigenen Prompts. Verwendet kein anderer Prompt und keine Nachricht die Datei, wird auch die gespeicherte Datei gelöscht.

Antwort. 204. Fehler. 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"}.

Mit einzelnen Benutzern teilen

GET /share

Gibt Prompts zurück, die mit Ihnen geteilt sind, die neuesten zuerst.

Antwort. 200 mit einem Array aus Prompt-Objekten, jedes mit einem shared_by-Objekt. scope=workspace ohne Workspace ergibt []; ein leeres Ergebnis in den anderen Bereichen ist null, nicht [].

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

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

GET /prompt/:id/share

Listet die Benutzer auf, mit denen ein Prompt geteilt ist. Jede Freigabe (Share) enthält ein vollständiges user-Objekt.

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

Teilt den Prompt :id schreibgeschützt mit einem Benutzer, anhand seiner E-Mail-Adresse. Gibt es für diese Adresse noch kein Konto, legt der Server ein eingeladenes Konto an und verschickt eine Einladungs-E-Mail; ein bereits eingeladener Benutzer erhält die Einladung erneut.

Antwort. 200 mit leerem Body. Fehler. 404 {"error":"prompt not found"}, 400 {"error":"invalid email format"}, 400 {"error":"share already exists"}, 400 {"error":"..."}, wenn die Einladung fehlschlägt.

POST /share/:id/resend

Sendet die Einladungs-E-Mail erneut an einen Benutzer, der sich noch nicht registriert hat.

Antwort. 204. Fehler. 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

Entfernt eine Freigabe und storniert alle ausstehenden Einladungen dieses Benutzers.

Antwort. 204. Fehler. 404 {"error":"share not found"}.

Verwandte Seiten

• Unterhaltungen und Nachrichten - die Unterhaltung einer Ausführung fortsetzen und Antworten streamen.
• Prompt-Bibliothek und Prompt-Variablen - dieselben Funktionen in der App.
• Tool-Referenz - list_prompts, get_prompt, run_prompt, custom_run.