Saltar al contenido

Guías

Herramientas

Llama una a una a las herramientas de los agentes, con sus scopes y entradas.

Los agentes de Piqline trabajan con herramientas: leer el corpus, buscar en directo, escribir, actuar. La API expone cada una con la misma forma. Hay 92 herramientas invocables; el catálogo las lista con sus scopes y la referencia describe los parámetros de cada una, con ejemplos de llamada.

Listar las herramientas#

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 acepta all (el valor por defecto), piqline, requete, facebook, linkedin, upwork u onboarding. Cada herramienta de la lista incluye:

CampoSignificado
nameel nombre de la herramienta, tal como se llama
descriptionqué hace la herramienta, en inglés, tal como la lee el agente
agentslos agentes que tienen la herramienta
requireslos scopes requeridos
callabletrue si tu clave puede llamarla
missing_scopesscopes que la clave no tiene
confirmation_in_chattrue si el chat pide confirmación antes de ejecutar la herramienta
read_onlytrue si la herramienta no cambia nada
input_schemaJSON Schema de la entrada

Las herramientas que tu clave no puede llamar siguen en la lista, con callable: false y missing_scopes. GET/api/v1/tools/{nom} devuelve la misma entrada para una sola herramienta, sin confirmation_in_chat ni read_only.

Llamar a una herramienta#

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

El cuerpo JSON es la entrada de la herramienta, tal como la describe input_schema. Una herramienta sin entrada acepta un cuerpo vacío.

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

La respuesta incluye el nombre de la herramienta y su salida, la misma que lee el 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 es la fecha de visualización del elemento. getItem devuelve además detectedAt (primera vez que Piqline lo vio), lastSeenAt (última vez que lo vio) y publishedAt.

Un error llega como application/problem+json: consulta Errores.

Quién puede llamar a qué#

  • El rol del creador limita la clave. Una herramienta que ese rol no abre responde 403 forbidden. Las herramientas de escritura, las de acción y el agente onboarding están reservadas a propietarios y administradores.
  • Las tarjetas del chat no existen en la API. askUser, proposeSources, proposeBoard y similares se muestran a una persona y no ejecutan nada: responden 404 not_found. Para obtener ese diálogo, ejecuta un agente.
  • Las herramientas de acción no esperan confirmación. El chat la pide. Una llamada directa con el scope act se ejecuta de inmediato.
  • Las lecturas en directo consumen créditos. Las herramientas del scope explore descuentan créditos del tope mensual del workspace.

Leer el corpus y el workspace#

Herramientas del agente Piqline. Leen lo que el workspace ya ha recogido: no consumen créditos y no escriben nada.

