Integrationen

Mit Integrationen kann StickyPrompts in Ihren eigenen Systemen handeln. Über die API legen Sie Verbindungen an und nutzen sie dann direkt: SQL gegen eine Datenbank ausführen, eine E-Mail senden, ein CRM durchsuchen oder aktualisieren und Dateien von und nach Google Drive übertragen. Dahinter steckt dieselbe Mechanik, die auch die App verwendet, wenn jemand im Chat darum bittet.

Alle Pfade sind relativ zu https://api.stickyprompts.com/api/v1. Der Schlüssel handelt im Namen seines Inhabers: Es gelten dieselben Freigabe- und Admin-Regeln wie in der App.

Grundbegriffe

Anbieter

:provider in Pfaden und provider in Antworten verwenden genau diese Zeichenfolgen:

Die Limits gelten pro Inhaber: pro Benutzer bei persönlichen Verbindungen, pro Workspace bei geteilten.

Geltungsbereich

Jede Verbindung ist entweder personal (nur ihr Inhaber sieht und nutzt sie) oder workspace (alle im Workspace können sie nutzen). Nur Inhaber und Admins des Workspace können eine Workspace-Verbindung anlegen, ändern, löschen oder ihre gespeicherten Details lesen. Nutzen kann sie dagegen jedes Mitglied: abfragen, darüber senden, CRM-Datensätze lesen und, mit Schreibzugriff, auch schreiben. Eine Verbindung, die Sie nicht sehen können, antwortet mit 404, nie mit 403.

Zugangsdaten oder OAuth

• Datenbank-, E-Mail- und CRM-Verbindungen werden in einem einzigen Aufruf mit den Zugangsdaten im Body angelegt. Der Server prüft sie zuerst beim Anbieter: Er öffnet die Datenbankverbindung, authentifiziert sich beim SMTP-Server oder sendet eine Testnachricht über Postmark, Resend oder SendGrid. Ein reiner API-Client kann das vollständig selbst erledigen.
• Google Drive verwendet OAuth. Der Connect-Aufruf gibt eine auth_url zurück; eine Person muss sie öffnen und den Zustimmungsbildschirm von Google bestätigen. Ihr Code kann den Link an einen Benutzer weitergeben und GET /integration/connections?provider=google_drive abfragen, bis die Verbindung erscheint.

Kein Endpunkt gibt jemals Geheimnisse wie Passwörter oder Tokens zurück.

Status

Der status einer Verbindung ist active, needs_reauth, revoked oder error. Jede Verbindungsroute, die Sie für eine nicht aktive Verbindung aufrufen, antwortet mit 409 {"error":"reconnect_required"}. Derzeit verlassen nur Google-Drive-Verbindungen den Status active; verbinden Sie sie über Reconnect neu.

Fehler

Katalog und Verbindungen

GET /integration

Der Anbieterkatalog: was jeder Anbieter kann und wie viele Verbindungen Sie bereits haben.

[
  {
    "provider": "postgres",
    "display_name": "PostgreSQL",
    "capabilities": ["test_connection", "schema_browse", "query"],
    "availability": "available",
    "connection_count": 1,
    "max_connections": 0
  }
]

max_connections: 0 bedeutet unbegrenzt. Das gemeinsame Limit von einer E-Mail-Verbindung ist hier nicht berücksichtigt.

GET /integration/ssh-tunnel/public-key

Datenbankverbindungen können eine private Datenbank über einen SSH-Jump-Host erreichen. Fügen Sie diesen öffentlichen Schlüssel zu authorized_keys des SSH-Benutzers auf Ihrem Jump-Host hinzu, und lassen Sie die Adresse von StickyPrompts durch Ihre Firewall zu.

{ "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... stickyprompts" }

POST /integration/:provider/connect

Legt eine neue Verbindung an (eine bestehende wird nie ersetzt). Der Body ist ein einziges flaches Objekt: die gemeinsamen Felder plus die anbieterspezifischen.

