Guias
Ferramentas
Chame as ferramentas dos agentes uma a uma, com seus scopes e entradas.
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 as lista com seus scopes, e a referência descreve os parâmetros de cada uma, com exemplos de chamada.
Listar as ferramentas#
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#
POST https://piqline.com/api/v1/tools/{nom}
Content-Type: application/jsonO corpo JSON é a entrada da ferramenta, como input_schema a descreve. Uma ferramenta sem entrada aceita um corpo vazio.
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()A resposta traz o nome da ferramenta e sua saída, a mesma saída que o agente lê:
{
"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.
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 agenteonboardingsão reservados a owners e admins. - Os cartões do chat não existem na API.
askUser,proposeSources,proposeBoarde semelhantes são exibidos a uma pessoa e não executam nada: respondem404 not_found. Para obter esse diálogo, execute um agente. - 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
exploredebitam 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 | 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 | Leitura | read | Fontes que o workspace acompanha, com número de itens, saúde e última leitura. |
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 | Leitura | read | Detalhe de um item: texto, transcrição, OCR, temas detectados, itens próximos em significado e suas datas de observação. |
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 | 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 | 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 | 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 | Leitura | read | Temas detectados com sua parcela de voz e histórias (o mesmo assunto visto em várias fontes). |
getSignals | Leitura | read | Sinais abertos, disparados pelas regras de persistência do workspace, com seu prazo e status. |
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 | 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 | Leitura | read | Favoritos e pastas do cofre do workspace: título, tipo, pasta, status, admissão. Filtro opcional por palavra, status ou tipo. |
listEntities | Leitura | read | Entidades acompanhadas (empresas, marcas, contas públicas) e itens vinculados no período. |
listWatchContracts | Leitura | read | Contratos de monitoramento definidos nas fontes: intenção, termos mantidos e excluídos, evento. |
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 | 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 | Leitura | read | Propõe um conjunto coerente de fontes a acompanhar para um objetivo. Não cria nada. |
listWidgets | Leitura | read | Widgets que podem entrar em um board deste workspace, classificados para a pessoa, com seus motivos. |
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 | 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 | 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 | Leitura ao vivo | explore | Lê uma página web pública: título, texto principal (6.000 caracteres), feeds descobertos e 30 links. |
searchWeb | Leitura ao vivo | explore | Pesquisa na web pública para encontrar URLs candidatas. |
browserRead | Leitura ao vivo | explore | Lê uma página dinâmica ou protegida com um navegador forçado. Mesma forma que readPage. |
waybackHistory | Leitura ao vivo | explore | Capturas da Wayback Machine de uma URL: primeira captura e capturas recentes. |
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 | Leitura ao vivo | explore | Lista os endpoints de leitura das redes sociais (40 no máximo), filtráveis por plataforma. |
socialCall | Leitura ao vivo | explore | Chama um endpoint de leitura de rede social e devolve até 20 itens compactos. |
previewSource | Leitura ao vivo | explore | Amostra ao vivo (5 a 10 itens) de uma fonte, antes de assiná-la. |
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 | Leitura ao vivo | explore | Converte o nome de uma cidade ou região em coordenadas do Marketplace. |
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 | Leitura ao vivo | explore | Detalhe de um anúncio: descrição, atributos, fotos, entrega, data exata quando o Facebook a fornece. |
getMarketplaceListings | Leitura ao vivo | explore | Detalhe de 2 a 6 anúncios de uma vez, em uma tabela comparativa. |
getFacebookGroup | Leitura ao vivo | explore | Perfil público de um grupo: privacidade, tamanho, atividade, categorias, regras. |
getFacebookGroupPosts | Leitura ao vivo | explore | Posts de um grupo público, em páginas de 3 (6 páginas no máximo). |
getFacebookPost | Leitura ao vivo | explore | Detalhe de um post público ou reel: texto, autor, data, reações, visualizações. |
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 | 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 | 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 | Leitura ao vivo | explore | Lê um post ou artigo público: texto, autor, data, reações, comentários com seus sinais. |
getLinkedinPostTranscript | Leitura ao vivo | explore | Transcrição do vídeo de um post público, cobrada apenas se existir. |
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 | Leitura ao vivo | explore | Posts mais antigos da página de uma empresa, com um resumo dos sinais (contratação, financiamento, lançamentos). |
searchLinkedinAds | Leitura ao vivo | explore | Pesquisa a biblioteca de anúncios: anunciante, formato, datas, impressões. |
getLinkedinAd | Leitura ao vivo | explore | Detalhe de um anúncio da biblioteca: segmentação, impressões por país, duração. |
matchLinkedinPosts | Leitura ao vivo | explore | Cruza pessoas disponíveis com oportunidades vindas de posts públicos (duas pesquisas). |
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 | 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 | Leitura ao vivo | explore | Lê uma vaga: descrição, habilidades, orçamento, atividade, cliente. Adiciona um instantâneo datado ao pipeline. |
scoreUpworkJobs | Escrita | write | Pontua de novo as vagas do pipeline após uma mudança na base de conhecimento. Nenhuma página é lida. |
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 | Leitura | read | Pipeline do Upwork: contagem por status, melhores vagas primeiro, desfecho de cada uma. |
updateUpworkLead | Escrita | write | Altera o status de uma vaga do pipeline (enviada, resposta, entrevista, ganha, perdida, ignorada) e guarda uma nota. |
getUpworkKnowledge | Leitura | read | Base de conhecimento Upwork do workspace: serviços, ferramentas, projetos a evitar, valores mínimos, estudos de caso, tom, assinatura. |
updateUpworkKnowledge | Escrita | write | Atualiza a base de conhecimento. As listas que você envia substituem as listas armazenadas. |
listUpworkTemplates | Leitura | read | Modelos de proposta salvos, com seus slots e suas regras de perguntas. |
upsertUpworkTemplate | Escrita | write | Cria ou atualiza um modelo de proposta. |
draftUpworkProposal | Escrita | write, explore | Redige uma proposta para uma vaga a partir de um modelo. Você mesmo cola o texto no Upwork. |
listUpworkCampaigns | Leitura | read | Campanhas salvas: pesquisa, pontuação mínima, status, última atualização, saúde das fontes. |
saveUpworkCampaign | Escrita | write | Cria ou atualiza uma campanha: nome, pesquisa, pontuação mínima, modelo. |
simulateUpworkCampaign | Leitura ao vivo | explore | Simula uma campanha em vagas reais antes de acompanhá-la. Nada é salvo. |
followUpworkCampaign | Ação | act | Pede ao Motor que acompanhe uma campanha salva, no ritmo de coleta dela. |
pauseUpworkCampaign | Ação | act | Faz o Motor parar de acompanhar uma campanha. As vagas já vistas permanecem no pipeline. |
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 | Escrita | write, explore | Lê de novo as páginas das candidaturas em andamento para datar o desfecho: encerrada, entrevistas iniciadas, sem resposta. |
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 | Escrita | write | Salva o perfil de necessidades do workspace: objetivos, assuntos, entidades, idiomas, regiões, nível, ritmo. |
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 | Exclusão | write | Para de acompanhar uma entidade. Os vínculos existentes permanecem. |
saveBookmark | Escrita | write | Salva um favorito no cofre do workspace. Uma URL http(s) entra na fila para leitura, arquivamento e vetorização. |
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 | Exclusão | write | Remove o contrato de monitoramento de uma fonte: todos os itens voltam a aparecer. |
initReaderInterview | Escrita | write | Salva as duas respostas da entrevista de leitura (o essencial ou o detalhe, intenção principal) no perfil de leitura. |
applyBoardChange | Escrita | write | Aplica a um board alterações que já foram aprovadas. |
buildDashboard | Escrita | write | Monta um board diretamente, sem passar pelo seletor de widgets. |
saveWorkspaceTable | Escrita | write | Cria uma tabela do workspace, preenchida com as colunas úteis. |
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 | 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 | Ação | act | Assina uma nova fonte. Inicia uma coleta real (tarefas de leitura, cotas das plataformas). |
subscribeSources | Ação | act | Assina várias fontes em uma única chamada e devolve um resultado por fonte. |
unsubscribeSource | Ação | act | Para de acompanhar uma fonte. Os itens já coletados permanecem no corpus. |
setHomeDashboard | Ação | act | Define um board salvo como a página inicial do workspace. |
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 | 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 | Ação | act | Coloca na fila uma investigação Edge em segundo plano para este workspace (owner ou admin). |
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 | 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 | 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 | 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 | 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. |