Zum Inhalt springen

Leitfäden

Tools

Die Tools der Agenten einzeln aufrufen, mit ihren Scopes und Eingaben.

Piqline-Agenten arbeiten mit Tools: den Korpus lesen, live suchen, schreiben, handeln. Die API stellt jedes davon in derselben Form bereit. 92 Tools sind aufrufbar. Der Katalog listet sie mit ihren Scopes auf, und die Referenz beschreibt die Parameter jedes Tools mit Aufrufbeispielen.

Tools auflisten#

HTTP
GET https://piqline.com/api/v1/tools
GET https://piqline.com/api/v1/tools?agent=linkedin
GET https://piqline.com/api/v1/tools/{nom}

agent akzeptiert all (Standard), piqline, requete, facebook, linkedin, upwork oder onboarding. Jedes Tool in der Liste enthält:

FeldBedeutung
nameder Name des Tools, wie Sie es aufrufen
descriptionwas das Tool tut, auf Englisch, so wie der Agent es liest
agentsdie Agenten, die das Tool haben
requiresdie erforderlichen Scopes
callabletrue, wenn Ihr Schlüssel es aufrufen kann
missing_scopesScopes, die dem Schlüssel fehlen
confirmation_in_chattrue, wenn der Chat vor der Ausführung des Tools um Bestätigung bittet
read_onlytrue, wenn das Tool nichts ändert
input_schemaJSON Schema der Eingabe

Tools, die Ihr Schlüssel nicht aufrufen kann, bleiben in der Liste, mit callable: false und missing_scopes. GET/api/v1/tools/{nom} liefert denselben Eintrag für ein einzelnes Tool, ohne confirmation_in_chat und read_only.

Tool aufrufen#

HTTP
POST https://piqline.com/api/v1/tools/{nom}
Content-Type: application/json

Der JSON-Body ist die Eingabe des Tools, wie input_schema sie beschreibt. Ein Tool ohne Eingabe akzeptiert einen leeren Body.

curl -s https://piqline.com/api/v1/tools/searchItems \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"levée de fonds","limit":5}'

Die Antwort enthält den Namen des Tools und seine Ausgabe, dieselbe Ausgabe, die der Agent liest:

JSON
{
  "tool": "searchItems",
  "output": {
    "count": 1,
    "hasMore": true,
    "items": [
      {
        "id": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
        "sourceId": "e1f4b2a8-6c3d-4957-b0a1-82d5c7f3e964",
        "title": "Titre de l’article",
        "excerpt": "Début du texte…",
        "itemType": "article",
        "platform": "rss",
        "sourceName": "Blog du secteur",
        "sourceBadge": null,
        "occurredAt": "2026-10-27T08:14:00.000+00:00",
        "url": "https://exemple.fr/article",
        "language": "fr"
      }
    ]
  }
}

occurredAt ist das Anzeigedatum des Items. getItem liefert zusätzlich detectedAt (von Piqline zuerst gesehen), lastSeenAt (zuletzt gesehen) und publishedAt.

Ein Fehler kommt als application/problem+json zurück: siehe Fehler.

Wer was aufrufen darf#

  • Die Rolle des Erstellers begrenzt den Schlüssel. Ein Tool, das diese Rolle nicht öffnet, antwortet mit 403 forbidden. Schreib-Tools, Aktions-Tools und der Agent onboarding sind Ownern und Admins vorbehalten.
  • Chat-Karten gibt es in der API nicht. askUser, proposeSources, proposeBoard und verwandte Tools werden einer Person angezeigt und führen nichts aus: Sie antworten mit 404 not_found. Für diesen Dialog starten Sie einen Agenten.
  • Aktions-Tools warten nicht auf Bestätigung. Der Chat fragt danach. Ein direkter Aufruf mit dem Scope act wird sofort ausgeführt.
  • Live-Lesezugriffe verbrauchen Credits. Tools mit dem Scope explore belasten das monatliche Limit des Workspace.

Katalog#

