Guide
Tool
Chiama uno per uno i tool degli agenti, con i loro scope e i loro input.
Gli agenti Piqline lavorano con dei tool: leggere il corpus, cercare in diretta, scrivere, agire. L'API espone ciascuno di essi nella stessa forma. 92 tool sono richiamabili; il catalogo li elenca con i loro scope, e il riferimento descrive i parametri di ciascuno, con esempi di chiamata.
Elencare i tool#
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 accetta all (il valore predefinito), piqline, requete, facebook, linkedin, upwork oppure onboarding. Ogni tool dell'elenco contiene:
| Campo | Significato |
|---|---|
name | il nome del tool, come lo chiami |
description | che cosa fa il tool, in inglese, come lo legge l'agente |
agents | gli agenti che hanno il tool |
requires | gli scope richiesti |
callable | true se la tua chiave può chiamarlo |
missing_scopes | gli scope che la chiave non ha |
confirmation_in_chat | true se la chat chiede conferma prima di eseguire il tool |
read_only | true se il tool non modifica nulla |
input_schema | JSON Schema dell'input |
I tool che la tua chiave non può chiamare restano nell'elenco, con callable: false e missing_scopes. GET/api/v1/tools/{nom} restituisce la stessa voce per un singolo tool, senza confirmation_in_chat né read_only.
Chiamare un tool#
POST https://piqline.com/api/v1/tools/{nom}
Content-Type: application/jsonIl corpo JSON è l'input del tool, come lo descrive input_schema. Un tool senza input accetta un corpo vuoto.
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}'const response = await fetch("https://piqline.com/api/v1/tools/searchItems", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "levée de fonds", limit: 5 }),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://piqline.com/api/v1/tools/searchItems",
headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
json={"query": "levée de fonds", "limit": 5},
)
data = response.json()La risposta contiene il nome del tool e il suo output, lo stesso output che legge l'agente:
{
"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 è la data di visualizzazione dell'elemento. getItem restituisce anche detectedAt (visto per la prima volta da Piqline), lastSeenAt (visto per l'ultima volta) e publishedAt.
Un errore torna come application/problem+json: vedi Errori.
Chi può chiamare che cosa#
- Il ruolo del creatore limita la chiave. Un tool che quel ruolo non apre risponde
403 forbidden. I tool di scrittura, i tool di azione e l'agenteonboardingsono riservati a owner e admin. - Le card della chat non esistono nell'API.
askUser,proposeSources,proposeBoarde simili vengono mostrati a una persona e non eseguono nulla: rispondono404 not_found. Per ottenere quel dialogo, esegui un agente. - I tool di azione non aspettano conferma. La chat la chiede. Una chiamata diretta con lo scope
actviene eseguita subito. - Le letture in diretta consumano crediti. I tool dello scope
exploreprelevano crediti dal limite mensile del workspace.
Catalogo#
Leggere il corpus e il workspace#
Tool dell'agente Piqline. Leggono ciò che il workspace ha già raccolto: nessun credito consumato, nulla viene scritto.
| Tool | Tipo | Scope | Ruolo |
|---|---|---|---|
getCoverageStats | Lettura | read | Volumi e stato della raccolta: totali, suddivisione per piattaforma e per tipo, serie di acquisizione sulla finestra di analisi (1h, 24h, 7d o 30d). |
listSources | Lettura | read | Fonti seguite dal workspace, con numero di elementi, stato e ultima lettura. |
searchItems | Lettura | read | Cerca elementi (post, video, articoli, inserzioni, offerte di lavoro) con filtri: testo, piattaforma, tipo, fonte. Senza filtro, restituisce i più recenti (al massimo 40). |
getItem | Lettura | read | Dettaglio di un elemento: testo, trascrizione, OCR, argomenti rilevati, elementi vicini per significato e date di osservazione. |
searchPassages | Lettura | read | Ricerca per significato nei documenti lunghi (PDF letti dal Motor): i passaggi più vicini a una domanda, con l'elemento, la pagina e il titolo della sezione. |
citeItem | Lettura | read | Verifica che un passaggio compaia parola per parola in un elemento e restituisce un numero di citazione; altrimenti il passaggio più vicino. Base della modalità Citazioni della chat. |
drawDiagram | Lettura | read | Disegna la risposta come diagramma SVG (timeline, matrice, flusso, albero…): colori per ruolo del tema, SVG ripulito prima della visualizzazione. Base della modalità Diagramma della chat. |
createCanvas | Lettura | read | Compila un canvas (un file TSX che importa solo l'SDK piqline/canvas) e restituisce il codice pronto da visualizzare, oppure l'errore da correggere. Base delle modalità Canvas e Report della chat. |
getTopics | Lettura | read | Argomenti rilevati con la loro quota di voce e le storie (lo stesso soggetto visto in più fonti). |
getSignals | Lettura | read | Segnali aperti, attivati dalle regole di persistenza del workspace, con il loro anticipo e il loro stato. |
listWorkspaceTables | Lettura | read | Tabelle già create nel workspace: nome, commento, numero di colonne e di righe, e se la tabella si popola da sola. |
getWorkspaceTable | Lettura | read | Una tabella del workspace in JSON: schema, colonne e righe. Serve da base o da feed per un sito, un'app o un agente (scope read). |
listBookmarks | Lettura | read | Segnalibri e cartelle del vault del workspace: titolo, tipo, cartella, stato, ammissione. Filtro facoltativo per parola, stato o tipo. |
listEntities | Lettura | read | Entità seguite (aziende, marchi, account pubblici) ed elementi collegati nel periodo. |
listWatchContracts | Lettura | read | Contratti di monitoraggio impostati sulle fonti: intento, termini mantenuti ed esclusi, evento. |
checkInvestigation | Lettura | read | Stato dell'ultima indagine Edge, o di una indagine specifica: in attesa, in corso, conclusa con i suoi candidati, oppure fallita. |
checkHunt | Lettura | read | Stato dell'ultima ricerca, o di una ricerca specifica: fase, persone trovate con il verdetto del codice e il tuo, e per ogni criterio il suo stato e la sua prova pubblica datata (URL, data, estratto). Mai recapiti. |
planSourcePack | Lettura | read | Propone un insieme coerente di fonti da seguire per un obiettivo. Non crea nulla. |
listWidgets | Lettura | read | Widget che possono andare su una board di questo workspace, ordinati per la persona, con le loro motivazioni. |
getAdvertiserCampaigns | Lettura | read | Scheda delle inserzioni di un inserzionista dalle raccolte del workspace: inserzioni, quelle attive, date, librerie, paesi, esigenze lette, nuove inserzioni al mese e aumenti di ritmo, ultime inserzioni, segnali. Mai una persona. Nessun credito. |
listAdSignals | Lettura | read | Segnali pubblicitari del workspace, calcolati ogni ora: campagna avviata o interrotta, aumento di ritmo, nuovo paese, nuova piattaforma, assunzione a pagamento, promozione, lancio, nuovo inserzionista. Nessun credito. |
listCollectedAds | Lettura | read | Raccolte di inserzioni del workspace (Meta, TikTok, Google, LinkedIn), già lette: l'elenco oppure, con il nome di una raccolta, le sue suddivisioni (angoli, offerte, toni, formati), il suo ritmo, le sue inserzioni più longeve e le sue inserzioni filtrate per libreria, stato, angolo o parola. Nessun credito. |
Esplorare il web e i registri in diretta#
Letture in diretta sul web e sulle reti pubbliche. Consumano crediti; nulla viene salvato nel workspace.
| Tool | Tipo | Scope | Ruolo |
|---|---|---|---|
readPage | Lettura in diretta | explore | Legge una pagina web pubblica: titolo, testo principale (6.000 caratteri), feed individuati e 30 link. |
searchWeb | Lettura in diretta | explore | Cerca nel web pubblico per trovare URL candidati. |
browserRead | Lettura in diretta | explore | Legge una pagina dinamica o protetta con un browser forzato. Stessa forma di readPage. |
waybackHistory | Lettura in diretta | explore | Catture della Wayback Machine di un URL: prima cattura e catture recenti. |
registryLookup | Lettura in diretta | explore | Cerca un'azienda in un registro pubblico: Sirene (Francia), EDGAR (Stati Uniti), Companies House (Regno Unito) oppure OpenCorporates. |
socialCatalog | Lettura in diretta | explore | Elenca gli endpoint di lettura dei social network (al massimo 40), filtrabili per piattaforma. |
socialCall | Lettura in diretta | explore | Chiama un endpoint di lettura di un social network e restituisce fino a 20 elementi compatti. |
previewSource | Lettura in diretta | explore | Campione in diretta (da 5 a 10 elementi) di una fonte, prima di iscriversi. |
whoSaidItFirst | Lettura in diretta | explore | Chi ha pubblicato per primo un'informazione sul web, pagina per pagina, e quando le tue fonti l'hanno vista. Parte da un argomento o da un elemento; conservato come timeline privata del workspace. |
Facebook#
Tool dell'agente Facebook: annunci di Marketplace e gruppi pubblici, letti in diretta.
| Tool | Tipo | Scope | Ruolo |
|---|---|---|---|
findMarketplaceLocation | Lettura in diretta | explore | Trasforma il nome di una città o di un'area in coordinate di Marketplace. |
searchMarketplace | Lettura in diretta | explore | Cerca gli annunci pubblici di Marketplace per parola chiave attorno a un luogo (città o coordinate), su 3 pagine al massimo. |
getMarketplaceListing | Lettura in diretta | explore | Dettaglio di un annuncio: descrizione, attributi, foto, consegna, data esatta quando Facebook la fornisce. |
getMarketplaceListings | Lettura in diretta | explore | Dettaglio di 2-6 annunci insieme, come tabella di confronto. |
getFacebookGroup | Lettura in diretta | explore | Profilo pubblico di un gruppo: privacy, dimensione, attività, categorie, regole. |
getFacebookGroupPosts | Lettura in diretta | explore | Post di un gruppo pubblico, in pagine da 3 (al massimo 6 pagine). |
getFacebookPost | Lettura in diretta | explore | Dettaglio di un post o reel pubblico: testo, autore, data, reazioni, visualizzazioni. |
getFacebookPostComments | Lettura in diretta | explore | Commenti a un post pubblico, filtrabili per parole chiave (al massimo 3 pagine). |
LinkedIn#
Tool dell'agente LinkedIn: post pubblici, pagine aziendali e inserzioni, letti in diretta. I recapiti non vengono mai letti.
| Tool | Tipo | Scope | Ruolo |
|---|---|---|---|
searchLinkedinPosts | Lettura in diretta | explore | Cerca post pubblici per parole chiave, in tempo reale, dal più recente (una lettura parziale è segnalata nel risultato), con il titolo e il ruolo dell'autore quando il post riguarda un'assunzione, e segnali calcolati dal codice: assunzione, raccolta fondi, lancio, espansione, riorganizzazione, disponibilità, partenza. |
probeLinkedinWatch | Lettura in diretta | explore | Sonda da 1 a 3 varianti di query prima di iscriversi a un monitoraggio LinkedIn, e restituisce il ticket di indagine da allegare all'iscrizione. |
getLinkedinPost | Lettura in diretta | explore | Legge un post o un articolo pubblico: testo, autore, data, reazioni, commenti con i loro segnali. |
getLinkedinPostTranscript | Lettura in diretta | explore | Trascrizione del video di un post pubblico, fatturata solo se esiste. |
getLinkedinCompany | Lettura in diretta | explore | Pagina aziendale pubblica: descrizione, organico, settore, finanziamenti, ultimi post con i loro segnali. |
getLinkedinCompanyPosts | Lettura in diretta | explore | Post meno recenti di una pagina aziendale, con un riepilogo dei segnali (assunzioni, finanziamenti, lanci). |
searchLinkedinAds | Lettura in diretta | explore | Cerca nella libreria delle inserzioni: inserzionista, formato, date, impression. |
getLinkedinAd | Lettura in diretta | explore | Dettaglio di un'inserzione della libreria: targeting, impression per paese, durata. |
matchLinkedinPosts | Lettura in diretta | explore | Abbina persone disponibili a opportunità a partire da post pubblici (due ricerche). |
getLinkedinProfile | Lettura in diretta | explore | Lettura limitata di un profilo pubblico /in/, solo a partire da un post pubblico che nomina la persona. Riservato ai workspace che hanno attivato questa opzione. |
Upwork#
Tool dell'agente Upwork: offerte pubbliche lette, valutate e riscontrate a partire dalla knowledge base del workspace. Nulla viene inviato a Upwork.
| Tool | Tipo | Scope | Ruolo |
|---|---|---|---|
searchUpworkJobs | Lettura in diretta | explore | Legge una pagina di risultati pubblici (una decina di offerte) e valuta ciascuna offerta rispetto alla knowledge base. Le offerte vengono aggiunte alla pipeline del workspace. |
getUpworkJob | Lettura in diretta | explore | Legge un'offerta: descrizione, competenze, budget, attività, cliente. Aggiunge alla pipeline un'istantanea datata. |
scoreUpworkJobs | Scrittura | write | Rivaluta le offerte della pipeline dopo una modifica della knowledge base. Nessuna pagina viene letta. |
getUpworkRadar | Lettura in diretta | explore | Radar di mercato: volume al giorno, quartili di tariffa e di budget, competenze, concorrenza, paesi dei clienti. |
listUpworkLeads | Lettura | read | Pipeline Upwork: conteggio per stato, prima le migliori offerte, esito di ciascuna. |
updateUpworkLead | Scrittura | write | Modifica lo stato di un'offerta della pipeline (inviata, risposta, colloquio, vinta, persa, ignorata) e conserva una nota. |
getUpworkKnowledge | Lettura | read | Knowledge base Upwork del workspace: servizi, strumenti, progetti da evitare, tariffe minime, casi di studio, tono, firma. |
updateUpworkKnowledge | Scrittura | write | Aggiorna la knowledge base. Gli elenchi che invii sostituiscono quelli memorizzati. |
listUpworkTemplates | Lettura | read | Modelli di proposta salvati, con i loro slot e le loro regole per le domande. |
upsertUpworkTemplate | Scrittura | write | Crea o aggiorna un modello di proposta. |
draftUpworkProposal | Scrittura | write, explore | Redige una bozza di proposta per un'offerta a partire da un modello. Incolli tu stesso il testo su Upwork. |
listUpworkCampaigns | Lettura | read | Campagne salvate: ricerca, punteggio minimo, stato, ultimo aggiornamento, stato delle fonti. |
saveUpworkCampaign | Scrittura | write | Crea o aggiorna una campagna: nome, ricerca, punteggio minimo, modello. |
simulateUpworkCampaign | Lettura in diretta | explore | Simula una campagna su offerte reali prima di seguirla. Nulla viene salvato. |
followUpworkCampaign | Azione | act | Chiede al Motor di seguire una campagna salvata, al suo ritmo di raccolta. |
pauseUpworkCampaign | Azione | act | Impedisce al Motor di seguire una campagna. Le offerte già viste restano nella pipeline. |
refreshUpworkCampaigns | Scrittura | write, explore | Aggiorna le campagne seguite: unisce le offerte raccolte dal Motor, rilegge in diretta la prima pagina, valuta le nuove offerte. |
checkUpworkOutcomes | Scrittura | write, explore | Rilegge le pagine delle candidature in corso per datare il loro esito: chiusa, colloqui avviati, nessuna risposta. |
syncUpworkReplies | Scrittura | write | Legge le e-mail di notifica di Upwork nelle caselle collegate del creatore della chiave e fa avanzare lo stato delle offerte della pipeline. |
Scrivere nel workspace#
Tool dell'agente Piqline che creano o modificano oggetti del workspace. Richiedono lo scope write.
| Tool | Tipo | Scope | Ruolo |
|---|---|---|---|
updateWorkspaceProfile | Scrittura | write | Salva il profilo di esigenza del workspace: obiettivi, argomenti, entità, lingue, regioni, livello, ritmo. |
followEntity | Scrittura | write | Segue un'azienda, un marchio o un account pubblico (mai una persona privata) per collegare i suoi elementi e le sue menzioni. |
unfollowEntity | Eliminazione | write | Smette di seguire un'entità. I suoi collegamenti esistenti restano. |
saveBookmark | Scrittura | write | Salva un segnalibro nel vault del workspace. Un URL http(s) viene messo in coda per la lettura, l'archiviazione e la vettorizzazione. |
setWatchContract | Scrittura | write | Imposta un contratto di monitoraggio su una fonte: la pagina di monitoraggio mostra poi solo gli elementi corrispondenti. Deterministico, senza modello. |
removeWatchContract | Eliminazione | write | Rimuove il contratto di monitoraggio di una fonte: tutti gli elementi tornano visibili. |
initReaderInterview | Scrittura | write | Salva le due risposte dell'intervista di lettura (essenziale o dettaglio, intento principale) nel profilo di lettura. |
applyBoardChange | Scrittura | write | Applica a una board modifiche già approvate. |
buildDashboard | Scrittura | write | Costruisce direttamente una board, senza passare dalla selezione dei widget. |
saveWorkspaceTable | Scrittura | write | Crea una tabella del workspace, popolata con le colonne utili. |
writeFromWatch | Scrittura | write | Scrive un testo a partire dagli elementi dei monitoraggi del workspace (articolo, post LinkedIn, thread X, didascalia Instagram, newsletter, script video, comunicato stampa, articolo SEO, e-mail, riepilogo), in nove lingue, con ogni fatto citato [n] rispetto alla sua fonte; il testo entra nelle bozze. Consuma alcuni crediti. |
setTableFeed | Azione | act, write | Dà vita a una tabella: non appena un elemento del corpus corrisponde alla regola, viene aggiunto, dopo conferma. status=paused interrompe il popolamento. |
Agire su fonti e regole#
Tool di azione dell'agente Piqline. Nella chat, ciascuno chiede conferma. Tramite l'API, una chiamata diretta con lo scope act vale come conferma: chiama questi tool solo dopo che la persona interessata ha dato il suo consenso.
| Tool | Tipo | Scope | Ruolo |
|---|---|---|---|
subscribeSource | Azione | act | Si iscrive a una nuova fonte. Avvia una vera raccolta (job di lettura, quote delle piattaforme). |
subscribeSources | Azione | act | Si iscrive a più fonti in una sola chiamata e restituisce un risultato per fonte. |
unsubscribeSource | Azione | act | Smette di seguire una fonte. Gli elementi già raccolti restano nel corpus. |
setHomeDashboard | Azione | act | Imposta una board salvata come home del workspace. |
upsertSignalRule | Azione | act | Crea o aggiorna una regola di segnale di persistenza: scatta quando un elemento resta online più a lungo della soglia. |
upsertQuestionRule | Azione | act | Crea o aggiorna una domanda permanente: una frase in linguaggio naturale che Jev pone a ogni nuovo elemento delle fonti del workspace. La soglia di probabilità genera il segnale. |
startInvestigation | Azione | act | Mette in coda un'indagine Edge in background per questo workspace (owner o admin). |
startHunt | Azione | act | Avvia una ricerca: trova persone che soddisfano criteri verificabili, con ogni criterio provato da una fonte pubblica datata. I criteri sensibili sono rifiutati, non viene restituito alcun recapito. Viene eseguita in background e consuma i crediti del mese; owner o admin. |
buildAdAudit | Scrittura | write | Audit retroattivo delle campagne di 1-6 inserzionisti già raccolti, su N mesi: una tabella del workspace (inserzionista, mese, nuove inserzioni, interruzioni, librerie, paesi, esigenze lette, aumento di ritmo) e le cifre di un riepilogo citato. Nessun credito. |
findCreatorSponsors | Azione | act, write, explore | Chi paga i creator YouTube in una nicchia: ricerca di video recenti, sponsor dedotti da ciascun video, una tabella del workspace «Sponsor · nicchia». Consuma crediti; conferma nella chat, owner o admin. |
importAdHistory | Azione | act, write, explore | Importa la cronologia Google di una raccolta di un inserzionista: fino a 20 pagine (circa 800 inserzioni dal 2021) per datare le campagne passate. Consuma crediti; conferma nella chat, owner o admin. |
startAdCollection | Azione | act, write, explore | Avvia una raccolta di inserzioni su un inserzionista (nome o dominio) o su una parola chiave: legge Meta, TikTok, Google e LinkedIn, porta ogni inserzione nello stesso formato, poi legge l'angolo, l'offerta, il pubblico e il tono. Consuma crediti; conferma nella chat, owner o admin. |