curl -X POST https://api.stickyprompts.com/api/v1/integration/postgres/connect \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind Retail DB",
    "scope": "workspace",
    "database_permission": "read_only",
    "host": "localhost",
    "port": 5432,
    "database": "retail",
    "schema": "public",
    "username": "sp_reader",
    "password": "********",
    "ssl_mode": "disable",
    "ssh_host": "bastion.northwind.example",
    "ssh_port": 22,
    "ssh_username": "stickyprompts"
  }'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/integration/postmark/connect",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={
        "name": "Northwind Mailer",
        "scope": "workspace",
        "default_from_email": "team@northwind.example",
        "default_from_name": "Northwind Team",
        "server_token": os.environ["POSTMARK_SERVER_TOKEN"],
    },
)
print(r.status_code, r.json())   # 200 {"connection_id": 42}

const res = await fetch("https://api.stickyprompts.com/api/v1/integration/pipedrive/connect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Pipedrive - Sales",
    scope: "workspace",
    api_token: process.env.PIPEDRIVE_TOKEN,
    allow_write: true,
  }),
});
console.log(res.status, await res.json()); // 200 {"connection_id": 43}

Antwort 200 {"connection_id": 42}. Bei google_drive lautet die Antwort stattdessen 200 {"auth_url": "..."}; schicken Sie eine Person zu dieser URL, um den Vorgang abzuschließen.

GET /integration/connections

Alle Verbindungen, die Sie sehen können (Ihre eigenen plus die geteilten Ihres Workspace), die neuesten zuerst. Optional mit ?provider=<provider>.

[
  {
    "id": 42,
    "provider": "postgres",
    "name": "Northwind Retail DB",
    "description": "Demo retail data: stores, orders, products, customers.",
    "scope": "workspace",
    "status": "active",
    "account_name": "sp_reader@localhost:5432/retail",
    "connected_at": "2026-09-28T12:55:00Z",
    "database_permission": "read_only"
  }
]

account_name ist eine nicht geheime Bezeichnung: user@host:port/database bei Datenbanken, der Standardabsender bei E-Mail, die Konto-URL bei ActiveCampaign. Der CRM-Schreibzugriff steht nicht in dieser Liste; lesen Sie ihn aus GET .../crm/connection.

PATCH /integration/connections/:connectionId

Benennt eine Verbindung um, ändert die Berechtigungsstufe der Datenbank oder tauscht Zugangsdaten aus. Senden Sie jedes Mal name mit (den aktuellen Namen, wenn Sie nicht umbenennen). description wird immer geschrieben; fehlt das Feld, wird die Beschreibung geleert. Nur die gesendeten Anbieterfelder ändern sich; ist ein Feld mit Zugangsdaten dabei, wird die zusammengeführte Konfiguration vor dem Speichern erneut geprüft (422 bei Fehlschlag). Bei Datenbanken schaltet "ssh_host": "" den SSH-Tunnel ab. Gibt 200 mit leerem Body zurück.

DELETE /integration/connections/:connectionId

Löscht die Verbindung und ihre gespeicherten Zugangsdaten. Bei Google Drive wird die Berechtigung zuerst bei Google widerrufen. Gibt 204 zurück.

POST /integration/connections/:connectionId/reconnect

Startet für eine Google-Drive-Verbindung eine neue OAuth-Zustimmung und behält ihre ID und ihren Namen bei. Gibt 200 {"auth_url": "..."} zurück. Anbieter mit Zugangsdaten antworten mit 501; aktualisieren Sie diese per PATCH.

Datenbanken

Berechtigungsstufen

Die database_permission der Verbindung bestimmt, welches SQL der Abfrage-Endpunkt akzeptiert, unabhängig davon, was der API-Schlüssel darf:

Bei read_only und create_update wird die gesamte Anweisung nach verbotenen Schlüsselwörtern durchsucht. Eine Leseabfrage, die ein Wort wie update auch nur in einem Spaltennamen oder String erwähnt, wird deshalb abgelehnt. Bei MySQL, MariaDB und PostgreSQL werden schreibgeschützte Sitzungen zusätzlich im Read-only-Modus geöffnet; SQL Server verlässt sich allein auf die Schlüsselwortprüfung. Verbinden Sie sich in jedem Fall mit einem Datenbankbenutzer, der nur die Rechte hat, die Sie tatsächlich vergeben möchten.

GET /integration/connections/:connectionId/database/schema