Korpus und Workspace lesen#

Tools des Piqline-Agenten. Sie lesen, was der Workspace bereits erfasst hat: keine Credits verbraucht, nichts geschrieben.

ToolTypScopesRolle
getCoverageStatsLesenreadErfassungsvolumen und Zustand: Summen, aufgeteilt nach Plattform und Art, Erfassungsreihen über das Analysefenster (1h, 24h, 7d oder 30d).
listSourcesLesenreadQuellen, denen der Workspace folgt, mit Anzahl der Items, Zustand und letztem Lesevorgang.
searchItemsLesenreadSucht Items (Beiträge, Videos, Artikel, Anzeigen, Jobs) mit Filtern: Text, Plattform, Art, Quelle. Ohne Filter werden die neuesten geliefert (höchstens 40).
getItemLesenreadDetail eines Items: Text, Transkript, OCR, erkannte Themen, bedeutungsnahe Items und seine Beobachtungsdaten.
searchPassagesLesenreadBedeutungssuche in langen Dokumenten (vom Motor gelesene PDFs): die Passagen, die einer Frage am nächsten kommen, mit Item, Seite und Abschnittstitel.
citeItemLesenreadPrüft, ob eine Passage wörtlich in einem Item vorkommt, und liefert eine Zitatnummer; andernfalls die nächstliegende Passage. Grundlage des Modus Zitate im Chat.
drawDiagramLesenreadZeichnet die Antwort als SVG-Diagramm (Zeitleiste, Matrix, Ablauf, Baum …): Farben nach Rolle im Theme, SVG vor der Anzeige bereinigt. Grundlage des Modus Diagramm im Chat.
createCanvasLesenreadKompiliert ein Canvas (eine TSX-Datei, die nur das SDK piqline/canvas importiert) und liefert anzeigefertigen Code oder den zu behebenden Fehler. Grundlage der Modi Canvas und Bericht im Chat.
getTopicsLesenreadErkannte Themen mit ihrem Anteil an der Aufmerksamkeit und Stories (dasselbe Thema, gesehen in mehreren Quellen).
getSignalsLesenreadOffene Signale, ausgelöst durch die Persistenzregeln des Workspace, mit Vorlaufzeit und Status.
listWorkspaceTablesLesenreadBereits im Workspace erstellte Tabellen: Name, Kommentar, Anzahl der Spalten und Zeilen und ob sich die Tabelle selbst füllt.
getWorkspaceTableLesenreadEine Workspace-Tabelle als JSON: Schema, Spalten und Zeilen. Dient als Grundlage oder Datenquelle für eine Website, eine App oder einen Agenten (Scope read).
listBookmarksLesenreadLesezeichen und Ordner des Workspace-Tresors: Titel, Typ, Ordner, Status, Aufnahme. Optionaler Filter nach Wort, Status oder Typ.
listEntitiesLesenreadVerfolgte Entitäten (Unternehmen, Marken, öffentliche Konten) und verknüpfte Items im Zeitraum.
listWatchContractsLesenreadAuf Quellen gesetzte Watch-Verträge: Absicht, behaltene und ausgeschlossene Begriffe, Ereignis.
checkInvestigationLesenreadStatus der letzten Edge-Recherche oder einer bestimmten: ausstehend, laufend, abgeschlossen mit ihren Kandidaten oder fehlgeschlagen.
checkHuntLesenreadStatus der letzten Suche oder einer bestimmten: Stufe, gefundene Personen mit dem Urteil des Codes und Ihrem, und je Kriterium sein Status und sein datierter öffentlicher Beleg (URL, Datum, Ausschnitt). Nie Kontaktdaten.
planSourcePackLesenreadSchlägt für ein Ziel einen stimmigen Satz von Quellen zum Verfolgen vor. Erstellt nichts.
listWidgetsLesenreadWidgets, die auf ein Board dieses Workspace gelegt werden können, für die Person gereiht, mit ihren Gründen.
getAdvertiserCampaignsLesenreadAnzeigenakte eines Werbetreibenden aus den Erfassungen des Workspace: Anzeigen, laufende, Daten, Bibliotheken, Länder, gelesene Bedarfe, neue Anzeigen pro Monat und Hochfahren, neueste Anzeigen, Signale. Nie eine Person. Keine Credits.
listAdSignalsLesenreadAnzeigensignale des Workspace, stündlich berechnet: Kampagne gestartet oder gestoppt, Hochfahren, neues Land, neue Plattform, bezahlte Einstellung, Aktion, Launch, neuer Werbetreibender. Keine Credits.
listCollectedAdsLesenreadAnzeigenerfassungen des Workspace (Meta, TikTok, Google, LinkedIn), bereits gelesen: die Liste oder, mit dem Namen einer Erfassung, ihre Aufschlüsselungen (Winkel, Angebote, Tonalitäten, Formate), ihr Rhythmus, ihre am längsten laufenden Anzeigen und ihre Anzeigen, gefiltert nach Bibliothek, Status, Winkel oder Wort. Keine Credits.

