# Ferramentas

> Chame as ferramentas dos agentes uma a uma, com seus scopes e entradas.

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

Os agentes do Piqline trabalham com ferramentas: ler o corpus, buscar ao vivo, escrever, agir. A API expõe cada uma delas na mesma forma. 92 ferramentas são chamáveis; o [catálogo](#catalogo) as lista com seus scopes, e a [referência](/pt/docs/api/reference) descreve os parâmetros de cada uma, com exemplos de chamada.

## Listar as ferramentas

```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` aceita `all` (o padrão), `piqline`, `requete`, `facebook`, `linkedin`, `upwork` ou `onboarding`. Cada ferramenta da lista traz:

| Campo | Significado |
| --- | --- |
| `name` | o nome da ferramenta, como você a chama |
| `description` | o que a ferramenta faz, em inglês, como o agente a lê |
| `agents` | os agentes que têm a ferramenta |
| `requires` | os scopes exigidos |
| `callable` | `true` se a sua chave pode chamá-la |
| `missing_scopes` | scopes que a chave não tem |
| `confirmation_in_chat` | `true` se o chat pede confirmação antes de executar a ferramenta |
| `read_only` | `true` se a ferramenta não altera nada |
| `input_schema` | JSON Schema da entrada |

As ferramentas que a sua chave não pode chamar continuam na lista, com `callable: false` e `missing_scopes`. `GET /api/v1/tools/{nom}` devolve a mesma entrada para uma única ferramenta, sem `confirmation_in_chat` nem `read_only`.

## Chamar uma ferramenta

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

O corpo JSON é a entrada da ferramenta, como `input_schema` a descreve. Uma ferramenta sem entrada aceita um corpo vazio.

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

A resposta traz o nome da ferramenta e sua saída, a mesma saída que o agente lê:

```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` é a data de exibição do item. `getItem` também devolve `detectedAt` (visto pela primeira vez pelo Piqline), `lastSeenAt` (visto pela última vez) e `publishedAt`.

Um erro volta como `application/problem+json`: veja [Erros](/pt/docs/api/errors).

## Quem pode chamar o quê

- **O papel do criador limita a chave.** Uma ferramenta que esse papel não abre responde `403 forbidden`. As ferramentas de escrita, as de ação e o agente `onboarding` são reservados a owners e admins.
- **Os cartões do chat não existem na API.** `askUser`, `proposeSources`, `proposeBoard` e semelhantes são exibidos a uma pessoa e não executam nada: respondem `404 not_found`. Para obter esse diálogo, execute um [agente](/pt/docs/api/agents).
- **As ferramentas de ação não esperam confirmação.** O chat a pede. Uma chamada direta com o scope `act` é executada na hora.
- **As leituras ao vivo consomem créditos.** As ferramentas do scope `explore` debitam créditos do limite mensal do workspace.

## Catálogo

### Ler o corpus e o workspace

Ferramentas do agente Piqline. Elas leem o que o workspace já coletou: sem consumo de créditos, nada é gravado.

| Ferramenta | Tipo | Scopes | Função |
| --- | --- | --- | --- |
| [`getCoverageStats`](/pt/docs/api/reference/corpus#getcoveragestats) | Leitura | `read` | Volumes e saúde da coleta: totais, divisão por plataforma e por tipo, séries de ingestão na janela de análise (`1h`, `24h`, `7d` ou `30d`). |
| [`listSources`](/pt/docs/api/reference/corpus#listsources) | Leitura | `read` | Fontes que o workspace acompanha, com número de itens, saúde e última leitura. |
| [`searchItems`](/pt/docs/api/reference/corpus#searchitems) | Leitura | `read` | Busca itens (posts, vídeos, artigos, anúncios, vagas) com filtros: texto, plataforma, tipo, fonte. Sem filtro, devolve os mais recentes (40 no máximo). |
| [`getItem`](/pt/docs/api/reference/corpus#getitem) | Leitura | `read` | Detalhe de um item: texto, transcrição, OCR, temas detectados, itens próximos em significado e suas datas de observação. |
| [`searchPassages`](/pt/docs/api/reference/corpus#searchpassages) | Leitura | `read` | Busca por significado em documentos longos (PDFs lidos pelo Motor): as passagens mais próximas de uma pergunta, com o item, a página e o título da seção. |
| [`citeItem`](/pt/docs/api/reference/corpus#citeitem) | Leitura | `read` | Verifica se uma passagem aparece palavra por palavra em um item e devolve um número de citação; caso contrário, a passagem mais próxima. Base do modo Citações do chat. |
| [`drawDiagram`](/pt/docs/api/reference/corpus#drawdiagram) | Leitura | `read` | Desenha a resposta como um diagrama SVG (linha do tempo, matriz, fluxo, árvore…): cores por papel do tema, SVG sanitizado antes da exibição. Base do modo Diagrama do chat. |
| [`createCanvas`](/pt/docs/api/reference/corpus#createcanvas) | Leitura | `read` | Compila um canvas (um arquivo TSX que só importa o SDK piqline/canvas) e devolve código pronto para exibir, ou o erro a corrigir. Base dos modos Canvas e Relatório do chat. |
| [`getTopics`](/pt/docs/api/reference/corpus#gettopics) | Leitura | `read` | Temas detectados com sua parcela de voz e histórias (o mesmo assunto visto em várias fontes). |
| [`getSignals`](/pt/docs/api/reference/corpus#getsignals) | Leitura | `read` | Sinais abertos, disparados pelas regras de persistência do workspace, com seu prazo e status. |
| [`listWorkspaceTables`](/pt/docs/api/reference/corpus#listworkspacetables) | Leitura | `read` | Tabelas já criadas no workspace: nome, comentário, número de colunas e linhas, e se a tabela se preenche sozinha. |
| [`getWorkspaceTable`](/pt/docs/api/reference/corpus#getworkspacetable) | Leitura | `read` | Uma tabela do workspace em JSON: esquema, colunas e linhas. Serve de base ou de alimentação para um site, um app ou um agente (scope read). |
| [`listBookmarks`](/pt/docs/api/reference/corpus#listbookmarks) | Leitura | `read` | Favoritos e pastas do cofre do workspace: título, tipo, pasta, status, admissão. Filtro opcional por palavra, status ou tipo. |
| [`listEntities`](/pt/docs/api/reference/corpus#listentities) | Leitura | `read` | Entidades acompanhadas (empresas, marcas, contas públicas) e itens vinculados no período. |
| [`listWatchContracts`](/pt/docs/api/reference/corpus#listwatchcontracts) | Leitura | `read` | Contratos de monitoramento definidos nas fontes: intenção, termos mantidos e excluídos, evento. |
| [`checkInvestigation`](/pt/docs/api/reference/corpus#checkinvestigation) | Leitura | `read` | Status da última investigação Edge, ou de uma específica: pendente, em execução, concluída com seus candidatos, ou falha. |
| [`checkHunt`](/pt/docs/api/reference/corpus#checkhunt) | Leitura | `read` | Status da última busca, ou de uma específica: etapa, pessoas encontradas com o veredito do código e o seu, e para cada critério seu status e sua prova pública datada (URL, data, trecho). Nunca dados de contato. |
| [`planSourcePack`](/pt/docs/api/reference/corpus#plansourcepack) | Leitura | `read` | Propõe um conjunto coerente de fontes a acompanhar para um objetivo. Não cria nada. |
| [`listWidgets`](/pt/docs/api/reference/corpus#listwidgets) | Leitura | `read` | Widgets que podem entrar em um board deste workspace, classificados para a pessoa, com seus motivos. |
| [`getAdvertiserCampaigns`](/pt/docs/api/reference/corpus#getadvertisercampaigns) | Leitura | `read` | Dossiê de anúncios de um anunciante a partir das coletas do workspace: anúncios, ativos, datas, bibliotecas, países, necessidades lidas, novos anúncios por mês e aumentos de ritmo, últimos anúncios, sinais. Nunca uma pessoa. Sem créditos. |
| [`listAdSignals`](/pt/docs/api/reference/corpus#listadsignals) | Leitura | `read` | Sinais de anúncios do workspace, calculados a cada hora: campanha iniciada ou encerrada, aumento de ritmo, novo país, nova plataforma, contratação paga, promoção, lançamento, novo anunciante. Sem créditos. |
| [`listCollectedAds`](/pt/docs/api/reference/corpus#listcollectedads) | Leitura | `read` | Coletas de anúncios do workspace (Meta, TikTok, Google, LinkedIn), já lidas: a lista ou, com o nome de uma coleta, suas divisões (ângulos, ofertas, tons, formatos), seu ritmo, seus anúncios mais duradouros e seus anúncios filtrados por biblioteca, status, ângulo ou palavra. Sem créditos. |

### Explorar a web e os registros ao vivo

Leituras ao vivo na web e em redes públicas. Consomem créditos; nada é armazenado no workspace.

| Ferramenta | Tipo | Scopes | Função |
| --- | --- | --- | --- |
| [`readPage`](/pt/docs/api/reference/direct#readpage) | Leitura ao vivo | `explore` | Lê uma página web pública: título, texto principal (6.000 caracteres), feeds descobertos e 30 links. |
| [`searchWeb`](/pt/docs/api/reference/direct#searchweb) | Leitura ao vivo | `explore` | Pesquisa na web pública para encontrar URLs candidatas. |
| [`browserRead`](/pt/docs/api/reference/direct#browserread) | Leitura ao vivo | `explore` | Lê uma página dinâmica ou protegida com um navegador forçado. Mesma forma que `readPage`. |
| [`waybackHistory`](/pt/docs/api/reference/direct#waybackhistory) | Leitura ao vivo | `explore` | Capturas da Wayback Machine de uma URL: primeira captura e capturas recentes. |
| [`registryLookup`](/pt/docs/api/reference/direct#registrylookup) | Leitura ao vivo | `explore` | Consulta uma empresa em um registro público: Sirene (França), EDGAR (Estados Unidos), Companies House (Reino Unido) ou OpenCorporates. |
| [`socialCatalog`](/pt/docs/api/reference/direct#socialcatalog) | Leitura ao vivo | `explore` | Lista os endpoints de leitura das redes sociais (40 no máximo), filtráveis por plataforma. |
| [`socialCall`](/pt/docs/api/reference/direct#socialcall) | Leitura ao vivo | `explore` | Chama um endpoint de leitura de rede social e devolve até 20 itens compactos. |
| [`previewSource`](/pt/docs/api/reference/direct#previewsource) | Leitura ao vivo | `explore` | Amostra ao vivo (5 a 10 itens) de uma fonte, antes de assiná-la. |
| [`whoSaidItFirst`](/pt/docs/api/reference/direct#whosaiditfirst) | Leitura ao vivo | `explore` | Quem publicou uma informação primeiro na web, página por página, e quando as suas fontes a viram. Parte de um assunto ou de um item; mantida como linha do tempo privada do workspace. |

### Facebook

Ferramentas do agente Facebook: anúncios do Marketplace e grupos públicos, lidos ao vivo.

| Ferramenta | Tipo | Scopes | Função |
| --- | --- | --- | --- |
| [`findMarketplaceLocation`](/pt/docs/api/reference/facebook#findmarketplacelocation) | Leitura ao vivo | `explore` | Converte o nome de uma cidade ou região em coordenadas do Marketplace. |
| [`searchMarketplace`](/pt/docs/api/reference/facebook#searchmarketplace) | Leitura ao vivo | `explore` | Pesquisa anúncios públicos do Marketplace por palavra-chave em torno de um local (cidade ou coordenadas), em no máximo 3 páginas. |
| [`getMarketplaceListing`](/pt/docs/api/reference/facebook#getmarketplacelisting) | Leitura ao vivo | `explore` | Detalhe de um anúncio: descrição, atributos, fotos, entrega, data exata quando o Facebook a fornece. |
| [`getMarketplaceListings`](/pt/docs/api/reference/facebook#getmarketplacelistings) | Leitura ao vivo | `explore` | Detalhe de 2 a 6 anúncios de uma vez, em uma tabela comparativa. |
| [`getFacebookGroup`](/pt/docs/api/reference/facebook#getfacebookgroup) | Leitura ao vivo | `explore` | Perfil público de um grupo: privacidade, tamanho, atividade, categorias, regras. |
| [`getFacebookGroupPosts`](/pt/docs/api/reference/facebook#getfacebookgroupposts) | Leitura ao vivo | `explore` | Posts de um grupo público, em páginas de 3 (6 páginas no máximo). |
| [`getFacebookPost`](/pt/docs/api/reference/facebook#getfacebookpost) | Leitura ao vivo | `explore` | Detalhe de um post público ou reel: texto, autor, data, reações, visualizações. |
| [`getFacebookPostComments`](/pt/docs/api/reference/facebook#getfacebookpostcomments) | Leitura ao vivo | `explore` | Comentários de um post público, filtráveis por palavras-chave (3 páginas no máximo). |

### LinkedIn

Ferramentas do agente LinkedIn: posts públicos, páginas de empresas e anúncios, lidos ao vivo. Os dados de contato nunca são lidos.

| Ferramenta | Tipo | Scopes | Função |
| --- | --- | --- | --- |
| [`searchLinkedinPosts`](/pt/docs/api/reference/linkedin#searchlinkedinposts) | Leitura ao vivo | `explore` | Pesquisa posts públicos por palavras-chave, em tempo real, dos mais novos aos mais antigos (uma leitura parcial é sinalizada no resultado), com o cargo e o papel do autor quando o post é de contratação, e sinais calculados pelo código: contratação, captação de recursos, lançamento, expansão, reorganização, disponibilidade, saída. |
| [`probeLinkedinWatch`](/pt/docs/api/reference/linkedin#probelinkedinwatch) | Leitura ao vivo | `explore` | Testa de 1 a 3 variantes de consulta antes de assinar um monitoramento do LinkedIn e devolve o ticket de investigação a anexar à assinatura. |
| [`getLinkedinPost`](/pt/docs/api/reference/linkedin#getlinkedinpost) | Leitura ao vivo | `explore` | Lê um post ou artigo público: texto, autor, data, reações, comentários com seus sinais. |
| [`getLinkedinPostTranscript`](/pt/docs/api/reference/linkedin#getlinkedinposttranscript) | Leitura ao vivo | `explore` | Transcrição do vídeo de um post público, cobrada apenas se existir. |
| [`getLinkedinCompany`](/pt/docs/api/reference/linkedin#getlinkedincompany) | Leitura ao vivo | `explore` | Página pública de uma empresa: descrição, número de funcionários, setor, financiamento, últimos posts com seus sinais. |
| [`getLinkedinCompanyPosts`](/pt/docs/api/reference/linkedin#getlinkedincompanyposts) | Leitura ao vivo | `explore` | Posts mais antigos da página de uma empresa, com um resumo dos sinais (contratação, financiamento, lançamentos). |
| [`searchLinkedinAds`](/pt/docs/api/reference/linkedin#searchlinkedinads) | Leitura ao vivo | `explore` | Pesquisa a biblioteca de anúncios: anunciante, formato, datas, impressões. |
| [`getLinkedinAd`](/pt/docs/api/reference/linkedin#getlinkedinad) | Leitura ao vivo | `explore` | Detalhe de um anúncio da biblioteca: segmentação, impressões por país, duração. |
| [`matchLinkedinPosts`](/pt/docs/api/reference/linkedin#matchlinkedinposts) | Leitura ao vivo | `explore` | Cruza pessoas disponíveis com oportunidades vindas de posts públicos (duas pesquisas). |
| [`getLinkedinProfile`](/pt/docs/api/reference/linkedin#getlinkedinprofile) | Leitura ao vivo | `explore` | Leitura limitada de um perfil público `/in/`, somente a partir de um post público que nomeia a pessoa. Reservada aos workspaces que ativaram esta opção. |

### Upwork

Ferramentas do agente Upwork: vagas públicas lidas, pontuadas e respondidas a partir da base de conhecimento do workspace. Nada é enviado ao Upwork.

| Ferramenta | Tipo | Scopes | Função |
| --- | --- | --- | --- |
| [`searchUpworkJobs`](/pt/docs/api/reference/upwork#searchupworkjobs) | Leitura ao vivo | `explore` | Lê uma página de resultados públicos (cerca de dez vagas) e pontua cada vaga em relação à base de conhecimento. As vagas são adicionadas ao pipeline do workspace. |
| [`getUpworkJob`](/pt/docs/api/reference/upwork#getupworkjob) | Leitura ao vivo | `explore` | Lê uma vaga: descrição, habilidades, orçamento, atividade, cliente. Adiciona um instantâneo datado ao pipeline. |
| [`scoreUpworkJobs`](/pt/docs/api/reference/upwork#scoreupworkjobs) | Escrita | `write` | Pontua de novo as vagas do pipeline após uma mudança na base de conhecimento. Nenhuma página é lida. |
| [`getUpworkRadar`](/pt/docs/api/reference/upwork#getupworkradar) | Leitura ao vivo | `explore` | Radar de mercado: volume por dia, quartis de valor por hora e de orçamento, habilidades, concorrência, países dos clientes. |
| [`listUpworkLeads`](/pt/docs/api/reference/upwork#listupworkleads) | Leitura | `read` | Pipeline do Upwork: contagem por status, melhores vagas primeiro, desfecho de cada uma. |
| [`updateUpworkLead`](/pt/docs/api/reference/upwork#updateupworklead) | Escrita | `write` | Altera o status de uma vaga do pipeline (enviada, resposta, entrevista, ganha, perdida, ignorada) e guarda uma nota. |
| [`getUpworkKnowledge`](/pt/docs/api/reference/upwork#getupworkknowledge) | Leitura | `read` | Base de conhecimento Upwork do workspace: serviços, ferramentas, projetos a evitar, valores mínimos, estudos de caso, tom, assinatura. |
| [`updateUpworkKnowledge`](/pt/docs/api/reference/upwork#updateupworkknowledge) | Escrita | `write` | Atualiza a base de conhecimento. As listas que você envia substituem as listas armazenadas. |
| [`listUpworkTemplates`](/pt/docs/api/reference/upwork#listupworktemplates) | Leitura | `read` | Modelos de proposta salvos, com seus slots e suas regras de perguntas. |
| [`upsertUpworkTemplate`](/pt/docs/api/reference/upwork#upsertupworktemplate) | Escrita | `write` | Cria ou atualiza um modelo de proposta. |
| [`draftUpworkProposal`](/pt/docs/api/reference/upwork#draftupworkproposal) | Escrita | `write`, `explore` | Redige uma proposta para uma vaga a partir de um modelo. Você mesmo cola o texto no Upwork. |
| [`listUpworkCampaigns`](/pt/docs/api/reference/upwork#listupworkcampaigns) | Leitura | `read` | Campanhas salvas: pesquisa, pontuação mínima, status, última atualização, saúde das fontes. |
| [`saveUpworkCampaign`](/pt/docs/api/reference/upwork#saveupworkcampaign) | Escrita | `write` | Cria ou atualiza uma campanha: nome, pesquisa, pontuação mínima, modelo. |
| [`simulateUpworkCampaign`](/pt/docs/api/reference/upwork#simulateupworkcampaign) | Leitura ao vivo | `explore` | Simula uma campanha em vagas reais antes de acompanhá-la. Nada é salvo. |
| [`followUpworkCampaign`](/pt/docs/api/reference/upwork#followupworkcampaign) | Ação | `act` | Pede ao Motor que acompanhe uma campanha salva, no ritmo de coleta dela. |
| [`pauseUpworkCampaign`](/pt/docs/api/reference/upwork#pauseupworkcampaign) | Ação | `act` | Faz o Motor parar de acompanhar uma campanha. As vagas já vistas permanecem no pipeline. |
| [`refreshUpworkCampaigns`](/pt/docs/api/reference/upwork#refreshupworkcampaigns) | Escrita | `write`, `explore` | Atualiza as campanhas acompanhadas: mescla as vagas coletadas pelo Motor, lê de novo a primeira página ao vivo, pontua as novas vagas. |
| [`checkUpworkOutcomes`](/pt/docs/api/reference/upwork#checkupworkoutcomes) | Escrita | `write`, `explore` | Lê de novo as páginas das candidaturas em andamento para datar o desfecho: encerrada, entrevistas iniciadas, sem resposta. |
| [`syncUpworkReplies`](/pt/docs/api/reference/upwork#syncupworkreplies) | Escrita | `write` | Lê os e-mails de notificação do Upwork nas caixas de entrada conectadas do criador da chave e avança o status das vagas do pipeline. |

### Escrever no workspace

Ferramentas do agente Piqline que criam ou alteram objetos do workspace. Exigem o scope `write`.

| Ferramenta | Tipo | Scopes | Função |
| --- | --- | --- | --- |
| [`updateWorkspaceProfile`](/pt/docs/api/reference/write#updateworkspaceprofile) | Escrita | `write` | Salva o perfil de necessidades do workspace: objetivos, assuntos, entidades, idiomas, regiões, nível, ritmo. |
| [`followEntity`](/pt/docs/api/reference/write#followentity) | Escrita | `write` | Acompanha uma empresa, uma marca ou uma conta pública (nunca uma pessoa física) para vincular seus itens e menções. |
| [`unfollowEntity`](/pt/docs/api/reference/write#unfollowentity) | Exclusão | `write` | Para de acompanhar uma entidade. Os vínculos existentes permanecem. |
| [`saveBookmark`](/pt/docs/api/reference/write#savebookmark) | Escrita | `write` | Salva um favorito no cofre do workspace. Uma URL http(s) entra na fila para leitura, arquivamento e vetorização. |
| [`setWatchContract`](/pt/docs/api/reference/write#setwatchcontract) | Escrita | `write` | Define um contrato de monitoramento em uma fonte: a página de monitoramento mostra então apenas os itens correspondentes. Determinístico, sem modelo. |
| [`removeWatchContract`](/pt/docs/api/reference/write#removewatchcontract) | Exclusão | `write` | Remove o contrato de monitoramento de uma fonte: todos os itens voltam a aparecer. |
| [`initReaderInterview`](/pt/docs/api/reference/write#initreaderinterview) | Escrita | `write` | Salva as duas respostas da entrevista de leitura (o essencial ou o detalhe, intenção principal) no perfil de leitura. |
| [`applyBoardChange`](/pt/docs/api/reference/write#applyboardchange) | Escrita | `write` | Aplica a um board alterações que já foram aprovadas. |
| [`buildDashboard`](/pt/docs/api/reference/write#builddashboard) | Escrita | `write` | Monta um board diretamente, sem passar pelo seletor de widgets. |
| [`saveWorkspaceTable`](/pt/docs/api/reference/write#saveworkspacetable) | Escrita | `write` | Cria uma tabela do workspace, preenchida com as colunas úteis. |
| [`writeFromWatch`](/pt/docs/api/reference/write#writefromwatch) | Escrita | `write` | Escreve um texto a partir dos itens dos monitoramentos do workspace (artigo, post de LinkedIn, thread do X, legenda de Instagram, newsletter, roteiro de vídeo, comunicado de imprensa, artigo SEO, e-mail, resumo), em nove idiomas, com cada fato citado [n] até a sua fonte; o texto entra nos rascunhos. Consome alguns créditos. |
| [`setTableFeed`](/pt/docs/api/reference/write#settablefeed) | Ação | `act`, `write` | Dá vida a uma tabela: assim que um item do corpus corresponde à regra, ele é adicionado, após confirmação. status=paused interrompe o preenchimento. |

### Agir sobre fontes e regras

Ferramentas de ação do agente Piqline. No chat, cada uma pede confirmação. Pela API, uma chamada direta com o scope `act` conta como confirmação: só chame essas ferramentas depois que a pessoa envolvida concordar.

| Ferramenta | Tipo | Scopes | Função |
| --- | --- | --- | --- |
| [`subscribeSource`](/pt/docs/api/reference/act#subscribesource) | Ação | `act` | Assina uma nova fonte. Inicia uma coleta real (tarefas de leitura, cotas das plataformas). |
| [`subscribeSources`](/pt/docs/api/reference/act#subscribesources) | Ação | `act` | Assina várias fontes em uma única chamada e devolve um resultado por fonte. |
| [`unsubscribeSource`](/pt/docs/api/reference/act#unsubscribesource) | Ação | `act` | Para de acompanhar uma fonte. Os itens já coletados permanecem no corpus. |
| [`setHomeDashboard`](/pt/docs/api/reference/act#sethomedashboard) | Ação | `act` | Define um board salvo como a página inicial do workspace. |
| [`upsertSignalRule`](/pt/docs/api/reference/act#upsertsignalrule) | Ação | `act` | Cria ou atualiza uma regra de sinal de persistência: ela dispara quando um item permanece no ar por mais tempo que o limite. |
| [`upsertQuestionRule`](/pt/docs/api/reference/act#upsertquestionrule) | Ação | `act` | Cria ou atualiza uma pergunta permanente: uma frase em linguagem natural que o Jev faz a cada novo item das fontes do workspace. O limite de probabilidade gera o sinal. |
| [`startInvestigation`](/pt/docs/api/reference/act#startinvestigation) | Ação | `act` | Coloca na fila uma investigação Edge em segundo plano para este workspace (owner ou admin). |
| [`startHunt`](/pt/docs/api/reference/act#starthunt) | Ação | `act` | Inicia uma busca: encontrar pessoas que atendam a critérios verificáveis, cada critério comprovado por uma fonte pública datada. Critérios sensíveis são recusados, nenhum dado de contato é devolvido. Roda em segundo plano e consome os créditos do mês; owner ou admin. |
| [`buildAdAudit`](/pt/docs/api/reference/act#buildadaudit) | Escrita | `write` | Auditoria retroativa das campanhas de 1 a 6 anunciantes já coletados, ao longo de N meses: uma tabela do workspace (anunciante, mês, novos anúncios, encerramentos, bibliotecas, países, necessidades lidas, aumento de ritmo) e os números de um resumo citado. Sem créditos. |
| [`findCreatorSponsors`](/pt/docs/api/reference/act#findcreatorsponsors) | Ação | `act`, `write`, `explore` | Quem paga criadores do YouTube em um nicho: pesquisa de vídeos recentes, patrocinadores deduzidos de cada vídeo, uma tabela do workspace “Patrocinadores · nicho”. Consome créditos; confirmação no chat, owner ou admin. |
| [`importAdHistory`](/pt/docs/api/reference/act#importadhistory) | Ação | `act`, `write`, `explore` | Importa o histórico do Google de uma coleta de anunciante: até 20 páginas (cerca de 800 anúncios desde 2021) para datar campanhas passadas. Consome créditos; confirmação no chat, owner ou admin. |
| [`startAdCollection`](/pt/docs/api/reference/act#startadcollection) | Ação | `act`, `write`, `explore` | Inicia uma coleta de anúncios de um anunciante (nome ou domínio) ou de uma palavra-chave: lê Meta, TikTok, Google e LinkedIn, coloca cada anúncio no mesmo formato e lê o ângulo, a oferta, o público e o tom. Consome créditos; confirmação no chat, owner ou admin. |
