Scout Developer Guide

Choose the right Scout surface before you run.

Use this guide when you need operating judgment: local versus hosted, CLI versus HTTP, workdir setup, auth headers, and what to inspect after a run. Hosted API examples live in this guide; local Swagger docs remain available only when running Scout locally for exact request and response schemas.

Surfaces

Pick the interface that matches the job.

Local CLI

Best for repeatable local runs, scripts, saved workdirs, and quick product exports.

scout scrape https://example.com
scout products books --site books.toscrape.com

Local HTTP service

Best when agents, notebooks, or local apps need a controlled acquisition service.

export SCOUT_API_KEY="dev-key"
scout serve
curl -H "X-API-Key: dev-key" http://127.0.0.1:8421/health

Hosted beta API

Best for approved testers who need a convenience endpoint with finite hosted credits.

curl "$SCOUT_HOSTED_BASE_URL/v1/hosted/me" \
  -H "Authorization: Bearer $SCOUT_HOSTED_API_KEY"

scout hosted-curl --base-url "$SCOUT_HOSTED_BASE_URL" \
  --endpoint scrape --url https://example.com

Claude/Codex skill backend

Best when an agent needs Scout as a local evidence-preserving acquisition tool.

Use Scout locally, then inspect records and source evidence before trusting the answer.

Auth and workdir

Keep credentials separate from artifacts.

SCOUT_WORKDIR

Set `SCOUT_WORKDIR` so local runs write artifacts somewhere predictable.

export SCOUT_WORKDIR="$PWD/scout-runs"

X-API-Key

Local authenticated routes use the `X-API-Key` header. Do not expose local Scout without setting a non-default key.

curl -X POST http://127.0.0.1:8421/scrape \
  -H "X-API-Key: dev-key" \
  -H "Content-Type: application/json"

Authorization: Bearer

Hosted beta routes use Bearer tokens. Hosted keys are finite-credit credentials, not unlimited access. Public hosted deployments should enable SCOUT_PUBLIC_HOSTED_ONLY=true so consumers only call /v1/hosted/*.

curl "$SCOUT_HOSTED_BASE_URL/v1/hosted/scrape" \
  -H "Authorization: Bearer $SCOUT_HOSTED_API_KEY"

Secrets

Put local secrets in `.env.local` or shell environment. Do not put keys in screenshots, issue text, public repos, or run artifacts.

Artifacts

A successful run is inspectable after the command exits.

records.json

Structured records from the run.

source_pages.json

Source registry with provider, URL, status, timestamps, and hashes.

blocked_pages.json

Blocked or failed pages with reasons where available.

extraction_report.md

Human-readable summary for review and handoff.

Boundaries

Know what this beta does not promise.

No unlimited hosted crawling

Hosted beta has finite standard credits, browser credits, page limits, retention limits, and concurrency limits.

No certified legacy /app UI claim

The beta launch surface is CLI, HTTP API, Docker, skill docs, hosted beta API, this website, and artifact evidence.

Hosted API examples live in this guide; local Swagger docs remain available only when running Scout locally

Use this guide for hosted API examples and operating context. When Scout runs locally, Swagger remains available at `/docs` for exact endpoint schemas.

Public launch remains blocked

License, legal, registry, Stripe real test-mode, dependency audit, and publishing gates still need closure before broad public launch.