본문으로 건너뛰기

가이드

도구

에이전트의 도구를 하나씩 호출합니다. 스코프와 입력을 함께 안내합니다.

Piqline 에이전트는 도구로 일합니다. 코퍼스 읽기, 실시간 검색, 쓰기, 실행이 있습니다. API는 모든 도구를 같은 형태로 제공합니다. 호출할 수 있는 도구는 92개이며, 카탈로그에 스코프와 함께 나열되어 있고, 레퍼런스에는 각 도구의 매개변수와 호출 예제가 있습니다.

도구 목록 조회#

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에는 all(기본값), piqline, requete, facebook, linkedin, upwork, onboarding을 사용할 수 있습니다. 목록의 각 도구에는 다음 필드가 있습니다.

필드의미
name호출할 때 사용하는 도구 이름
description에이전트가 읽는 영어 도구 설명
agents이 도구를 가진 에이전트
requires필요한 스코프
callable키로 호출할 수 있으면 true
missing_scopes키에 없는 스코프
confirmation_in_chat도구 실행 전에 채팅이 확인을 요청하면 true
read_only도구가 아무것도 변경하지 않으면 true
input_schema입력의 JSON Schema

키로 호출할 수 없는 도구도 목록에 남으며, callable: false와 missing_scopes가 함께 표시됩니다. GET/api/v1/tools/{nom}은 도구 하나에 대해 같은 항목을 반환하며, confirmation_in_chat과 read_only는 포함하지 않습니다.

도구 호출하기#

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

JSON 본문이 도구의 입력이며, input_schema가 그 형태를 설명합니다. 입력이 없는 도구는 빈 본문을 받습니다.

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

응답에는 도구 이름과 출력이 들어 있으며, 에이전트가 읽는 출력과 같습니다.

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은 항목에 표시되는 날짜입니다. getItem은 detectedAt(Piqline이 처음 본 시점), lastSeenAt(마지막으로 본 시점), publishedAt도 반환합니다.

오류는 application/problem+json으로 반환됩니다. 오류를 참조하십시오.

누가 무엇을 호출할 수 있는가#

  • 키는 만든 사람의 역할로 제한됩니다. 그 역할이 열어 주지 않는 도구는 403 forbidden으로 응답합니다. 쓰기 도구, 실행 도구, onboarding 에이전트는 소유자와 관리자 전용입니다.
  • 채팅 카드는 API에 없습니다. askUser, proposeSources, proposeBoard 등은 사람에게 표시되는 카드이며 아무것도 실행하지 않습니다. 이 도구들은 404 not_found로 응답합니다. 이런 대화를 하려면 에이전트를 실행하십시오.
  • 실행 도구는 확인을 기다리지 않습니다. 채팅에서는 확인을 요청하지만, act 스코프로 직접 호출하면 즉시 실행됩니다.
  • 실시간 읽기는 크레딧을 사용합니다. explore 스코프의 도구는 워크스페이스의 월간 한도에서 크레딧을 차감합니다.

카탈로그#

코퍼스와 워크스페이스 읽기#

Piqline 에이전트의 도구입니다. 워크스페이스가 이미 수집한 내용을 읽습니다. 크레딧을 사용하지 않으며 아무것도 쓰지 않습니다.