Alle Tabellen und Views im Schema der Verbindung, mit ihren Spalten:

{
  "schema": {
    "name": "public",
    "tables": [
      {
        "schema": "public",
        "name": "demo_orders",
        "columns": [
          { "name": "id", "data_type": "integer", "nullable": false },
          { "name": "customer_id", "data_type": "integer", "nullable": false },
          { "name": "status", "data_type": "text", "nullable": true }
        ]
      }
    ]
  }
}

GET /integration/connections/:connectionId/database/connection

Die gespeicherten Verbindungsdetails ohne Passwort. Bei Workspace-Verbindungen nur für Inhaber und Admins. Felder, die Sie leer gelassen haben, kommen als 0 oder "" zurück, auch wenn beim Verbinden ein Standardwert verwendet wurde.

POST /integration/connections/:connectionId/database/query

curl -X POST https://api.stickyprompts.com/api/v1/integration/connections/42/database/query \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT c.name, SUM(o.total) AS revenue FROM demo_orders o JOIN demo_customers c ON c.id = o.customer_id GROUP BY c.name ORDER BY revenue DESC LIMIT 5"}'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/integration/connections/42/database/query",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={"query": "SELECT name, city FROM demo_customers ORDER BY name", "row_limit": 50},
)
data = r.json()
rows = [dict(zip(data["columns"], row)) for row in data["rows"]]

const res = await fetch(
  "https://api.stickyprompts.com/api/v1/integration/connections/42/database/query",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "SELECT name, city FROM demo_customers ORDER BY name" }),
  },
);
const { columns, rows, truncated } = await res.json();

Antwort bei einem SELECT:

{
  "columns": ["name", "revenue"],
  "rows": [["Hawthorne Goods", "18240.00"], ["Cedar & Pine Outfitters", "15110.50"]],
  "row_count": 2,
  "truncated": false
}

truncated: true bedeutet, dass es über row_limit hinaus weitere Zeilen gab. Numerische Spalten kommen oft als Strings an. Andere Anweisungen (auf höheren Stufen erlaubt) geben nur row_count zurück, die Zahl der betroffenen Zeilen. SQL-Fehler der Datenbank liefern 500 ohne die Meldung der Datenbank; testen Sie Abfragen daher zuerst in einem Datenbank-Client.

E-Mail

E-Mails werden immer mit den eigenen Zugangsdaten des verbundenen Kontos versendet; einen von StickyPrompts bereitgestellten Absender gibt es nicht.

GET /integration/connections/:connectionId/email/connection

Die Absendereinstellungen (provider, default_from_email, default_from_name, default_reply_to, bei SMTP außerdem Host, Port, Benutzername und Verschlüsselung). Tokens und Passwörter werden nie zurückgegeben. Bei Workspace-Verbindungen nur für Inhaber und Admins.

POST /integration/connections/:connectionId/email/send

curl -X POST https://api.stickyprompts.com/api/v1/integration/connections/41/email/send \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "sales@northwind.example", "name": "Sales team" }],
    "subject": "Pipedrive: Deals at Proposal Made",
    "html_body": "<p>2 deals at Proposal Made, worth $28,788.</p>",
    "text_body": "2 deals at Proposal Made, worth $28,788."
  }'

Antwort 200 {"message_id": "<...>", "provider": "postmark"}: die eigene ID des Anbieters, praktisch, um die Nachricht in dessen Dashboard zu finden.

CRM

Lesen funktioniert bei jeder CRM-Verbindung. Schreiben, also Kontakte hinzufügen oder bearbeiten und Deals anlegen, erfordert allow_write an der Verbindung.

Kontakt: email (bei jedem Schreibvorgang erforderlich und beim Bearbeiten der Suchschlüssel), first_name, last_name, phone, company, custom_fields (anbieterspezifisch), list_ids (Brevo, ActiveCampaign) und tag_ids (ActiveCampaign). Ergebnisse kommen als {"remote_id", "provider", "contact"} zurück.

Deal: title, value, currency, contact_email (muss zu einem bestehenden Kontakt gehören) und stage (eine frei wählbare Bezeichnung). Ergebnisse kommen als {"remote_id", "provider", "deal"} zurück.