HerramientaTipoScopesFunción
getCoverageStatsLecturareadVolúmenes y estado de la recogida: totales, desglose por plataforma y por tipo, series de ingesta en la ventana de análisis (1h, 24h, 7d o 30d).
listSourcesLecturareadFuentes que sigue el workspace, con número de elementos, estado y última lectura.
searchItemsLecturareadBusca elementos (publicaciones, vídeos, artículos, anuncios, ofertas) con filtros: texto, plataforma, tipo, fuente. Sin filtro, devuelve los más recientes (40 como máximo).
getItemLecturareadDetalle de un elemento: texto, transcripción, OCR, temas detectados, elementos de sentido cercano y sus fechas de observación.
searchPassagesLecturareadBúsqueda por sentido en documentos largos (PDF leídos por el Motor): los pasajes más cercanos a una pregunta, con el elemento, la página y el título de la sección.
citeItemLecturareadComprueba que un pasaje aparece palabra por palabra en un elemento y devuelve un número de cita; si no, el pasaje más cercano. Base del modo Citas del chat.
drawDiagramLecturareadDibuja la respuesta como un diagrama SVG (línea de tiempo, matriz, flujo, árbol…): colores por rol del tema, SVG saneado antes de mostrarse. Base del modo Diagrama del chat.
createCanvasLecturareadCompila un canvas (un archivo TSX que solo importa el SDK piqline/canvas) y devuelve código listo para mostrar, o el error que hay que corregir. Base de los modos Canvas e Informe del chat.
getTopicsLecturareadTemas detectados con su cuota de voz, e historias (el mismo asunto visto en varias fuentes).
getSignalsLecturareadSeñales abiertas, activadas por las reglas de persistencia del workspace, con su antelación y su estado.
listWorkspaceTablesLecturareadTablas ya creadas en el workspace: nombre, comentario, número de columnas y filas, y si la tabla se rellena sola.
getWorkspaceTableLecturareadUna tabla del workspace en JSON: esquema, columnas y filas. Sirve de base o de fuente para un sitio, una aplicación o un agente (scope read).
listBookmarksLecturareadMarcadores y carpetas de la bóveda del workspace: título, tipo, carpeta, estado, admisión. Filtro opcional por palabra, estado o tipo.
listEntitiesLecturareadEntidades seguidas (empresas, marcas, cuentas públicas) y elementos vinculados en el período.
listWatchContractsLecturareadContratos de vigilancia definidos sobre las fuentes: intención, términos conservados y excluidos, evento.
checkInvestigationLecturareadEstado de la última investigación de Edge, o de una concreta: pendiente, en curso, terminada con sus candidatos, o fallida.
checkHuntLecturareadEstado de la última búsqueda, o de una concreta: etapa, personas encontradas con el veredicto del código y el tuyo, y, para cada criterio, su estado y su prueba pública fechada (URL, fecha, extracto). Nunca datos de contacto.
planSourcePackLecturareadPropone un conjunto coherente de fuentes que seguir para un objetivo. No crea nada.
listWidgetsLecturareadWidgets que pueden ir en un tablero de este workspace, ordenados para la persona, con sus motivos.
getAdvertiserCampaignsLecturareadFicha publicitaria de un anunciante a partir de las colecciones del workspace: anuncios, los activos, fechas, bibliotecas, países, necesidades leídas, anuncios nuevos por mes y aumentos de ritmo, últimos anuncios, señales. Nunca una persona. Sin créditos.
listAdSignalsLecturareadSeñales publicitarias del workspace, calculadas cada hora: campaña iniciada o detenida, aumento de ritmo, nuevo país, nueva plataforma, contratación pagada, promoción, lanzamiento, nuevo anunciante. Sin créditos.
listCollectedAdsLecturareadColecciones de anuncios del workspace (Meta, TikTok, Google, LinkedIn), ya leídas: la lista o, con el nombre de una colección, sus desgloses (ángulos, ofertas, tonos, formatos), su ritmo, sus anuncios más longevos y sus anuncios filtrados por biblioteca, estado, ángulo o palabra. Sin créditos.

Explorar la web y los registros en directo#

Lecturas en directo de la web y de las redes públicas. Consumen créditos; no se guarda nada en el workspace.

HerramientaTipoScopesFunción
readPageLectura en directoexploreLee una página web pública: título, texto principal (6000 caracteres), feeds descubiertos y 30 enlaces.
searchWebLectura en directoexploreBusca en la web pública para encontrar URL candidatas.
browserReadLectura en directoexploreLee una página dinámica o protegida con un navegador forzado. Misma forma que readPage.
waybackHistoryLectura en directoexploreCapturas de Wayback Machine de una URL: primera captura y capturas recientes.
registryLookupLectura en directoexploreBusca una empresa en un registro público: Sirene (Francia), EDGAR (Estados Unidos), Companies House (Reino Unido) u OpenCorporates.
socialCatalogLectura en directoexploreLista los endpoints de lectura de redes sociales (40 como máximo), filtrables por plataforma.
socialCallLectura en directoexploreLlama a un endpoint de lectura de una red social y devuelve hasta 20 elementos compactos.
previewSourceLectura en directoexploreMuestra en directo (5 a 10 elementos) de una fuente, antes de suscribirse a ella.
whoSaidItFirstLectura en directoexploreQuién publicó primero una información en la web, página por página, y cuándo la vieron tus fuentes. Parte de un tema o de un elemento; se conserva como línea de tiempo privada del workspace.