Web und Register live erkunden#

Live-Lesezugriffe auf das Web und öffentliche Netzwerke. Sie verbrauchen Credits; im Workspace wird nichts gespeichert.

ToolTypScopesRolle
readPageLive-LesenexploreLiest eine öffentliche Webseite: Titel, Haupttext (6.000 Zeichen), gefundene Feeds und 30 Links.
searchWebLive-LesenexploreDurchsucht das öffentliche Web, um Kandidaten-URLs zu finden.
browserReadLive-LesenexploreLiest eine dynamische oder geschützte Seite mit erzwungenem Browser. Gleiche Form wie readPage.
waybackHistoryLive-LesenexploreWayback-Machine-Aufnahmen einer URL: erste Aufnahme und aktuelle Aufnahmen.
registryLookupLive-LesenexploreSucht ein Unternehmen in einem öffentlichen Register: Sirene (Frankreich), EDGAR (USA), Companies House (Vereinigtes Königreich) oder OpenCorporates.
socialCatalogLive-LesenexploreListet die Lese-Endpunkte der sozialen Netzwerke (höchstens 40), filterbar nach Plattform.
socialCallLive-LesenexploreRuft einen Lese-Endpunkt eines sozialen Netzwerks auf und liefert bis zu 20 kompakte Items.
previewSourceLive-LesenexploreLive-Stichprobe (5 bis 10 Items) einer Quelle, bevor Sie sie abonnieren.
whoSaidItFirstLive-LesenexploreWer eine Information zuerst im Web veröffentlicht hat, Seite für Seite, und wann Ihre Quellen sie gesehen haben. Geht von einem Thema oder einem Item aus; als private Zeitleiste des Workspace gespeichert.

Facebook#

Tools des Facebook-Agenten: Marketplace-Anzeigen und öffentliche Gruppen, live gelesen.

ToolTypScopesRolle
findMarketplaceLocationLive-LesenexploreWandelt den Namen einer Stadt oder Gegend in Marketplace-Koordinaten um.
searchMarketplaceLive-LesenexploreDurchsucht öffentliche Marketplace-Anzeigen nach Stichwort rund um einen Ort (Stadt oder Koordinaten), über höchstens 3 Seiten.
getMarketplaceListingLive-LesenexploreDetail einer Anzeige: Beschreibung, Attribute, Fotos, Lieferung, genaues Datum, wenn Facebook es liefert.
getMarketplaceListingsLive-LesenexploreDetail von 2 bis 6 Anzeigen auf einmal, als Vergleichstabelle.
getFacebookGroupLive-LesenexploreÖffentliches Profil einer Gruppe: Datenschutz, Größe, Aktivität, Kategorien, Regeln.
getFacebookGroupPostsLive-LesenexploreBeiträge einer öffentlichen Gruppe, in Seiten zu 3 (höchstens 6 Seiten).
getFacebookPostLive-LesenexploreDetail eines öffentlichen Beitrags oder Reels: Text, Autor, Datum, Reaktionen, Aufrufe.
getFacebookPostCommentsLive-LesenexploreKommentare zu einem öffentlichen Beitrag, filterbar nach Stichwörtern (höchstens 3 Seiten).