GET /integration/connections/:connectionId/crm/connection

{"provider": "pipedrive", "allow_write": true} (bei ActiveCampaign zusätzlich api_url).

GET /integration/connections/:connectionId/crm/contacts

Durchsucht Kontakte mit query (erforderlich) und optionalen Anbieterfiltern in Klammernotation, zum Beispiel ?query=priya&filters[organization_id]=1. Pipedrive und ActiveCampaign durchsuchen Freitext; Brevo sucht genau eine E-Mail-Adresse oder ID.

GET /integration/connections/:connectionId/crm/contacts/list

Blättert durch Kontakte. Zuerst limit (Standard 50), danach paginieren Sie mit cursor (Pipedrive: den vorherigen next_cursor übergeben) oder offset (ActiveCampaign, Brevo). Gibt {"contacts": [...], "has_more": true, "next_cursor": "..."} zurück.

POST /integration/connections/:connectionId/crm/contacts

Fügt einen Kontakt hinzu. Es wird immer ein neuer Kontakt angelegt, selbst wenn die E-Mail-Adresse schon existiert; suchen Sie also zuerst.

{ "email": "priya.raman@hawthornegoods.example", "first_name": "Priya", "last_name": "Raman", "company": "Hawthorne Goods" }

PATCH /integration/connections/:connectionId/crm/contacts

Bearbeitet den Kontakt mit dieser email; nur die gesendeten Felder ändern sich (senden Sie "", um ein Feld zu leeren). Legt nie einen Kontakt an: 404 "no matching contact was found in the crm to update".

GET /integration/connections/:connectionId/crm/deals

Durchsucht Deals mit query nach Titel oder nach der E-Mail-Adresse des verknüpften Kontakts, dazu kommen Anbieterfilter (bei Pipedrive: status, person_id, organization_id, exact_match).

GET /integration/connections/:connectionId/crm/deals/list

Blättert durch Deals, paginiert wie bei Kontakten. Zu den Pipedrive-Filtern gehören stage_id, status, owner_id und pipeline_id.

POST /integration/connections/:connectionId/crm/deals

{ "title": "Cedar & Pine - Scale plan, 42 stores", "value": 4788, "currency": "USD", "contact_email": "marcus.webb@cedarpine.example", "stage": "Proposal Made" }

404, wenn kein Kontakt diese E-Mail-Adresse hat.

GET /integration/connections/:connectionId/crm/lists, /crm/tags

Listen (Brevo, ActiveCampaign) und Tags (ActiveCampaign) als [{"id": "12", "name": "Newsletter"}], zur Verwendung in Filtern und in list_ids / tag_ids eines Kontakts. Andere Anbieter antworten mit 501.

Google Drive

Die Speicherrouten wirken immer auf Ihre eigene persönliche Drive-Verbindung und erwarten den Anbieter im Pfad: /integration/google_drive/storage/.... Ordner- und Eintrags-IDs sind root oder Drive-IDs.

GET /integration/:provider/storage/entries

Listet einen Ordner auf: folder_id (Standard root), page_token, page_size (1-200, Standard 100), kind (folder oder file). Gibt {"entries": [...], "next_page_token": "", "breadcrumbs": [...]} zurück. Jeder Eintrag hat id, name, kind, mime_type, size, modified_at, web_url, importable und import_name (Docs und Drawings werden als PDF importiert, Sheets als XLSX, Slides als PPTX).

GET /integration/:provider/storage/search

query (erforderlich) plus dieselbe Paginierung und dieselben Filter.

GET /integration/:provider/storage/entry/:entryId

POST /integration/:provider/storage/import

Kopiert 1-20 Drive-Einträge (entry_ids) als normale Dateien in StickyPrompts, optional verknüpft mit einer project_id. Jeder Eintrag gelingt oder scheitert für sich, prüfen Sie also immer failed: {"files": [...], "failed": [{"entry_id": "...", "error": "..."}]}. Bis zu 100 MB pro Datei.

POST /integration/:provider/storage/export

Kopiert eine StickyPrompts-Datei, die Ihnen gehört (file_id), in einen Drive-Ordner (folder_id, root erlaubt), optional umbenannt mit name.

Verwandte Seiten