Facebook#

Herramientas del agente de Facebook: anuncios de Marketplace y grupos públicos, leídos en directo.

HerramientaTipoScopesFunción
findMarketplaceLocationLectura en directoexploreConvierte el nombre de una ciudad o zona en coordenadas de Marketplace.
searchMarketplaceLectura en directoexploreBusca anuncios públicos de Marketplace por palabra clave en torno a un lugar (ciudad o coordenadas), en 3 páginas como máximo.
getMarketplaceListingLectura en directoexploreDetalle de un anuncio: descripción, atributos, fotos, envío, fecha exacta cuando Facebook la proporciona.
getMarketplaceListingsLectura en directoexploreDetalle de 2 a 6 anuncios a la vez, como tabla comparativa.
getFacebookGroupLectura en directoexplorePerfil público de un grupo: privacidad, tamaño, actividad, categorías, reglas.
getFacebookGroupPostsLectura en directoexplorePublicaciones de un grupo público, en páginas de 3 (6 páginas como máximo).
getFacebookPostLectura en directoexploreDetalle de una publicación o reel público: texto, autor, fecha, reacciones, visualizaciones.
getFacebookPostCommentsLectura en directoexploreComentarios de una publicación pública, filtrables por palabras clave (3 páginas como máximo).

LinkedIn#

Herramientas del agente de LinkedIn: publicaciones públicas, páginas de empresa y anuncios, leídos en directo. Los datos de contacto nunca se leen.

HerramientaTipoScopesFunción
searchLinkedinPostsLectura en directoexploreBusca publicaciones públicas por palabras clave, en tiempo real, de más reciente a más antigua (una lectura parcial se señala en el resultado), con el cargo y el rol del autor cuando la publicación es una oferta de empleo, y señales calculadas por código: contratación, captación de fondos, lanzamiento, expansión, reorganización, disponibilidad, salida.
probeLinkedinWatchLectura en directoexplorePrueba de 1 a 3 variantes de consulta antes de suscribirse a una vigilancia de LinkedIn, y devuelve el ticket de investigación que se adjunta a la suscripción.
getLinkedinPostLectura en directoexploreLee una publicación o artículo público: texto, autor, fecha, reacciones, comentarios con sus señales.
getLinkedinPostTranscriptLectura en directoexploreTranscripción del vídeo de una publicación pública, facturada solo si existe.
getLinkedinCompanyLectura en directoexplorePágina pública de empresa: descripción, plantilla, sector, financiación, últimas publicaciones con sus señales.
getLinkedinCompanyPostsLectura en directoexplorePublicaciones anteriores de una página de empresa, con un resumen de las señales (contratación, financiación, lanzamientos).
searchLinkedinAdsLectura en directoexploreBusca en la biblioteca de anuncios: anunciante, formato, fechas, impresiones.
getLinkedinAdLectura en directoexploreDetalle de un anuncio de la biblioteca: segmentación, impresiones por país, duración.
matchLinkedinPostsLectura en directoexploreEmpareja personas disponibles con oportunidades a partir de publicaciones públicas (dos búsquedas).
getLinkedinProfileLectura en directoexploreLectura acotada de un perfil público /in/, solo a partir de una publicación pública que nombra a la persona. Reservada a los workspaces que han activado esta opción.

Upwork#

Herramientas del agente de Upwork: ofertas públicas leídas, puntuadas y respondidas a partir de la base de conocimiento del workspace. No se envía nada a Upwork.