LinkedIn#

Tools des LinkedIn-Agenten: öffentliche Beiträge, Unternehmensseiten und Anzeigen, live gelesen. Kontaktdaten werden nie gelesen.

ToolTypScopesRolle
searchLinkedinPostsLive-LesenexploreDurchsucht öffentliche Beiträge nach Stichwörtern in Echtzeit, neueste zuerst (ein partieller Lesevorgang wird im Ergebnis markiert), mit Titel und Rolle des Autors, wenn der Beitrag eine Stelle ausschreibt, und vom Code berechneten Signalen: Einstellung, Finanzierung, Launch, Expansion, Reorganisation, Verfügbarkeit, Abgang.
probeLinkedinWatchLive-LesenexplorePrüft 1 bis 3 Suchvarianten, bevor Sie eine LinkedIn-Beobachtung abonnieren, und liefert das Recherche-Ticket, das dem Abonnement beizufügen ist.
getLinkedinPostLive-LesenexploreLiest einen öffentlichen Beitrag oder Artikel: Text, Autor, Datum, Reaktionen, Kommentare mit ihren Signalen.
getLinkedinPostTranscriptLive-LesenexploreTranskript des Videos eines öffentlichen Beitrags, nur berechnet, wenn es existiert.
getLinkedinCompanyLive-LesenexploreÖffentliche Unternehmensseite: Beschreibung, Mitarbeiterzahl, Branche, Finanzierung, neueste Beiträge mit ihren Signalen.
getLinkedinCompanyPostsLive-LesenexploreÄltere Beiträge einer Unternehmensseite, mit einer Zusammenfassung der Signale (Einstellung, Finanzierung, Launches).
searchLinkedinAdsLive-LesenexploreDurchsucht die Anzeigenbibliothek: Werbetreibender, Format, Daten, Impressionen.
getLinkedinAdLive-LesenexploreDetail einer Anzeige aus der Bibliothek: Targeting, Impressionen pro Land, Dauer.
matchLinkedinPostsLive-LesenexploreBringt verfügbare Personen mit Gelegenheiten aus öffentlichen Beiträgen zusammen (zwei Suchen).
getLinkedinProfileLive-LesenexploreBegrenzter Lesevorgang eines öffentlichen /in/-Profils, nur ausgehend von einem öffentlichen Beitrag, der die Person nennt. Workspaces vorbehalten, die diese Option aktiviert haben.

Upwork#

Tools des Upwork-Agenten: öffentliche Jobs lesen, bewerten und anhand der Wissensbasis des Workspace beantworten. An Upwork wird nichts gesendet.

