OmniScout Docs

엔드포인트

OmniScout Cloud API 엔드포인트 레퍼런스.

기본 URL: https://api.omniscout.xyz (또는 배포 URL).

모든 응답에는 디버깅 및 지원을 위한 request_id (UUID)가 포함됩니다.

POST /v0/search

자체 인덱스에 대한 시맨틱 검색.

요청

{
  "query": "rust async runtimes",
  "limit": 10
}
필드타입필수설명
querystring예검색 쿼리 (1–500자)
limitinteger아니요최대 결과 수 (1–20, 기본값 10)

응답

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "rust async runtimes",
  "count": 10,
  "hits": [
    {
      "url": "https://tokio.rs/",
      "title": "Tokio - An asynchronous Rust runtime",
      "snippet": "...",
      "source": "common_crawl",
      "score": 0.94,
      "rank": 1
    }
  ]
}

파이프라인

  1. Qdrant Cloud에 대한 하이브리드 벡터 + BM25 쿼리
  2. omniscout.engines.search.rerank으로 리랭크
  3. 점수가 포함된 상위 결과 반환

POST /v0/answer

웹 출처 기반 한 문장 답변.

요청

{
  "query": "What is the latest stable Rust version?"
}
필드타입필수설명
querystring예질문 (1–500자)

응답

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "What is the latest stable Rust version?",
  "answer": "Rust 1.85.0 is the latest stable release as of February 2025.",
  "status": "answered",
  "confidence": 0.87,
  "sources": [
    { "url": "https://blog.rust-lang.org/", "title": "Rust Blog" }
  ]
}

근거가 부족하면 status는 insufficient_information이고 answer는 null입니다.

파이프라인

  1. 상위 3개 인덱스 검색 + 리랭크
  2. URL 콘텐츠 추출 (omniscout 또는 trafilatura)
  3. Vercel AI Gateway로 합성
  4. 출처와 신뢰도가 포함된 답변 반환

세션 API 요약

POST /v0/search와 POST /v0/answer는 변경되지 않았습니다. 세션 엔드포인트는 동일한 URL 경로를 사용하지만, 호출자는 다음 사항에 유의해야 합니다:

주제이전현재
생성 응답session_id, expires_atsession_secret(저장 필요)과 capabilities도 포함
명령어 인증API 키 + x-session-secret동일 — 명시적으로 문서화; 시크릿은 생성 시에만 표시
컴퓨터 + 브라우저별도 세션 / VM컴퓨터 세션 ID가 두 경로 모두에서 동작
브라우저 액션navigate, screenshot, …변경 없음 (기본 액션 이름)
컴퓨터 액션computer.* 접두사변경 없음
스크린샷 / 파일Sprite상의 경로만바이트 다운로드는 GET /v0/sessions/{id}/files 사용
브라우저에 업로드Sprite상의 경로만먼저 POST /v0/sessions/{id}/files 후 upload 액션
만료생성 시점 기준 고정 TTL비활성 기반 슬라이딩 (기본 30분), 최대 2시간
세션 삭제API 키API 키만 (x-session-secret 불필요)

브라우저 세션

POST /v0/browser/sessions

브라우저 전용 Fly Sprite 세션 생성 (경량 Chromium VM).

인증: Authorization: Bearer os_live_...

{
  "request_id": "...",
  "session_id": "j57abc...",
  "type": "browser",
  "capabilities": ["browser"],
  "expires_at": 1710000000000,
  "sprite_url": "https://omniscout-sprites.fly.dev",
  "session_secret": "48-char-hex-secret-returned-once"
}

세션은 비활성 상태(SESSION_INACTIVITY_MS, 기본 30분)가 지속되거나 하드 TTL(SESSION_MAX_TTL_MS, 기본 2시간)에 도달하면 만료됩니다. 각 명령어마다 비활성 기간이 연장됩니다.

POST /v0/browser/sessions/{id}

데몬 명령어를 세션에 프록시.

헤더: Authorization: Bearer os_live_... 및 x-session-secret: <생성 시 받은 시크릿>

