Web Search Agent API Docs

Base

https://crawl.jhkim3ispark.work

모든 엔드포인트는 JSON POST 본문을 받습니다. Query 값과 URL 값은 사용량 원장에 기록하지 않습니다.

/api/search는 질의어를 기반으로 URL과 검색 결과를 찾습니다. /api/crawl은 이미 알고 있는 단일 URL에서 본문을 추출합니다. /api/scrap은 교보문고, KoreaScience, eArticle, 대한민국 상훈, 기관/커리어 페이지 등 출처별 워크플로를 감싼 래퍼입니다.

루트 엔드포인트인 /api/search와 /api/crawl은 GPT를 호출하지 않습니다. 묶음형 Search/Crawl 엔드포인트와 Scrap 워크플로는 결정적 식별 점수를 수행할 수 있으며, 요청하신 경우에만 선택적으로 GPT confidence를 추가합니다.

점수화가 가능한 엔드포인트를 호출하실 때에는 원본 소스 데이터를 담은 nullable person 및 company 객체를 함께 보내 주십시오. 각 결과의 마지막에는 scores가 추가되며, 그 안에 confidence, llm_confidence, identity_match_score, identity_match가 정리됩니다. 결정적 식별 점수만 유지하고 GPT를 생략하시려면 {"llm_confidence":false}를 보내시면 됩니다.

Endpoint Testers

Search keywords는 17개 평가 항목 중 실제 검색어 생성에 사용할 필드를 선택하는 영역입니다. Evaluation keywords는 결과가 대상 인물 또는 회사와 일치하는지 판단하기 위한 기준값 전체를 입력하는 영역입니다.

NoteApp Complete API

NoteApp용 목적별 완성형 엔드포인트입니다. 입력으로는 기존 17개 person/company 필드를 그대로 전달하시면 되며, 서버가 목적에 맞는 검색 질의를 구성하고 결과를 정리하여 반환합니다.

여섯 엔드포인트는 모두 JSON 입력을 사용합니다. complete 응답은 동기 집계 방식으로 동작하므로 포함된 하위 검색·스크랩 작업이 완료된 뒤 반환되며, 응답에는 response_mode, completion_status, subtasks가 포함됩니다.

news, publication, award, social, profile 요청에 top-level url을 전달하면 검색 API를 건너뛰고 해당 URL만 수집합니다. company-homepage는 company.홈페이지 또는 url을 auto로 수집하고 실패하면 Firecrawl scrape를 사용합니다.

각 items 항목에는 결과 키워드 일치 조합에 따른 identity_label이 포함됩니다. 기존 scores 및 raw_payload_json은 유지되며, 뉴스 항목에만 thumb_urls와 primary_thumb_url이 항상 포함됩니다.

POST /v1/complete/linkClassification · POST /v1/complete/news · POST /v1/complete/publication · POST /v1/complete/award · POST /v1/complete/social · POST /v1/complete/profile · POST /v1/complete/company-homepage

`POST /v1/complete/linkClassification`

주어진 URL을 분석하여 google_drive, notion, file, webpage 타입으로 분류하고 크롤링 가능 여부를 반환합니다.

curl (Windows CMD)

curl -sS -X POST "https://crawl.jhkim3ispark.work/v1/complete/linkClassification" -H "Content-Type: application/json" -d "{\"url\":\"https://drive.google.com/file/d/1abc/view\"}"

POST/v1/complete/linkClassification

Request body

{
  "url": "https://drive.google.com/file/d/1abc/view"
}

Response shape

{
  "url": "https://drive.google.com/file/d/1abc/view",
  "classification": "google_drive",
  "crawlable": false
}

`POST /v1/complete/news`

Naver News와 Serper를 병렬 검색한 뒤 최종 기사 메타데이터를 static, respect_robots=false로 응답 예산 안에서 수집합니다. crawl_business_news=true이면 한국 기업뉴스 상위 결과만 auto로 본문을 확인하고, 모두 실패할 때 Firecrawl Search를 1회 사용합니다.

curl (Windows CMD)

curl -sS -X POST "https://crawl.jhkim3ispark.work/v1/complete/news" -H "Content-Type: application/json" -d "{\"person\":{\"이름\":\"홍길동\",\"직책\":\"대표\"},\"company\":{\"회사명\":\"예시회사\"},\"limit\":3,\"llm_confidence\":false}"

POST/v1/complete/news

Request body

{
  "person": {"이름": "홍길동", "영문명": "Gildong Hong", "직책": "대표"},
  "company": {"회사명": "예시회사", "업종": "AI 소프트웨어"},
  "limit": 5,
  "llm_confidence": false
}