ToolTypScopesRolle
searchUpworkJobsLive-LesenexploreLiest eine Seite öffentlicher Ergebnisse (etwa zehn Jobs) und bewertet jeden Job anhand der Wissensbasis. Die Jobs werden der Pipeline des Workspace hinzugefügt.
getUpworkJobLive-LesenexploreLiest einen Job: Beschreibung, Skills, Budget, Aktivität, Kunde. Fügt der Pipeline einen datierten Snapshot hinzu.
scoreUpworkJobsSchreibenwriteBewertet die Jobs der Pipeline nach einer Änderung der Wissensbasis erneut. Es wird keine Seite gelesen.
getUpworkRadarLive-LesenexploreMarktradar: Volumen pro Tag, Quartile von Satz und Budget, Skills, Wettbewerb, Länder der Kunden.
listUpworkLeadsLesenreadUpwork-Pipeline: Anzahl pro Status, beste Jobs zuerst, Ergebnis jedes Jobs.
updateUpworkLeadSchreibenwriteÄndert den Status eines Jobs der Pipeline (gesendet, Antwort, Gespräch, gewonnen, verloren, ignoriert) und behält eine Notiz.
getUpworkKnowledgeLesenreadUpwork-Wissensbasis des Workspace: Leistungen, Werkzeuge, zu meidende Projekte, Mindestsätze, Fallstudien, Tonalität, Signatur.
updateUpworkKnowledgeSchreibenwriteAktualisiert die Wissensbasis. Von Ihnen gesendete Listen ersetzen die gespeicherten Listen.
listUpworkTemplatesLesenreadGespeicherte Angebotsvorlagen, mit ihren Slots und ihren Fragenregeln.
upsertUpworkTemplateSchreibenwriteErstellt oder aktualisiert eine Angebotsvorlage.
draftUpworkProposalSchreibenwrite, exploreEntwirft ein Angebot für einen Job anhand einer Vorlage. Den Text fügen Sie selbst auf Upwork ein.
listUpworkCampaignsLesenreadGespeicherte Kampagnen: Suche, Mindestscore, Status, letzte Aktualisierung, Zustand der Quellen.
saveUpworkCampaignSchreibenwriteErstellt oder aktualisiert eine Kampagne: Name, Suche, Mindestscore, Vorlage.
simulateUpworkCampaignLive-LesenexploreSimuliert eine Kampagne an echten Jobs, bevor Sie ihr folgen. Nichts wird gespeichert.
followUpworkCampaignAktionactBittet den Motor, einer gespeicherten Kampagne in ihrem Erfassungsrhythmus zu folgen.
pauseUpworkCampaignAktionactHält den Motor davon ab, einer Kampagne zu folgen. Bereits gesehene Jobs bleiben in der Pipeline.
refreshUpworkCampaignsSchreibenwrite, exploreAktualisiert die verfolgten Kampagnen: führt die vom Motor erfassten Jobs zusammen, liest die erste Seite erneut live und bewertet die neuen Jobs.
checkUpworkOutcomesSchreibenwrite, exploreLiest die Seiten laufender Bewerbungen erneut, um ihr Ergebnis zu datieren: geschlossen, Gespräche begonnen, keine Antwort.
syncUpworkRepliesSchreibenwriteLiest die Benachrichtigungs-E-Mails von Upwork in den verbundenen Postfächern des Schlüsselerstellers und setzt den Status von Pipeline-Jobs weiter.

Im Workspace schreiben#

Tools des Piqline-Agenten, die Objekte des Workspace erstellen oder ändern. Sie verlangen den Scope write.

ToolTypScopesRolle
updateWorkspaceProfileSchreibenwriteSpeichert das Bedarfsprofil des Workspace: Ziele, Themen, Entitäten, Sprachen, Regionen, Niveau, Rhythmus.
followEntitySchreibenwriteFolgt einem Unternehmen, einer Marke oder einem öffentlichen Konto (nie einer Privatperson), um seine Items und Erwähnungen zu verknüpfen.
unfollowEntityLöschenwriteBeendet das Folgen einer Entität. Ihre bestehenden Verknüpfungen bleiben.
saveBookmarkSchreibenwriteSpeichert ein Lesezeichen im Tresor des Workspace. Eine http(s)-URL wird zum Lesen, Archivieren und Vektorisieren eingereiht.
setWatchContractSchreibenwriteSetzt einen Watch-Vertrag auf eine Quelle: Die Watch-Seite zeigt dann nur noch die passenden Items. Deterministisch, ohne Modell.
removeWatchContractLöschenwriteEntfernt den Watch-Vertrag einer Quelle: Alle Items erscheinen wieder.
initReaderInterviewSchreibenwriteSpeichert die zwei Antworten des Lese-Interviews (Wesentliches oder Detail, Hauptabsicht) im Leseprofil.
applyBoardChangeSchreibenwriteWendet bereits freigegebene Änderungen auf ein Board an.
buildDashboardSchreibenwriteBaut ein Board direkt, ohne den Widget-Picker.
saveWorkspaceTableSchreibenwriteErstellt eine Workspace-Tabelle, gefüllt mit den nützlichen Spalten.
writeFromWatchSchreibenwriteSchreibt einen Text aus den Items der Beobachtungen des Workspace (Artikel, LinkedIn-Beitrag, X-Thread, Instagram-Bildunterschrift, Newsletter, Videoskript, Pressemitteilung, SEO-Artikel, E-Mail, Zusammenfassung), in neun Sprachen, jede Tatsache mit [n] auf ihre Quelle belegt; der Text kommt zu den Entwürfen. Verbraucht einige Credits.
setTableFeedAktionact, writeErweckt eine Tabelle zum Leben: Sobald ein Item des Korpus zur Regel passt, wird es nach Bestätigung hinzugefügt. status=paused stoppt das Füllen.

