Ir para o conteúdo

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#

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:

CampoSignificado
nameo nome da ferramenta, como você a chama
descriptiono que a ferramenta faz, em inglês, como o agente a lê
agentsos agentes que têm a ferramenta
requiresos scopes exigidos
callabletrue se a sua chave pode chamá-la
missing_scopesscopes que a chave não tem
confirmation_in_chattrue se o chat pede confirmação antes de executar a ferramenta
read_onlytrue se a ferramenta não altera nada
input_schemaJSON 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.

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}'

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.

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.
  • 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.

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.

FerramentaTipoScopesFunção
getCoverageStatsLeiturareadVolumes 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).
listSourcesLeiturareadFontes que o workspace acompanha, com número de itens, saúde e última leitura.
searchItemsLeiturareadBusca itens (posts, vídeos, artigos, anúncios, vagas) com filtros: texto, plataforma, tipo, fonte. Sem filtro, devolve os mais recentes (40 no máximo).
getItemLeiturareadDetalhe de um item: texto, transcrição, OCR, temas detectados, itens próximos em significado e suas datas de observação.
searchPassagesLeiturareadBusca 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.
citeItemLeiturareadVerifica 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.
drawDiagramLeiturareadDesenha 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.
createCanvasLeiturareadCompila 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.
getTopicsLeiturareadTemas detectados com sua parcela de voz e histórias (o mesmo assunto visto em várias fontes).
getSignalsLeiturareadSinais abertos, disparados pelas regras de persistência do workspace, com seu prazo e status.
listWorkspaceTablesLeiturareadTabelas já criadas no workspace: nome, comentário, número de colunas e linhas, e se a tabela se preenche sozinha.
getWorkspaceTableLeiturareadUma 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).
listBookmarksLeiturareadFavoritos e pastas do cofre do workspace: título, tipo, pasta, status, admissão. Filtro opcional por palavra, status ou tipo.
listEntitiesLeiturareadEntidades acompanhadas (empresas, marcas, contas públicas) e itens vinculados no período.
listWatchContractsLeiturareadContratos de monitoramento definidos nas fontes: intenção, termos mantidos e excluídos, evento.
checkInvestigationLeiturareadStatus da última investigação Edge, ou de uma específica: pendente, em execução, concluída com seus candidatos, ou falha.
checkHuntLeiturareadStatus 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.
planSourcePackLeiturareadPropõe um conjunto coerente de fontes a acompanhar para um objetivo. Não cria nada.
listWidgetsLeiturareadWidgets que podem entrar em um board deste workspace, classificados para a pessoa, com seus motivos.
getAdvertiserCampaignsLeiturareadDossiê 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.
listAdSignalsLeiturareadSinais 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.
listCollectedAdsLeiturareadColetas 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.

FerramentaTipoScopesFunção
readPageLeitura ao vivoexploreLê uma página web pública: título, texto principal (6.000 caracteres), feeds descobertos e 30 links.
searchWebLeitura ao vivoexplorePesquisa na web pública para encontrar URLs candidatas.
browserReadLeitura ao vivoexploreLê uma página dinâmica ou protegida com um navegador forçado. Mesma forma que readPage.
waybackHistoryLeitura ao vivoexploreCapturas da Wayback Machine de uma URL: primeira captura e capturas recentes.
registryLookupLeitura ao vivoexploreConsulta uma empresa em um registro público: Sirene (França), EDGAR (Estados Unidos), Companies House (Reino Unido) ou OpenCorporates.
socialCatalogLeitura ao vivoexploreLista os endpoints de leitura das redes sociais (40 no máximo), filtráveis por plataforma.
socialCallLeitura ao vivoexploreChama um endpoint de leitura de rede social e devolve até 20 itens compactos.
previewSourceLeitura ao vivoexploreAmostra ao vivo (5 a 10 itens) de uma fonte, antes de assiná-la.
whoSaidItFirstLeitura ao vivoexploreQuem 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.