Response shape

{
  "schema_version": "noteapp_complete/v1",
  "purpose": "news",
  "response_mode": "synchronous",
  "completion_status": "completed",
  "subtasks": [{"name": "naver_news_search", "status": "completed"}],
  "items": [
    {
      "title": "홍길동 예시회사 관련 뉴스",
      "source": "news.example",
      "article_url": "https://news.example/article",
      "snippet": "뉴스 요약",
      "published_at": "2026-06-25T00:00:00Z",
      "identity_label": "A",
      "thumb_urls": [],
      "primary_thumb_url": null,
      "scores": {"confidence": 0.35},
      "raw_payload_json": {"record": {}, "scores": {}}
    }
  ]
}

`POST /v1/complete/company-homepage`

회사 공식 홈페이지를 별도로 auto 크롤링하여 본문 미리보기와 이미지 URL을 반환합니다. 일반 오류나 빈 본문이면 Firecrawl scrape를 한 번 사용하고, 봇 챌린지는 우회하지 않습니다.

curl (Windows CMD)

curl -sS -X POST "https://crawl.jhkim3ispark.work/v1/complete/company-homepage" -H "Content-Type: application/json" -d "{"company":{"회사명":"이즈파크","홈페이지":"https://www.ispark.kr/"}}"

POST/v1/complete/company-homepage

Request body

{
  "company": {"회사명": "이즈파크", "홈페이지": "https://www.ispark.kr/"}
}

Response shape

{
  "schema_version": "noteapp_complete/v1",
  "purpose": "company-homepage",
  "completion_status": "completed",
  "subtasks": [{"name": "company_homepage_auto_crawl", "status": "completed"}],
  "items": [{
    "company_name": "이즈파크",
    "homepage_url": "https://www.ispark.kr/",
    "title": "이즈파크",
    "text_preview": "회사 홈페이지 본문...",
    "crawler": "static",
    "identity_label": "C",
    "scores": {"confidence": 0.7},
    "raw_payload_json": {"homepage_crawl": {}, "attempts": []}
  }]
}

`POST /v1/complete/publication`

저서 및 논문 범주를 함께 조회하여 책, 논문, 학술자료 후보를 수집하고, 출판물 중심의 evidence 목록으로 정리하여 반환합니다.

POST/v1/complete/publication

Request body

{
  "person": {"이름": "홍길동", "영문명": "Gildong Hong"},
  "company": {"회사명": "예시회사"},
  "limit": 5,
  "crawl_top": true,
  "crawler": "firecrawl",
  "llm_confidence": false
}

Response shape

{
  "schema_version": "noteapp_complete/v1",
  "purpose": "publication",
  "completion_status": "completed",
  "subtasks": [{"name": "person_evidence_publication", "categories": ["books", "publications"]}],
  "items": [
    {
      "title": "홍길동의 출판물",
      "publisher": "출판사 또는 학술 DB",
      "publication_year": "2024",
      "summary": "예시회사에서 축적한 경험을 정리한 책",
      "author_role": "저자 정보",
      "url": "https://source.example/item",
      "category": "books",
      "identity_label": "A",
      "scores": {"workflow_score": 0.82, "identity_match_score": 0.76},
      "raw_payload_json": {"candidate": {}, "primary_record": {}, "scores": {}}
    }
  ]
}

`POST /v1/complete/award`

상훈·수상 이력과 기관 단서를 함께 조회하여, 인물 또는 회사와 연결될 수 있는 수훈·수상 관련 evidence를 정리하여 반환합니다.

POST/v1/complete/award

Request body

{
  "person": {"이름": "홍길동", "영문명": "Gildong Hong"},
  "company": {"회사명": "예시회사"},
  "limit": 5,
  "llm_confidence": false
}

Response shape

{
  "schema_version": "noteapp_complete/v1",
  "purpose": "award",
  "completion_status": "completed",
  "subtasks": [{"name": "person_evidence_award", "categories": ["awards", "institutions"]}],
  "items": [
    {
      "award_name": "대통령 표창",
      "awarding_organization": "대한민국 상훈",
      "award_year": "2025",
      "description": "홍길동 예시회사 대표의 수상 내역",
      "url": "https://source.example/award",
      "identity_label": "A",
      "scores": {"workflow_score": 0.9, "identity_match_score": 0.88},
      "raw_payload_json": {"candidate": {}, "primary_record": {}, "scores": {}}
    }
  ]
}