도구유형스코프역할
getCoverageStats읽기read수집량과 상태: 합계, 플랫폼별 및 종류별 분포, 분석 기간(1h, 24h, 7d, 30d) 동안의 수집 시계열.
listSources읽기read워크스페이스가 팔로우하는 소스와 항목 수, 상태, 마지막 읽기.
searchItems읽기read필터(텍스트, 플랫폼, 종류, 소스)로 항목(게시물, 동영상, 기사, 광고, 일감)을 검색합니다. 필터가 없으면 최신 항목을 반환합니다(최대 40개).
getItem읽기read항목의 상세: 텍스트, 전사, OCR, 감지된 주제, 의미가 가까운 항목, 관찰 날짜.
searchPassages읽기read긴 문서(Motor가 읽은 PDF)에서 의미로 검색합니다. 질문과 가장 가까운 구절을 항목, 페이지, 섹션 제목과 함께 반환합니다.
citeItem읽기read구절이 항목에 글자 그대로 나오는지 확인하고 인용 번호를 반환합니다. 없으면 가장 가까운 구절을 반환합니다. 채팅의 인용 모드의 기반입니다.
drawDiagram읽기read답변을 SVG 다이어그램(타임라인, 매트릭스, 흐름, 트리 등)으로 그립니다. 색상은 테마 역할에 따르며, SVG는 표시 전에 정제됩니다. 채팅의 다이어그램 모드의 기반입니다.
createCanvas읽기read캔버스(piqline/canvas SDK만 import하는 TSX 파일)를 컴파일하여 바로 표시할 수 있는 코드, 또는 수정해야 할 오류를 반환합니다. 채팅의 캔버스 및 리포트 모드의 기반입니다.
getTopics읽기read감지된 주제와 점유율, 그리고 스토리(여러 소스에서 본 같은 주제).
getSignals읽기read워크스페이스의 지속성 규칙으로 발생한 열린 신호와 그 선행 시간 및 상태.
listWorkspaceTables읽기read워크스페이스에 이미 만들어진 테이블: 이름, 설명, 열과 행의 수, 테이블이 자동으로 채워지는지 여부.
getWorkspaceTable읽기readJSON으로 된 워크스페이스 테이블: 스키마, 열, 행. 사이트, 앱 또는 에이전트의 기반이나 데이터 공급원으로 쓰입니다(read 스코프).
listBookmarks읽기read워크스페이스 보관함의 북마크와 폴더: 제목, 유형, 폴더, 상태, 승인 여부. 단어, 상태, 유형으로 선택 필터링할 수 있습니다.
listEntities읽기read팔로우 중인 엔티티(회사, 브랜드, 공개 계정)와 해당 기간에 연결된 항목.
listWatchContracts읽기read소스에 설정된 모니터링 계약: 의도, 유지할 용어와 제외할 용어, 이벤트.
checkInvestigation읽기read가장 최근 Edge 조사 또는 지정한 조사의 상태: 대기 중, 실행 중, 후보와 함께 완료, 또는 실패.
checkHunt읽기read가장 최근 헌트 또는 지정한 헌트의 상태: 단계, 찾은 사람(코드의 판정과 사용자의 판정), 각 조건의 상태와 날짜가 있는 공개 근거(URL, 날짜, 발췌). 연락처는 절대 포함하지 않습니다.
planSourcePack읽기read목표에 맞는 일관된 소스 묶음을 제안합니다. 아무것도 만들지 않습니다.
listWidgets읽기read이 워크스페이스의 보드에 놓을 수 있는 위젯을 사용자에게 맞게 순위를 매겨 이유와 함께 나열합니다.
getAdvertiserCampaigns읽기read워크스페이스 수집 데이터에 있는 광고주의 광고 파일: 광고, 게재 중인 광고, 날짜, 라이브러리, 국가, 읽은 니즈, 월별 신규 광고와 증가 추세, 최신 광고, 신호. 개인은 다루지 않습니다. 크레딧을 사용하지 않습니다.
listAdSignals읽기read매시간 계산되는 워크스페이스의 광고 신호: 캠페인 시작 또는 중단, 증가, 새 국가, 새 플랫폼, 유료 채용, 프로모션, 출시, 새 광고주. 크레딧을 사용하지 않습니다.
listCollectedAds읽기read이미 읽은 워크스페이스의 광고 수집(Meta, TikTok, Google, LinkedIn): 목록, 또는 수집 이름을 지정하면 분류(각도, 오퍼, 톤, 형식), 속도, 가장 오래 게재된 광고, 라이브러리, 상태, 각도 또는 단어로 필터링한 광고. 크레딧을 사용하지 않습니다.

웹과 공공 등록부 실시간 탐색#

웹과 공개 네트워크를 실시간으로 읽습니다. 크레딧을 사용하며, 워크스페이스에는 아무것도 저장되지 않습니다.

도구유형스코프역할
readPage실시간 읽기explore공개 웹 페이지를 읽습니다: 제목, 본문(6,000자), 발견된 피드, 링크 30개.
searchWeb실시간 읽기explore공개 웹을 검색하여 후보 URL을 찾습니다.
browserRead실시간 읽기explore강제 브라우저로 동적 페이지나 보호된 페이지를 읽습니다. readPage와 같은 형태입니다.
waybackHistory실시간 읽기exploreURL의 Wayback Machine 캡처: 첫 캡처와 최근 캡처.
registryLookup실시간 읽기explore공개 등록부에서 회사를 조회합니다: Sirene(프랑스), EDGAR(미국), Companies House(영국), OpenCorporates.
socialCatalog실시간 읽기explore소셜 네트워크 읽기 엔드포인트(최대 40개)를 나열하며, 플랫폼별로 필터링할 수 있습니다.
socialCall실시간 읽기explore소셜 네트워크 읽기 엔드포인트를 호출하여 간략한 항목을 최대 20개 반환합니다.
previewSource실시간 읽기explore구독하기 전에 소스의 실시간 샘플(5~10개 항목)을 가져옵니다.
whoSaidItFirst실시간 읽기explore웹에서 어떤 정보를 누가 가장 먼저 게시했는지를 페이지 단위로, 그리고 사용자의 소스가 그것을 언제 보았는지 알려 줍니다. 주제 또는 항목에서 시작하며, 비공개 워크스페이스 타임라인으로 보관됩니다.