HerramientaTipoScopesFunción
searchUpworkJobsLectura en directoexploreLee una página de resultados públicos (unas diez ofertas) y puntúa cada oferta frente a la base de conocimiento. Las ofertas se añaden al pipeline del workspace.
getUpworkJobLectura en directoexploreLee una oferta: descripción, habilidades, presupuesto, actividad, cliente. Añade una instantánea fechada al pipeline.
scoreUpworkJobsEscriturawriteVuelve a puntuar las ofertas del pipeline tras un cambio en la base de conocimiento. No se lee ninguna página.
getUpworkRadarLectura en directoexploreRadar de mercado: volumen por día, cuartiles de tarifa y presupuesto, habilidades, competencia, países de los clientes.
listUpworkLeadsLecturareadPipeline de Upwork: recuento por estado, mejores ofertas primero, resultado de cada una.
updateUpworkLeadEscriturawriteCambia el estado de una oferta del pipeline (enviada, respuesta, entrevista, ganada, perdida, ignorada) y guarda una nota.
getUpworkKnowledgeLecturareadBase de conocimiento de Upwork del workspace: servicios, herramientas, proyectos que evitar, tarifas mínimas, casos de estudio, tono, firma.
updateUpworkKnowledgeEscriturawriteActualiza la base de conocimiento. Las listas que envías sustituyen a las listas almacenadas.
listUpworkTemplatesLecturareadPlantillas de propuesta guardadas, con sus campos y sus reglas de preguntas.
upsertUpworkTemplateEscriturawriteCrea o actualiza una plantilla de propuesta.
draftUpworkProposalEscriturawrite, exploreRedacta una propuesta para una oferta a partir de una plantilla. El texto lo pegas tú mismo en Upwork.
listUpworkCampaignsLecturareadCampañas guardadas: búsqueda, puntuación mínima, estado, última actualización, estado de las fuentes.
saveUpworkCampaignEscriturawriteCrea o actualiza una campaña: nombre, búsqueda, puntuación mínima, plantilla.
simulateUpworkCampaignLectura en directoexploreSimula una campaña con ofertas reales antes de seguirla. No se guarda nada.
followUpworkCampaignAcciónactPide al Motor que siga una campaña guardada, a su ritmo de recogida.
pauseUpworkCampaignAcciónactHace que el Motor deje de seguir una campaña. Las ofertas ya vistas permanecen en el pipeline.
refreshUpworkCampaignsEscriturawrite, exploreActualiza las campañas seguidas: fusiona las ofertas recogidas por el Motor, vuelve a leer la primera página en directo y puntúa las ofertas nuevas.
checkUpworkOutcomesEscriturawrite, exploreVuelve a leer las páginas de las candidaturas en curso para fechar su resultado: cerrada, entrevistas iniciadas, sin respuesta.
syncUpworkRepliesEscriturawriteLee los correos de notificación de Upwork en las bandejas conectadas del creador de la clave y hace avanzar el estado de las ofertas del pipeline.

Escribir en el workspace#

Herramientas del agente Piqline que crean o modifican objetos del workspace. Requieren el scope write.

