# Tool

> Chiama uno per uno i tool degli agenti, con i loro scope e i loro input.

Source: https://piqline.com/it/docs/api/tools

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](#catalogo) li elenca con i loro scope, e il [riferimento](/it/docs/api/reference) descrive i parametri di ciascuno, con esempi di chiamata.

## Elencare i tool

```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` 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

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

Il corpo JSON è l'input del tool, come lo descrive `input_schema`. Un tool senza input accetta un corpo vuoto.

```bash tab="curl"
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}'
```
```javascript tab="JavaScript"
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();
```
```python tab="Python"
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:

```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` è 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](/it/docs/api/errors).

## 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'agente `onboarding` sono riservati a owner e admin.
- **Le card della chat non esistono nell'API.** `askUser`, `proposeSources`, `proposeBoard` e simili vengono mostrati a una persona e non eseguono nulla: rispondono `404 not_found`. Per ottenere quel dialogo, esegui un [agente](/it/docs/api/agents).
- **I tool di azione non aspettano conferma.** La chat la chiede. Una chiamata diretta con lo scope `act` viene eseguita subito.
- **Le letture in diretta consumano crediti.** I tool dello scope `explore` prelevano 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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#listsources) | Lettura | `read` | Fonti seguite dal workspace, con numero di elementi, stato e ultima lettura. |
| [`searchItems`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#getitem) | Lettura | `read` | Dettaglio di un elemento: testo, trascrizione, OCR, argomenti rilevati, elementi vicini per significato e date di osservazione. |
| [`searchPassages`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#gettopics) | Lettura | `read` | Argomenti rilevati con la loro quota di voce e le storie (lo stesso soggetto visto in più fonti). |
| [`getSignals`](/it/docs/api/reference/corpus#getsignals) | Lettura | `read` | Segnali aperti, attivati dalle regole di persistenza del workspace, con il loro anticipo e il loro stato. |
| [`listWorkspaceTables`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#listbookmarks) | Lettura | `read` | Segnalibri e cartelle del vault del workspace: titolo, tipo, cartella, stato, ammissione. Filtro facoltativo per parola, stato o tipo. |
| [`listEntities`](/it/docs/api/reference/corpus#listentities) | Lettura | `read` | Entità seguite (aziende, marchi, account pubblici) ed elementi collegati nel periodo. |
| [`listWatchContracts`](/it/docs/api/reference/corpus#listwatchcontracts) | Lettura | `read` | Contratti di monitoraggio impostati sulle fonti: intento, termini mantenuti ed esclusi, evento. |
| [`checkInvestigation`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#plansourcepack) | Lettura | `read` | Propone un insieme coerente di fonti da seguire per un obiettivo. Non crea nulla. |
| [`listWidgets`](/it/docs/api/reference/corpus#listwidgets) | Lettura | `read` | Widget che possono andare su una board di questo workspace, ordinati per la persona, con le loro motivazioni. |
| [`getAdvertiserCampaigns`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/corpus#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`](/it/docs/api/reference/direct#readpage) | Lettura in diretta | `explore` | Legge una pagina web pubblica: titolo, testo principale (6.000 caratteri), feed individuati e 30 link. |
| [`searchWeb`](/it/docs/api/reference/direct#searchweb) | Lettura in diretta | `explore` | Cerca nel web pubblico per trovare URL candidati. |
| [`browserRead`](/it/docs/api/reference/direct#browserread) | Lettura in diretta | `explore` | Legge una pagina dinamica o protetta con un browser forzato. Stessa forma di `readPage`. |
| [`waybackHistory`](/it/docs/api/reference/direct#waybackhistory) | Lettura in diretta | `explore` | Catture della Wayback Machine di un URL: prima cattura e catture recenti. |
| [`registryLookup`](/it/docs/api/reference/direct#registrylookup) | Lettura in diretta | `explore` | Cerca un'azienda in un registro pubblico: Sirene (Francia), EDGAR (Stati Uniti), Companies House (Regno Unito) oppure OpenCorporates. |
| [`socialCatalog`](/it/docs/api/reference/direct#socialcatalog) | Lettura in diretta | `explore` | Elenca gli endpoint di lettura dei social network (al massimo 40), filtrabili per piattaforma. |
| [`socialCall`](/it/docs/api/reference/direct#socialcall) | Lettura in diretta | `explore` | Chiama un endpoint di lettura di un social network e restituisce fino a 20 elementi compatti. |
| [`previewSource`](/it/docs/api/reference/direct#previewsource) | Lettura in diretta | `explore` | Campione in diretta (da 5 a 10 elementi) di una fonte, prima di iscriversi. |
| [`whoSaidItFirst`](/it/docs/api/reference/direct#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`](/it/docs/api/reference/facebook#findmarketplacelocation) | Lettura in diretta | `explore` | Trasforma il nome di una città o di un'area in coordinate di Marketplace. |
| [`searchMarketplace`](/it/docs/api/reference/facebook#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`](/it/docs/api/reference/facebook#getmarketplacelisting) | Lettura in diretta | `explore` | Dettaglio di un annuncio: descrizione, attributi, foto, consegna, data esatta quando Facebook la fornisce. |
| [`getMarketplaceListings`](/it/docs/api/reference/facebook#getmarketplacelistings) | Lettura in diretta | `explore` | Dettaglio di 2-6 annunci insieme, come tabella di confronto. |
| [`getFacebookGroup`](/it/docs/api/reference/facebook#getfacebookgroup) | Lettura in diretta | `explore` | Profilo pubblico di un gruppo: privacy, dimensione, attività, categorie, regole. |
| [`getFacebookGroupPosts`](/it/docs/api/reference/facebook#getfacebookgroupposts) | Lettura in diretta | `explore` | Post di un gruppo pubblico, in pagine da 3 (al massimo 6 pagine). |
| [`getFacebookPost`](/it/docs/api/reference/facebook#getfacebookpost) | Lettura in diretta | `explore` | Dettaglio di un post o reel pubblico: testo, autore, data, reazioni, visualizzazioni. |
| [`getFacebookPostComments`](/it/docs/api/reference/facebook#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`](/it/docs/api/reference/linkedin#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`](/it/docs/api/reference/linkedin#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`](/it/docs/api/reference/linkedin#getlinkedinpost) | Lettura in diretta | `explore` | Legge un post o un articolo pubblico: testo, autore, data, reazioni, commenti con i loro segnali. |
| [`getLinkedinPostTranscript`](/it/docs/api/reference/linkedin#getlinkedinposttranscript) | Lettura in diretta | `explore` | Trascrizione del video di un post pubblico, fatturata solo se esiste. |
| [`getLinkedinCompany`](/it/docs/api/reference/linkedin#getlinkedincompany) | Lettura in diretta | `explore` | Pagina aziendale pubblica: descrizione, organico, settore, finanziamenti, ultimi post con i loro segnali. |
| [`getLinkedinCompanyPosts`](/it/docs/api/reference/linkedin#getlinkedincompanyposts) | Lettura in diretta | `explore` | Post meno recenti di una pagina aziendale, con un riepilogo dei segnali (assunzioni, finanziamenti, lanci). |
| [`searchLinkedinAds`](/it/docs/api/reference/linkedin#searchlinkedinads) | Lettura in diretta | `explore` | Cerca nella libreria delle inserzioni: inserzionista, formato, date, impression. |
| [`getLinkedinAd`](/it/docs/api/reference/linkedin#getlinkedinad) | Lettura in diretta | `explore` | Dettaglio di un'inserzione della libreria: targeting, impression per paese, durata. |
| [`matchLinkedinPosts`](/it/docs/api/reference/linkedin#matchlinkedinposts) | Lettura in diretta | `explore` | Abbina persone disponibili a opportunità a partire da post pubblici (due ricerche). |
| [`getLinkedinProfile`](/it/docs/api/reference/linkedin#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`](/it/docs/api/reference/upwork#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`](/it/docs/api/reference/upwork#getupworkjob) | Lettura in diretta | `explore` | Legge un'offerta: descrizione, competenze, budget, attività, cliente. Aggiunge alla pipeline un'istantanea datata. |
| [`scoreUpworkJobs`](/it/docs/api/reference/upwork#scoreupworkjobs) | Scrittura | `write` | Rivaluta le offerte della pipeline dopo una modifica della knowledge base. Nessuna pagina viene letta. |
| [`getUpworkRadar`](/it/docs/api/reference/upwork#getupworkradar) | Lettura in diretta | `explore` | Radar di mercato: volume al giorno, quartili di tariffa e di budget, competenze, concorrenza, paesi dei clienti. |
| [`listUpworkLeads`](/it/docs/api/reference/upwork#listupworkleads) | Lettura | `read` | Pipeline Upwork: conteggio per stato, prima le migliori offerte, esito di ciascuna. |
| [`updateUpworkLead`](/it/docs/api/reference/upwork#updateupworklead) | Scrittura | `write` | Modifica lo stato di un'offerta della pipeline (inviata, risposta, colloquio, vinta, persa, ignorata) e conserva una nota. |
| [`getUpworkKnowledge`](/it/docs/api/reference/upwork#getupworkknowledge) | Lettura | `read` | Knowledge base Upwork del workspace: servizi, strumenti, progetti da evitare, tariffe minime, casi di studio, tono, firma. |
| [`updateUpworkKnowledge`](/it/docs/api/reference/upwork#updateupworkknowledge) | Scrittura | `write` | Aggiorna la knowledge base. Gli elenchi che invii sostituiscono quelli memorizzati. |
| [`listUpworkTemplates`](/it/docs/api/reference/upwork#listupworktemplates) | Lettura | `read` | Modelli di proposta salvati, con i loro slot e le loro regole per le domande. |
| [`upsertUpworkTemplate`](/it/docs/api/reference/upwork#upsertupworktemplate) | Scrittura | `write` | Crea o aggiorna un modello di proposta. |
| [`draftUpworkProposal`](/it/docs/api/reference/upwork#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`](/it/docs/api/reference/upwork#listupworkcampaigns) | Lettura | `read` | Campagne salvate: ricerca, punteggio minimo, stato, ultimo aggiornamento, stato delle fonti. |
| [`saveUpworkCampaign`](/it/docs/api/reference/upwork#saveupworkcampaign) | Scrittura | `write` | Crea o aggiorna una campagna: nome, ricerca, punteggio minimo, modello. |
| [`simulateUpworkCampaign`](/it/docs/api/reference/upwork#simulateupworkcampaign) | Lettura in diretta | `explore` | Simula una campagna su offerte reali prima di seguirla. Nulla viene salvato. |
| [`followUpworkCampaign`](/it/docs/api/reference/upwork#followupworkcampaign) | Azione | `act` | Chiede al Motor di seguire una campagna salvata, al suo ritmo di raccolta. |
| [`pauseUpworkCampaign`](/it/docs/api/reference/upwork#pauseupworkcampaign) | Azione | `act` | Impedisce al Motor di seguire una campagna. Le offerte già viste restano nella pipeline. |
| [`refreshUpworkCampaigns`](/it/docs/api/reference/upwork#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`](/it/docs/api/reference/upwork#checkupworkoutcomes) | Scrittura | `write`, `explore` | Rilegge le pagine delle candidature in corso per datare il loro esito: chiusa, colloqui avviati, nessuna risposta. |
| [`syncUpworkReplies`](/it/docs/api/reference/upwork#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`](/it/docs/api/reference/write#updateworkspaceprofile) | Scrittura | `write` | Salva il profilo di esigenza del workspace: obiettivi, argomenti, entità, lingue, regioni, livello, ritmo. |
| [`followEntity`](/it/docs/api/reference/write#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`](/it/docs/api/reference/write#unfollowentity) | Eliminazione | `write` | Smette di seguire un'entità. I suoi collegamenti esistenti restano. |
| [`saveBookmark`](/it/docs/api/reference/write#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`](/it/docs/api/reference/write#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`](/it/docs/api/reference/write#removewatchcontract) | Eliminazione | `write` | Rimuove il contratto di monitoraggio di una fonte: tutti gli elementi tornano visibili. |
| [`initReaderInterview`](/it/docs/api/reference/write#initreaderinterview) | Scrittura | `write` | Salva le due risposte dell'intervista di lettura (essenziale o dettaglio, intento principale) nel profilo di lettura. |
| [`applyBoardChange`](/it/docs/api/reference/write#applyboardchange) | Scrittura | `write` | Applica a una board modifiche già approvate. |
| [`buildDashboard`](/it/docs/api/reference/write#builddashboard) | Scrittura | `write` | Costruisce direttamente una board, senza passare dalla selezione dei widget. |
| [`saveWorkspaceTable`](/it/docs/api/reference/write#saveworkspacetable) | Scrittura | `write` | Crea una tabella del workspace, popolata con le colonne utili. |
| [`writeFromWatch`](/it/docs/api/reference/write#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`](/it/docs/api/reference/write#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`](/it/docs/api/reference/act#subscribesource) | Azione | `act` | Si iscrive a una nuova fonte. Avvia una vera raccolta (job di lettura, quote delle piattaforme). |
| [`subscribeSources`](/it/docs/api/reference/act#subscribesources) | Azione | `act` | Si iscrive a più fonti in una sola chiamata e restituisce un risultato per fonte. |
| [`unsubscribeSource`](/it/docs/api/reference/act#unsubscribesource) | Azione | `act` | Smette di seguire una fonte. Gli elementi già raccolti restano nel corpus. |
| [`setHomeDashboard`](/it/docs/api/reference/act#sethomedashboard) | Azione | `act` | Imposta una board salvata come home del workspace. |
| [`upsertSignalRule`](/it/docs/api/reference/act#upsertsignalrule) | Azione | `act` | Crea o aggiorna una regola di segnale di persistenza: scatta quando un elemento resta online più a lungo della soglia. |
| [`upsertQuestionRule`](/it/docs/api/reference/act#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`](/it/docs/api/reference/act#startinvestigation) | Azione | `act` | Mette in coda un'indagine Edge in background per questo workspace (owner o admin). |
| [`startHunt`](/it/docs/api/reference/act#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`](/it/docs/api/reference/act#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`](/it/docs/api/reference/act#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`](/it/docs/api/reference/act#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`](/it/docs/api/reference/act#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. |