Facebook#

Facebook 에이전트의 도구입니다. Marketplace 매물과 공개 그룹을 실시간으로 읽습니다.

도구유형스코프역할
findMarketplaceLocation실시간 읽기explore도시 또는 지역 이름을 Marketplace 좌표로 변환합니다.
searchMarketplace실시간 읽기explore장소(도시 또는 좌표) 주변의 공개 Marketplace 매물을 키워드로 검색합니다. 최대 3페이지.
getMarketplaceListing실시간 읽기explore매물의 상세: 설명, 속성, 사진, 배송, Facebook이 제공하는 경우 정확한 날짜.
getMarketplaceListings실시간 읽기explore매물 2~6개의 상세를 비교 표로 한 번에 가져옵니다.
getFacebookGroup실시간 읽기explore그룹의 공개 프로필: 공개 범위, 규모, 활동, 카테고리, 규칙.
getFacebookGroupPosts실시간 읽기explore공개 그룹의 게시물을 3개씩 페이지로 가져옵니다(최대 6페이지).
getFacebookPost실시간 읽기explore공개 게시물 또는 릴스의 상세: 텍스트, 작성자, 날짜, 반응, 조회수.
getFacebookPostComments실시간 읽기explore공개 게시물의 댓글을 키워드로 필터링할 수 있습니다(최대 3페이지).

LinkedIn#

LinkedIn 에이전트의 도구입니다. 공개 게시물, 회사 페이지, 광고를 실시간으로 읽습니다. 연락처는 읽지 않습니다.

도구유형스코프역할
searchLinkedinPosts실시간 읽기explore키워드로 공개 게시물을 실시간으로 최신순 검색합니다(부분 읽기는 결과에 표시됨). 채용 게시물에는 작성자의 직함과 역할을 함께 반환하며, 코드가 계산한 신호(채용, 투자 유치, 출시, 확장, 조직 개편, 가용, 퇴사)를 포함합니다.
probeLinkedinWatch실시간 읽기exploreLinkedIn 모니터링을 구독하기 전에 쿼리 변형 1~3개를 시험하고, 구독에 첨부할 조사 티켓을 반환합니다.
getLinkedinPost실시간 읽기explore공개 게시물 또는 기사를 읽습니다: 텍스트, 작성자, 날짜, 반응, 신호가 포함된 댓글.
getLinkedinPostTranscript실시간 읽기explore공개 게시물 동영상의 전사. 전사가 있는 경우에만 과금됩니다.
getLinkedinCompany실시간 읽기explore공개 회사 페이지: 설명, 직원 수, 업종, 투자 정보, 신호가 포함된 최신 게시물.
getLinkedinCompanyPosts실시간 읽기explore회사 페이지의 이전 게시물과 신호 요약(채용, 투자, 출시).
searchLinkedinAds실시간 읽기explore광고 라이브러리를 검색합니다: 광고주, 형식, 날짜, 노출 수.
getLinkedinAd실시간 읽기explore라이브러리 광고의 상세: 타겟팅, 국가별 노출 수, 게재 기간.
matchLinkedinPosts실시간 읽기explore공개 게시물을 바탕으로 가용한 사람과 기회를 매칭합니다(검색 두 번).
getLinkedinProfile실시간 읽기explore공개 /in/ 프로필을 제한적으로 읽습니다. 그 사람을 언급하는 공개 게시물에서만 가능합니다. 이 옵션을 켠 워크스페이스 전용입니다.

Upwork#

Upwork 에이전트의 도구입니다. 공개 일감을 읽고, 점수를 매기고, 워크스페이스 지식 베이스를 바탕으로 답안을 작성합니다. Upwork로는 아무것도 전송되지 않습니다.