{
  "action": "navigate",
  "args": { "url": "https://example.com" },
  "session": "default"
}
필드타입필수설명
actionstring예브라우저 액션 이름 (예: navigate, snapshot, screenshot) — browser. 접두사 없음
argsobject아니요액션별 인수
sessionstring아니요데몬 탭 그룹 이름 (기본값 default)
timeout_msinteger아니요명령어 제한 시간 (밀리초)

capabilities: ["browser", "computer"]인 컴퓨터 세션도 같은 session_id를 사용해 이 경로에서 브라우저 명령어를 받습니다.

브라우저 전용 세션은 computer.* 액션을 400으로 거부합니다.

DELETE /v0/browser/sessions/{id}

세션을 삭제하고 Fly Machine을 해제.

헤더: Authorization: Bearer os_live_...만 (세션 시크릿 불필요).

컴퓨터 세션

통합 Fly Sprite 세션은 같은 VM에서 데스크톱 자동화와 브라우저 자동화를 모두 포함합니다.

메서드경로설명
POST/v0/computer/sessions통합 Sprite 생성 (capabilities: ["browser", "computer"])
POST/v0/computer/sessions/{id}명령어 프록시 (computer.* 액션)
DELETE/v0/computer/sessions/{id}세션 삭제 (API 키만)

명령어용 헤더: Authorization + x-session-secret (브라우저 명령어와 동일).

컴퓨터 명령어는 computer. 접두사를 사용합니다:

{
  "action": "computer.type",
  "args": { "text": "hello" },
  "session": "default"
}
필드타입필수설명
actionstring예computer.로 시작해야 함 (예: computer.type, computer.screenshot)
argsobject아니요액션별 인수
sessionstring아니요데몬 세션 이름 (기본값 default)

같은 session_id가 /v0/browser/sessions/{id}를 통한 브라우저 명령어에도 동작합니다 — 두 번째 브라우저 세션이 필요 없습니다.

세션 파일

Sprite 파일시스템의 파일을 업로드 및 다운로드.

메서드경로설명
POST/v0/sessions/{id}/files멀티파트 업로드 (file 필드, 선택적 session 이름)
GET/v0/sessions/{id}/files?path=...파일 바이트 다운로드
GET/v0/sessions/{id}/files?path=...&format=base64base64 페이로드가 포함된 JSON으로 다운로드

두 경로 모두 Authorization과 x-session-secret이 필요합니다.

업로드 — file 필드가 포함된 multipart/form-data. 선택적 session 필드는 데몬 세션 이름을 설정 (기본값 default).

curl -X POST "https://api.omniscout.xyz/v0/sessions/$SESSION_ID/files" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -F "file=@./document.pdf"

다운로드 — 쿼리 매개변수 path (screenshot 같은 명령어 결과에서 확인):

curl "https://api.omniscout.xyz/v0/sessions/$SESSION_ID/files?path=/tmp/...&format=base64" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET"

일반적인 스크린샷 워크플로:

  1. {"action":"screenshot","args":{}}와 함께 POST /v0/browser/sessions/{id}
  2. GET /v0/sessions/{id}/files?path={반환된_경로}&format=base64

일반적인 브라우저 업로드 워크플로:

  1. 파일 바이트와 함께 POST /v0/sessions/{id}/files
  2. {"action":"upload","args":{"selector":"@e1","files":["/path/from/step-1"]}}와 함께 POST /v0/browser/sessions/{id}

OpenAPI

전체 OpenAPI 3.1 스펙은 다음에서 확인할 수 있습니다:

스펙은 Zod 경로 스키마에서 생성되며 실시간 API와 동기화됩니다.

인증

OmniScout Cloud API 키를 생성하고 사용하기.

SDK 및 예제

OmniScout Cloud용 Python, TypeScript SDK와 curl.

On this page

POST /v0/search요청응답파이프라인POST /v0/answer요청응답파이프라인세션 API 요약브라우저 세션POST /v0/browser/sessionsPOST /v0/browser/sessions/{id}DELETE /v0/browser/sessions/{id}컴퓨터 세션세션 파일OpenAPI