FerramentaTipoScopesFunção
findMarketplaceLocationLeitura ao vivoexploreConverte o nome de uma cidade ou região em coordenadas do Marketplace.
searchMarketplaceLeitura ao vivoexplorePesquisa anúncios públicos do Marketplace por palavra-chave em torno de um local (cidade ou coordenadas), em no máximo 3 páginas.
getMarketplaceListingLeitura ao vivoexploreDetalhe de um anúncio: descrição, atributos, fotos, entrega, data exata quando o Facebook a fornece.
getMarketplaceListingsLeitura ao vivoexploreDetalhe de 2 a 6 anúncios de uma vez, em uma tabela comparativa.
getFacebookGroupLeitura ao vivoexplorePerfil público de um grupo: privacidade, tamanho, atividade, categorias, regras.
getFacebookGroupPostsLeitura ao vivoexplorePosts de um grupo público, em páginas de 3 (6 páginas no máximo).
getFacebookPostLeitura ao vivoexploreDetalhe de um post público ou reel: texto, autor, data, reações, visualizações.
getFacebookPostCommentsLeitura ao vivoexploreComentá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.

FerramentaTipoScopesFunção
searchLinkedinPostsLeitura ao vivoexplorePesquisa 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.
probeLinkedinWatchLeitura ao vivoexploreTesta de 1 a 3 variantes de consulta antes de assinar um monitoramento do LinkedIn e devolve o ticket de investigação a anexar à assinatura.
getLinkedinPostLeitura ao vivoexploreLê um post ou artigo público: texto, autor, data, reações, comentários com seus sinais.
getLinkedinPostTranscriptLeitura ao vivoexploreTranscrição do vídeo de um post público, cobrada apenas se existir.
getLinkedinCompanyLeitura ao vivoexplorePágina pública de uma empresa: descrição, número de funcionários, setor, financiamento, últimos posts com seus sinais.
getLinkedinCompanyPostsLeitura ao vivoexplorePosts mais antigos da página de uma empresa, com um resumo dos sinais (contratação, financiamento, lançamentos).
searchLinkedinAdsLeitura ao vivoexplorePesquisa a biblioteca de anúncios: anunciante, formato, datas, impressões.
getLinkedinAdLeitura ao vivoexploreDetalhe de um anúncio da biblioteca: segmentação, impressões por país, duração.
matchLinkedinPostsLeitura ao vivoexploreCruza pessoas disponíveis com oportunidades vindas de posts públicos (duas pesquisas).
getLinkedinProfileLeitura ao vivoexploreLeitura 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.

FerramentaTipoScopesFunção
searchUpworkJobsLeitura ao vivoexploreLê 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.
getUpworkJobLeitura ao vivoexploreLê uma vaga: descrição, habilidades, orçamento, atividade, cliente. Adiciona um instantâneo datado ao pipeline.
scoreUpworkJobsEscritawritePontua de novo as vagas do pipeline após uma mudança na base de conhecimento. Nenhuma página é lida.
getUpworkRadarLeitura ao vivoexploreRadar de mercado: volume por dia, quartis de valor por hora e de orçamento, habilidades, concorrência, países dos clientes.
listUpworkLeadsLeiturareadPipeline do Upwork: contagem por status, melhores vagas primeiro, desfecho de cada uma.
updateUpworkLeadEscritawriteAltera o status de uma vaga do pipeline (enviada, resposta, entrevista, ganha, perdida, ignorada) e guarda uma nota.
getUpworkKnowledgeLeiturareadBase de conhecimento Upwork do workspace: serviços, ferramentas, projetos a evitar, valores mínimos, estudos de caso, tom, assinatura.
updateUpworkKnowledgeEscritawriteAtualiza a base de conhecimento. As listas que você envia substituem as listas armazenadas.
listUpworkTemplatesLeiturareadModelos de proposta salvos, com seus slots e suas regras de perguntas.
upsertUpworkTemplateEscritawriteCria ou atualiza um modelo de proposta.
draftUpworkProposalEscritawrite, exploreRedige uma proposta para uma vaga a partir de um modelo. Você mesmo cola o texto no Upwork.
listUpworkCampaignsLeiturareadCampanhas salvas: pesquisa, pontuação mínima, status, última atualização, saúde das fontes.
saveUpworkCampaignEscritawriteCria ou atualiza uma campanha: nome, pesquisa, pontuação mínima, modelo.
simulateUpworkCampaignLeitura ao vivoexploreSimula uma campanha em vagas reais antes de acompanhá-la. Nada é salvo.
followUpworkCampaignAçãoactPede ao Motor que acompanhe uma campanha salva, no ritmo de coleta dela.
pauseUpworkCampaignAçãoactFaz o Motor parar de acompanhar uma campanha. As vagas já vistas permanecem no pipeline.
refreshUpworkCampaignsEscritawrite, exploreAtualiza as campanhas acompanhadas: mescla as vagas coletadas pelo Motor, lê de novo a primeira página ao vivo, pontua as novas vagas.
checkUpworkOutcomesEscritawrite, exploreLê de novo as páginas das candidaturas em andamento para datar o desfecho: encerrada, entrevistas iniciadas, sem resposta.
syncUpworkRepliesEscritawriteLê 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.