도구유형스코프역할
searchUpworkJobs실시간 읽기explore공개 결과 한 페이지(일감 약 10건)를 읽고 각 일감을 지식 베이스와 비교해 점수를 매깁니다. 일감은 워크스페이스 파이프라인에 추가됩니다.
getUpworkJob실시간 읽기explore일감을 읽습니다: 설명, 기술, 예산, 활동, 클라이언트. 날짜가 있는 스냅샷을 파이프라인에 추가합니다.
scoreUpworkJobs쓰기write지식 베이스가 바뀐 후 파이프라인 일감의 점수를 다시 매깁니다. 페이지는 읽지 않습니다.
getUpworkRadar실시간 읽기explore시장 레이더: 일별 건수, 요율과 예산의 사분위수, 기술, 경쟁, 클라이언트 국가.
listUpworkLeads읽기readUpwork 파이프라인: 상태별 건수, 우수 일감 순, 각 일감의 결과.
updateUpworkLead쓰기write파이프라인 일감의 상태(발송, 답장, 인터뷰, 수주, 실패, 무시)를 변경하고 메모를 남깁니다.
getUpworkKnowledge읽기read워크스페이스의 Upwork 지식 베이스: 서비스, 도구, 피할 프로젝트, 최저 요율, 사례, 어조, 서명.
updateUpworkKnowledge쓰기write지식 베이스를 업데이트합니다. 보낸 목록은 저장된 목록을 대체합니다.
listUpworkTemplates읽기read저장된 제안서 템플릿과 슬롯, 질문 규칙.
upsertUpworkTemplate쓰기write제안서 템플릿을 만들거나 업데이트합니다.
draftUpworkProposal쓰기write, explore템플릿으로 일감에 대한 제안서 초안을 작성합니다. 텍스트는 직접 Upwork에 붙여 넣습니다.
listUpworkCampaigns읽기read저장된 캠페인: 검색, 최소 점수, 상태, 마지막 새로고침, 소스 상태.
saveUpworkCampaign쓰기write캠페인을 만들거나 업데이트합니다: 이름, 검색, 최소 점수, 템플릿.
simulateUpworkCampaign실시간 읽기explore팔로우하기 전에 실제 일감으로 캠페인을 시뮬레이션합니다. 아무것도 저장되지 않습니다.
followUpworkCampaign실행act저장된 캠페인을 수집 주기에 맞춰 팔로우하도록 Motor에 요청합니다.
pauseUpworkCampaign실행actMotor가 캠페인을 팔로우하지 않도록 중지합니다. 이미 본 일감은 파이프라인에 남습니다.
refreshUpworkCampaigns쓰기write, explore팔로우 중인 캠페인을 새로고침합니다: Motor가 수집한 일감을 병합하고, 첫 페이지를 실시간으로 다시 읽고, 새 일감의 점수를 매깁니다.
checkUpworkOutcomes쓰기write, explore진행 중인 지원 페이지를 다시 읽어 결과 날짜를 기록합니다: 마감, 인터뷰 시작, 무응답.
syncUpworkReplies쓰기write키를 만든 사람이 연결한 받은편지함에서 Upwork 알림 이메일을 읽고 파이프라인 일감의 상태를 진행시킵니다.

워크스페이스에 쓰기#

워크스페이스 객체를 만들거나 변경하는 Piqline 에이전트의 도구입니다. write 스코프가 필요합니다.