`POST /v1/complete/social`

LinkedIn 후보 검색과 YouTube 검색을 함께 수행하여, 공개 프로필·채널·영상 단서를 사회적 활동 관점에서 묶어 반환합니다.

POST/v1/complete/social

Request body

{
  "person": {
    "이름": "홍길동",
    "영문명": "Gildong Hong",
    "직책": "대표",
    "부서": "전략",
    "이메일": "name at example dot com"
  },
  "company": {"회사명": "예시회사", "홈페이지": "https://example.com"},
  "limit": 5,
  "llm_confidence": false
}

Response shape

{
  "schema_version": "noteapp_complete/v1",
  "purpose": "social",
  "response_mode": "synchronous",
  "completion_status": "completed",
  "subtasks": [
    {"name": "linkedin_profile_finder", "status": "completed"},
    {"name": "youtube_search", "status": "completed"}
  ],
  "items": [
    {
      "platform": "LinkedIn",
      "title": "홍길동 - 예시회사",
      "url": "https://www.linkedin.com/in/example",
      "identity_label": "A",
      "scores": {"workflow_score": 0.91, "identity_match_score": 0.9},
      "raw_payload_json": {"candidate": {}, "primary_record": {}, "scores": {}}
    }
  ]
}

`POST /v1/complete/profile`

네이버 인물검색 결과 페이지를 Firecrawl로 수집하여 학력, 경력, 약력 등 프로필 필드를 추출합니다. 현재는 firecrawl crawler만 지원합니다.

POST/v1/complete/profile

Request body

{
  "person": {"이름": "홍길동", "영문명": "Gildong Hong"},
  "company": {"회사명": "예시회사"},
  "crawler": "firecrawl"
}

Response shape

{
  "schema_version": "noteapp_complete/v1",
  "purpose": "profile",
  "response_mode": "synchronous",
  "completion_status": "completed",
  "subtasks": [{"name": "naver_profile_crawl", "provider": "firecrawl"}],
  "items": [
    {
      "education": ["한성대학교"],
      "career_history": ["예시회사 대표"],
      "identity_label": "A",
      "scores": {"confidence": 0.7},
      "raw_payload_json": {"profile_crawl": {}, "scores": {}}
    }
  ],
}

LinkedIn Profile Finder Workflow

serperapifyranked candidates

POST /api/find/linkedin

POST/api/find/linkedin

Request body

{
  "query": "홍길동 예시회사",
  "person": {"이름": "홍길동", "영문명": "Gildong Hong"},
  "company": {"회사명": "예시회사"},
  "providers": ["serper"],
  "max_serp_queries": 4,
  "max_apify_queries": 6,
  "llm_confidence": false
}

Response shape

{
  "schema_version": "linkedin_profile_finder/v1",
  "query": "홍길동 예시회사",
  "providers": ["serper"],
  "best_match": {"url": "https://www.linkedin.com/in/example", "workflow_score": 0.91, "identity_label": "A"},
  "candidates": [{"url": "...", "identity_label": "A", "identity_match": {}, "records": []}],
  "operations": [],
  "endpoint": "/api/find/linkedin"
}

Scrap API

KyoboScholar/eArticle/KCI/RISS/DBpia/KoreaScience대한민국 상훈훈장/포장/표창기관/커리어

POST /api/scrap/person-evidence

POST /api/scrap/books · POST /api/scrap/publications · POST /api/scrap/honors · POST /api/scrap/awards · POST /api/scrap/institutions · POST /api/scrap/career