FerramentaTipoScopesFunção
updateWorkspaceProfileEscritawriteSalva o perfil de necessidades do workspace: objetivos, assuntos, entidades, idiomas, regiões, nível, ritmo.
followEntityEscritawriteAcompanha uma empresa, uma marca ou uma conta pública (nunca uma pessoa física) para vincular seus itens e menções.
unfollowEntityExclusãowritePara de acompanhar uma entidade. Os vínculos existentes permanecem.
saveBookmarkEscritawriteSalva um favorito no cofre do workspace. Uma URL http(s) entra na fila para leitura, arquivamento e vetorização.
setWatchContractEscritawriteDefine um contrato de monitoramento em uma fonte: a página de monitoramento mostra então apenas os itens correspondentes. Determinístico, sem modelo.
removeWatchContractExclusãowriteRemove o contrato de monitoramento de uma fonte: todos os itens voltam a aparecer.
initReaderInterviewEscritawriteSalva as duas respostas da entrevista de leitura (o essencial ou o detalhe, intenção principal) no perfil de leitura.
applyBoardChangeEscritawriteAplica a um board alterações que já foram aprovadas.
buildDashboardEscritawriteMonta um board diretamente, sem passar pelo seletor de widgets.
saveWorkspaceTableEscritawriteCria uma tabela do workspace, preenchida com as colunas úteis.
writeFromWatchEscritawriteEscreve 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.
setTableFeedAçãoact, writeDá 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.

FerramentaTipoScopesFunção
subscribeSourceAçãoactAssina uma nova fonte. Inicia uma coleta real (tarefas de leitura, cotas das plataformas).
subscribeSourcesAçãoactAssina várias fontes em uma única chamada e devolve um resultado por fonte.
unsubscribeSourceAçãoactPara de acompanhar uma fonte. Os itens já coletados permanecem no corpus.
setHomeDashboardAçãoactDefine um board salvo como a página inicial do workspace.
upsertSignalRuleAçãoactCria ou atualiza uma regra de sinal de persistência: ela dispara quando um item permanece no ar por mais tempo que o limite.
upsertQuestionRuleAçãoactCria 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.
startInvestigationAçãoactColoca na fila uma investigação Edge em segundo plano para este workspace (owner ou admin).
startHuntAçãoactInicia 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.
buildAdAuditEscritawriteAuditoria 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.
findCreatorSponsorsAçãoact, write, exploreQuem 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.
importAdHistoryAçãoact, write, exploreImporta 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.
startAdCollectionAçãoact, write, exploreInicia 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.

Uma dúvida sobre a API, ou um erro nesta página? Escreva para nós.