HerramientaTipoScopesFunción
updateWorkspaceProfileEscriturawriteGuarda el perfil de necesidades del workspace: objetivos, temas, entidades, idiomas, regiones, nivel, ritmo.
followEntityEscriturawriteSigue una empresa, una marca o una cuenta pública (nunca una persona privada) para vincular sus elementos y menciones.
unfollowEntityEliminaciónwriteDeja de seguir una entidad. Sus vínculos existentes permanecen.
saveBookmarkEscriturawriteGuarda un marcador en la bóveda del workspace. Una URL http(s) se pone en cola para lectura, archivado y vectorización.
setWatchContractEscriturawriteDefine un contrato de vigilancia sobre una fuente: la página de vigilancia solo muestra entonces los elementos que coinciden. Determinista, sin modelo.
removeWatchContractEliminaciónwriteElimina el contrato de vigilancia de una fuente: se vuelven a mostrar todos los elementos.
initReaderInterviewEscriturawriteGuarda las dos respuestas de la entrevista de lectura (lo esencial o el detalle, intención principal) en el perfil de lectura.
applyBoardChangeEscriturawriteAplica a un tablero cambios que ya fueron aprobados.
buildDashboardEscriturawriteConstruye un tablero directamente, sin pasar por el selector de widgets.
saveWorkspaceTableEscriturawriteCrea una tabla del workspace, rellenada con las columnas útiles.
writeFromWatchEscriturawriteRedacta un texto a partir de los elementos de las vigilancias del workspace (artículo, publicación de LinkedIn, hilo de X, pie de foto de Instagram, boletín, guion de vídeo, nota de prensa, artículo SEO, correo, resumen), en nueve idiomas, con cada dato citado [n] a su fuente; el texto se une a los borradores. Consume unos pocos créditos.
setTableFeedAcciónact, writeDa vida a una tabla: en cuanto un elemento del corpus cumple la regla, se añade, previa confirmación. status=paused detiene el rellenado.

Actuar sobre fuentes y reglas#

Herramientas de acción del agente Piqline. En el chat, cada una pide confirmación. Por la API, una llamada directa con el scope act cuenta como confirmación: llama a estas herramientas solo después de que la persona afectada lo haya aceptado.

HerramientaTipoScopesFunción
subscribeSourceAcciónactSe suscribe a una fuente nueva. Inicia una recogida real (trabajos de lectura, cuotas de plataforma).
subscribeSourcesAcciónactSe suscribe a varias fuentes en una sola llamada y devuelve un resultado por fuente.
unsubscribeSourceAcciónactDeja de seguir una fuente. Los elementos ya recogidos permanecen en el corpus.
setHomeDashboardAcciónactDefine un tablero guardado como página de inicio del workspace.
upsertSignalRuleAcciónactCrea o actualiza una regla de señal de persistencia: se activa cuando un elemento permanece en línea más tiempo que el umbral.
upsertQuestionRuleAcciónactCrea o actualiza una pregunta permanente: una frase en lenguaje natural que Jev plantea a cada elemento nuevo de las fuentes del workspace. El umbral de probabilidad genera la señal.
startInvestigationAcciónactPone en cola una investigación de Edge en segundo plano para este workspace (propietario o administrador).
startHuntAcciónactInicia una búsqueda: encontrar personas que cumplen criterios verificables, cada criterio probado por una fuente pública fechada. Los criterios sensibles se rechazan y no se devuelve ningún dato de contacto. Se ejecuta en segundo plano y consume los créditos del mes; propietario o administrador.
buildAdAuditEscriturawriteAuditoría retroactiva de las campañas de 1 a 6 anunciantes ya recogidos, a lo largo de N meses: una tabla del workspace (anunciante, mes, anuncios nuevos, paradas, bibliotecas, países, necesidades leídas, aumento de ritmo) y las cifras de un resumen citado. Sin créditos.
findCreatorSponsorsAcciónact, write, exploreQuién paga a los creadores de YouTube en un nicho: búsqueda de vídeos recientes, patrocinadores deducidos de cada vídeo, una tabla del workspace «Patrocinadores · nicho». Consume créditos; confirmación en el chat, propietario o administrador.
importAdHistoryAcciónact, write, exploreImporta el historial de Google de una colección de anunciante: hasta 20 páginas (unos 800 anuncios desde 2021) para fechar campañas pasadas. Consume créditos; confirmación en el chat, propietario o administrador.
startAdCollectionAcciónact, write, exploreInicia una recogida de anuncios sobre un anunciante (nombre o dominio) o una palabra clave: lee Meta, TikTok, Google y LinkedIn, pone cada anuncio en el mismo formato y luego lee el ángulo, la oferta, la audiencia y el tono. Consume créditos; confirmación en el chat, propietario o administrador.

¿Tienes una pregunta sobre la API o has encontrado un error en esta página? Escríbenos.