클라우드 API 개요

검색, 근거 기반 답변, 브라우저/컴퓨터 세션을 위한 OmniScout Cloud API.

OmniScout Cloud는 시맨틱 검색, 근거 기반 답변, 원격 브라우저/컴퓨터 세션을 위한 호스팅 API입니다. 로컬 CLI와 동일한 검색 및 리랭킹 파이프라인을 사용하며, DuckDuckGo 대신 자체 Qdrant 인덱스로 지원됩니다.

제공 기능

기능	엔드포인트	설명
검색	`POST /v0/search`	자체 인덱스에 대한 하이브리드 벡터 + BM25 검색, omniscout로 리랭크
답변	`POST /v0/answer`	출처와 신뢰도가 포함된 검색 → 추출 → AI 합성
브라우저 세션	`POST /v0/browser/sessions`	경량 브라우저 전용 Sprite (`capabilities: ["browser"]`)
컴퓨터 세션	`POST /v0/computer/sessions`	브라우저 + 데스크톱 통합 Sprite (`capabilities: ["browser", "computer"]`)
세션 파일	`POST/GET /v0/sessions/{id}/files`	Sprite에 업로드 또는 Sprite에서 다운로드

세션 호출자에 대한 변경 사항

POST /v0/search와 POST /v0/answer는 변경되지 않았습니다.

세션 엔드포인트는 이전과 동일한 경로를 사용하며, 차이점은 다음과 같습니다:

생성 응답의 session_secret 저장 — 모든 명령어 및 파일 요청마다 x-session-secret으로 필요.
컴퓨터 세션은 통합됨 — 하나의 session_id로 브라우저 명령어(POST /v0/browser/sessions/{id})와 컴퓨터 명령어(POST /v0/computer/sessions/{id})를 모두 지원. 컴퓨터 세션이 이미 있으면 별도 브라우저 세션이 필요 없음.
액션 이름 — 브라우저 액션은 기본 이름 사용 (navigate, screenshot); 컴퓨터 액션은 computer. 접두사 사용 (computer.type, computer.screenshot).
파일 경로는 새로 추가됨 — 파일을 업로드하거나 Sprite에서 스크린샷/PDF를 다운로드하려면 /v0/sessions/{id}/files 사용.
만료는 비활성 기반 — 각 명령어마다 세션이 연장됨 (기본 30분 유휴, 최대 2시간). 생성 시점 기준 고정 TTL로 가정하지 마세요.

# 1. 통합 컴퓨터 세션 생성 (API 키만)
curl -X POST https://api.omniscout.xyz/v0/computer/sessions \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY"

# 응답에 session_id, session_secret, capabilities: ["browser","computer"] 포함

# 2. 같은 세션에 브라우저 명령어 (두 헤더 모두)
curl -X POST "https://api.omniscout.xyz/v0/browser/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action":"navigate","args":{"url":"https://example.com"}}'

# 3. 같은 세션에 컴퓨터 명령어
curl -X POST "https://api.omniscout.xyz/v0/computer/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action":"computer.type","args":{"text":"hello"}}'

빠른 시작

api.omniscout.xyz에서 가입 (또는 배포 URL).
대시보드에서 API 키 생성 — 키는 os_live_로 시작.
첫 요청 전송:

curl -X POST https://api.omniscout.xyz/v0/search \
  -H "Authorization: Bearer os_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtimes", "limit": 10}'

CLI vs 클라우드

	CLI	Cloud API
검색 소스	DuckDuckGo + 로컬 리랭크	자체 Qdrant 인덱스 + omniscout 리랭크
답변	로컬 Probe Zero Mini	Vercel AI Gateway (모델 설정 가능)
브라우저	로컬 Chrome / Playwright	omniscout 데몬이 포함된 Fly Sprite
인증	없음 (로컬 실행)	Bearer API 키 (`os_live_...`)
결제	무료, 오픈소스	무료 티어 + 유료 플랜

로컬 CLI는 변경되지 않았습니다. 클라우드는 추가 옵션입니다 — 배포 환경에 맞는 쪽을 사용하세요.

아키텍처

Client → Vercel gateway (/v0/*) → Fly search worker → Qdrant Cloud
                                  → Vercel AI Gateway (answers)
                                  → Fly Sprites (browser/computer)

Vercel은 대시보드, API 게이트웨이, Clerk 인증, Convex (키, 사용량, 세션)를 호스팅.
Fly.io는 검색 워커, 인덱서, Sprite를 실행.
Qdrant Cloud는 자체 검색 인덱스 저장 (Common Crawl + StormCrawler, 추가 수집).

다음 단계

인증 및 API 키 — 키 생성 및 사용 방법
엔드포인트 — 모든 경로의 요청/응답 스키마
요금 제한 — 일일 할당량 및 티어
OpenAPI 레퍼런스 — 대화형 API 탐색기