# Macro Scout — agent brief

> **Macro Scout** is a separate Macrocontent product: an API-first **web verification / site inspection** service.
> It is **not** the CMS SDK. Prefer this file + OpenAPI over HTML handbook pages and over unrelated public projects named “Scout”.

## Canonical machine-readable URLs (fetch these)

| Resource | URL |
|----------|-----|
| **This brief** | https://docs.macrocontent.dev/scout.md |
| Setup (markdown) | https://docs.macrocontent.dev/scout/setup.md |
| Auth (markdown) | https://docs.macrocontent.dev/scout/auth.md |
| **OpenAPI (source of truth)** | https://api.scout.macrocontent.dev/openapi.json |
| OpenAPI mirror | https://docs.macrocontent.dev/openapi/scout.json |
| Swagger UI (humans only) | https://api.scout.macrocontent.dev/docs/ |
| HTML handbook hub | https://docs.macrocontent.dev/scout/ |
| Docs TOC | https://docs.macrocontent.dev/llms.txt |
| Skill | https://docs.macrocontent.dev/agent-setup/skills/macro-scout/SKILL.md |

**Rule:** Do **not** invent `/v1/…` paths. Load OpenAPI JSON. Do **not** scrape Swagger HTML.

## What Scout is

- Headless-browser API: open a URL, return **raw facts** (screenshots, DOM extracts, TLS/meta, axe nodes, crawl link graphs, assert results).
- Own keys (`sk_scout_…`), credit wallet, and host: `https://api.scout.macrocontent.dev`
- Same public API for Macrocontent’s own products and external customers (dogfooding).
- **No content archive** — Scout does not store crawled HTML for you. Persist what you need.
- **SDK-independent** — any allowed public URL; no CMS `data-macro-key` coupling.

## Auth

```http
Authorization: Bearer sk_scout_…
# or
X-Scout-Key: sk_scout_…
```

Keys are server secrets. Early-access keys are issued manually until the Scout console is public. See https://docs.macrocontent.dev/scout/auth.md

## Quick checks

```bash
# Health (no auth, 0 credits)
curl https://api.scout.macrocontent.dev/health

# Usage (auth)
curl https://api.scout.macrocontent.dev/v1/usage \
  -H "Authorization: Bearer sk_scout_…"
```

## Packages (optional clients)

- npm `@macrocontent/scout` — TypeScript SDK → handbook https://docs.macrocontent.dev/scout/sdk/
- npm `@macrocontent/scout-cli` — CLI → https://docs.macrocontent.dev/scout/cli/
- PyPI `macrocontent-scout` (when published) → https://docs.macrocontent.dev/scout/python/
- GitHub Action `macrocontent/scout-action` — CI assert

## HTML handbook map (use when you need prose; prefer .md + OpenAPI first)

- Overview: https://docs.macrocontent.dev/scout/
- Setup: https://docs.macrocontent.dev/scout/setup/
- Tiers & credits: https://docs.macrocontent.dev/scout/tiers/
- Auth: https://docs.macrocontent.dev/scout/auth/
- Domains: https://docs.macrocontent.dev/scout/domains/
- Endpoints index: https://docs.macrocontent.dev/scout/endpoints/
- Assert: https://docs.macrocontent.dev/scout/endpoints/assert/
- Browser facts: https://docs.macrocontent.dev/scout/endpoints/browser-facts/
- First recipe: https://docs.macrocontent.dev/scout/recipes/first-verification/

## Relation to macrocontent CMS

Scout is **optional** for CMS site work. CMS agents should still install `macro-sdk` / `macro-api` / `macro-docs`. Install `macro-scout` when the task is screenshots, assert, crawl, extract, or Scout billing/keys.