이 API는 일반 검색 API가 아닙니다. 고정 출처 검색 URL은 직접 crawler로 수집하고 Serper는 보완 탐색에만 사용합니다. identity matching으로 후보를 정렬하며, 필요하실 경우 Firecrawl로 상위 후보 페이지를 추가 수집할 수 있습니다. /api/find/* 하위의 레거시 별칭도 계속 지원합니다.

POST/api/scrap/person-evidence

Request body

{
  "query": "홍길동 예시회사",
  "person": {"이름": "홍길동", "영문명": "Gildong Hong"},
  "company": {"회사명": "예시회사"},
  "providers": ["serper"],
  "categories": ["books", "publications", "awards"],
  "direct_crawler": "auto",
  "crawl_top": true,
  "crawler": "firecrawl",
  "crawl_limit": 3,
  "llm_confidence": false
}

Response shape

{
  "schema_version": "person_evidence_finder/v1",
  "query": "홍길동 예시회사",
  "categories": ["books", "publications", "awards"],
  "best_by_category": {"books": {}, "publications": {}, "awards": {}},
  "candidates": [{"workflow_score": 0.82, "identity_match": {}, "primary_record": {}}],
  "identity_match": {},
  "llm_confidence": {},
  "operations": []
}

Search

Naver bundle

webnewsbook

POST /api/search/naver

{
  "type": "web",
  "query": "삼성전자 IR",
  "limit": 3,
  "intent": "company_profile",
  "target": "삼성전자 IR 공식 정보"
}

Google SERP bundle

serper

POST /api/search/google

{
  "provider": "serper",
  "query": "Samsung Electronics IR",
  "limit": 3
}

YouTube

youtube

POST /api/search/youtube

{
  "query": "OpenAI keynote",
  "limit": 3
}

WaterCrawl Search

watercrawlasync API

POST /api/search/watercrawl

{
  "query": "Samsung Electronics IR",
  "limit": 3
}

Crawl

Generic Crawl response updated 2026-07-28

POST /api/crawl

요청 body와 endpoint는 유지됩니다. 변경 전/후 응답은 다음과 같습니다.

Request body (변경 없음)

{
  "url": "https://example.com/article",
  "crawler": "auto",
  "respect_robots": true
}

변경 전 response

{
  "crawler": "auto",
  "elapsed_seconds": 5.012,
  "result": {
    "url": "https://example.com/article",
    "crawler": "stealth_browser",
    "title": "Example",
    "text": "...",
    "status_code": 200,
    "screenshot_path": null,
    "error": null,
    "text_length": 3,
    "text_preview": "..."
  }
}

변경 후 response (2026-07-28)

{
  "crawler": "auto",
  "response_mode": "api",
  "elapsed_seconds": 2.107,
  "result": {
    "url": "https://example.com/article",
    "crawler": "stealth_browser",
    "title": "Example",
    "text": "...",
    "status_code": 200,
    "error": null,
    "thumb_urls": [
      "https://cdn.example.com/hero.jpg"
    ],
    "primary_thumb_url":
      "https://cdn.example.com/hero.jpg",
    "text_length": 3,
    "text_preview": "..."
  }
}

변경 요약

변경 전: 이미지 URL 필드와 최상위 response_mode가 없었고, 서버 로컬 경로인 result.screenshot_path가 포함됐습니다.

변경 후: 원격 썸네일 URL 배열인 thumb_urls, 대표 URL인 primary_thumb_url, response_mode=api가 추가되고 screenshot_path는 제거됐습니다.

이미지 바이너리, multipart, base64는 반환하지 않습니다. 대표 이미지는 Vision Encoder 없이 메타데이터, DOM 위치, 표시 크기, URL 패턴으로 선택합니다.

Playwright

POST /api/crawl/playwright

{
  "url": "https://brief.jhkim3ispark.work/",
  "respect_robots": true,
  "llm_confidence": false
}

Playwright Stealth

POST /api/crawl/playwright-stealth

{
  "url": "https://brief.jhkim3ispark.work/",
  "respect_robots": true,
  "llm_confidence": false
}

Firecrawl

POST /api/crawl/firecrawl

{
  "url": "https://brief.jhkim3ispark.work/",
  "llm_confidence": false
}

WaterCrawl

POST /api/crawl/watercrawl

{
  "url": "https://brief.jhkim3ispark.work/",
  "llm_confidence": false
}

Stealth Browser

POST /api/crawl/stealth-browser

{
  "url": "https://brief.jhkim3ispark.work/",
  "respect_robots": true,
  "llm_confidence": false
}

Playwright then Firecrawl fallback

POST /api/crawl/playwright-firecrawl

{
  "url": "https://brief.jhkim3ispark.work/",
  "respect_robots": true,
  "base_delay_seconds": 2,
  "government_delay_seconds": 10
}

LinkedIn via Apify

endpoint openactor id required

POST /api/crawl/linkedin

APIFY_LINKEDIN_ACTOR_ID가 아직 설정되지 않아 이 엔드포인트는 현재 스모크 테스트를 완료하지 못했습니다. 공개 LinkedIn 프로필·회사·학교·쇼케이스 URL만 명시적으로 받습니다.

POST/api/crawl/linkedin

Request body

{
  "url": "https://www.linkedin.com/company/openai/",
  "llm_confidence": false
}

Response shape

{
  "crawler": "apify_linkedin",
  "endpoint": "/api/crawl/linkedin",
  "result": {
    "url": "https://www.linkedin.com/company/openai/",
    "text_preview": "...",
    "scores": {}
  }
}