도구유형스코프역할
updateWorkspaceProfile쓰기write워크스페이스의 니즈 프로필을 저장합니다: 목표, 주제, 엔티티, 언어, 지역, 수준, 속도.
followEntity쓰기write회사, 브랜드 또는 공개 계정(개인은 제외)을 팔로우하여 그 항목과 언급을 연결합니다.
unfollowEntity삭제write엔티티 팔로우를 중단합니다. 기존 연결은 남습니다.
saveBookmark쓰기write워크스페이스 보관함에 북마크를 저장합니다. http(s) URL은 읽기, 보관, 벡터화 대기열에 들어갑니다.
setWatchContract쓰기write소스에 모니터링 계약을 설정합니다. 이후 모니터링 페이지에는 일치하는 항목만 표시됩니다. 결정적 방식이며 모델을 사용하지 않습니다.
removeWatchContract삭제write소스의 모니터링 계약을 제거합니다. 모든 항목이 다시 표시됩니다.
initReaderInterview쓰기write읽기 인터뷰의 두 가지 답(핵심 또는 상세, 주된 의도)을 읽기 프로필에 저장합니다.
applyBoardChange쓰기write이미 승인된 변경 사항을 보드에 적용합니다.
buildDashboard쓰기write위젯 선택기를 거치지 않고 보드를 직접 만듭니다.
saveWorkspaceTable쓰기write유용한 열이 채워진 워크스페이스 테이블을 만듭니다.
writeFromWatch쓰기write워크스페이스 모니터링 항목을 바탕으로 텍스트를 작성합니다(기사, LinkedIn 게시물, X 스레드, Instagram 캡션, 뉴스레터, 동영상 스크립트, 보도 자료, SEO 기사, 이메일, 요약). 9개 언어를 지원하며, 각 사실에는 출처를 [n]으로 인용하고, 텍스트는 초안에 추가됩니다. 크레딧을 조금 사용합니다.
setTableFeed실행act, write테이블이 스스로 채워지게 합니다: 규칙에 맞는 코퍼스 항목이 생기면 확인 후 추가됩니다. status=paused는 채우기를 중지합니다.

소스와 규칙에 대한 실행#

Piqline 에이전트의 실행 도구입니다. 채팅에서는 각 도구가 확인을 요청합니다. API에서는 act 스코프로 직접 호출하는 것이 확인으로 간주됩니다. 해당하는 사람이 동의한 후에만 이 도구를 호출하십시오.

도구유형스코프역할
subscribeSource실행act새 소스를 구독합니다. 실제 수집(읽기 작업, 플랫폼 쿼터)을 시작합니다.
subscribeSources실행act한 번의 호출로 여러 소스를 구독하고 소스별 결과를 반환합니다.
unsubscribeSource실행act소스 팔로우를 중단합니다. 이미 수집된 항목은 코퍼스에 남습니다.
setHomeDashboard실행act저장된 보드를 워크스페이스 홈으로 설정합니다.
upsertSignalRule실행act지속성 신호 규칙을 만들거나 업데이트합니다. 항목이 임계값보다 오래 온라인에 남아 있으면 발동합니다.
upsertQuestionRule실행act상시 질문을 만들거나 업데이트합니다. 워크스페이스 소스의 모든 새 항목에 대해 Jev가 던지는 평이한 문장입니다. 확률 임계값이 신호를 만듭니다.
startInvestigation실행act이 워크스페이스를 위한 백그라운드 Edge 조사를 대기열에 넣습니다(소유자 또는 관리자).
startHunt실행act헌트를 시작합니다. 검증 가능한 조건을 충족하는 사람을 찾으며, 각 조건은 날짜가 있는 공개 출처로 입증됩니다. 민감한 조건은 거부되고 연락처는 반환되지 않습니다. 백그라운드에서 실행되며 해당 월의 크레딧을 사용합니다. 소유자 또는 관리자.
buildAdAudit쓰기write이미 수집된 광고주 1~6곳의 캠페인을 N개월에 걸쳐 소급 감사합니다. 워크스페이스 테이블(광고주, 월, 신규 광고, 중단, 라이브러리, 국가, 읽은 니즈, 증가)과 인용된 요약의 수치를 만듭니다. 크레딧을 사용하지 않습니다.
findCreatorSponsors실행act, write, explore특정 분야에서 YouTube 크리에이터에게 비용을 지불하는 곳: 최근 동영상을 검색하고, 각 동영상에서 스폰서를 추론하여 “Sponsors · niche” 워크스페이스 테이블을 만듭니다. 크레딧을 사용하며, 채팅에서 확인을 거치고, 소유자 또는 관리자 전용입니다.
importAdHistory실행act, write, explore광고주 수집의 Google 이력을 가져옵니다. 최대 20페이지(2021년 이후 광고 약 800건)로 과거 캠페인의 날짜를 파악합니다. 크레딧을 사용하며, 채팅에서 확인을 거치고, 소유자 또는 관리자 전용입니다.
startAdCollection실행act, write, explore광고주(이름 또는 도메인) 또는 키워드에 대한 광고 수집을 시작합니다. Meta, TikTok, Google, LinkedIn을 읽고 모든 광고를 같은 형식으로 정리한 다음 각도, 오퍼, 타겟, 어조를 읽습니다. 크레딧을 사용하며, 채팅에서 확인을 거치고, 소유자 또는 관리자 전용입니다.

API에 대한 질문이 있거나 이 페이지에 오류가 있나요? 문의하기.