Auf Quellen und Regeln einwirken#

Aktions-Tools des Piqline-Agenten. Im Chat verlangt jedes eine Bestätigung. Über die API gilt ein direkter Aufruf mit dem Scope act als Bestätigung: Rufen Sie diese Tools erst auf, nachdem die betroffene Person zugestimmt hat.

ToolTypScopesRolle
subscribeSourceAktionactAbonniert eine neue Quelle. Startet eine echte Erfassung (Lese-Jobs, Plattformkontingente).
subscribeSourcesAktionactAbonniert mehrere Quellen in einem Aufruf und liefert ein Ergebnis pro Quelle.
unsubscribeSourceAktionactBeendet das Folgen einer Quelle. Bereits erfasste Items bleiben im Korpus.
setHomeDashboardAktionactSetzt ein gespeichertes Board als Startseite des Workspace.
upsertSignalRuleAktionactErstellt oder aktualisiert eine Persistenz-Signalregel: Sie löst aus, wenn ein Item länger als der Schwellenwert online bleibt.
upsertQuestionRuleAktionactErstellt oder aktualisiert eine Dauerfrage: ein Satz in einfacher Sprache, den Jev an jedes neue Item der Quellen des Workspace stellt. Der Wahrscheinlichkeitsschwellenwert erzeugt das Signal.
startInvestigationAktionactReiht eine Edge-Recherche im Hintergrund für diesen Workspace ein (Owner oder Admin).
startHuntAktionactStartet eine Suche: Personen finden, die nachprüfbare Kriterien erfüllen, jedes Kriterium durch eine datierte öffentliche Quelle belegt. Sensible Kriterien werden abgelehnt, es werden keine Kontaktdaten geliefert. Läuft im Hintergrund und verbraucht die Credits des Monats; Owner oder Admin.
buildAdAuditSchreibenwriteRückwirkendes Audit der Kampagnen von 1 bis 6 bereits erfassten Werbetreibenden über N Monate: eine Workspace-Tabelle (Werbetreibender, Monat, neue Anzeigen, Stopps, Bibliotheken, Länder, gelesene Bedarfe, Hochfahren) und die Zahlen einer zitierten Zusammenfassung. Keine Credits.
findCreatorSponsorsAktionact, write, exploreWer YouTube-Creator in einer Nische bezahlt: Suche nach aktuellen Videos, aus jedem Video abgeleitete Sponsoren, eine Workspace-Tabelle „Sponsoren · Nische“. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin.
importAdHistoryAktionact, write, exploreImportiert den Google-Verlauf einer Werbetreibenden-Erfassung: bis zu 20 Seiten (etwa 800 Anzeigen seit 2021), um vergangene Kampagnen zu datieren. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin.
startAdCollectionAktionact, write, exploreStartet eine Anzeigenerfassung zu einem Werbetreibenden (Name oder Domain) oder einem Stichwort: liest Meta, TikTok, Google und LinkedIn, bringt jede Anzeige ins gleiche Format und liest dann Winkel, Angebot, Zielgruppe und Tonalität. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin.

Eine Frage zur API oder ein Fehler auf dieser Seite? Schreiben Sie uns.