Agents
SKILL.md onboarding

SKILL.md onboarding

SuperScraper serves a machine-readable, self-onboarding skill document, no signup flow required to discover the API. It is the fastest path for an autonomous agent to go from "found this API" to "made a successful call."

curl -s https://api.superscraper.dev/agent-onboarding/SKILL.md
GET /agent-onboarding             (same content as SKILL.md)
GET /agent-onboarding/SKILL.md    curated quick-start (this page mirrors it)
GET /agent-onboarding/MANIFEST.md full agent skill manifest (every endpoint, in depth)

Both routes are public, no API key required, and mounted before the /v1/* auth guard, served as text/markdown with Cache-Control: public, max-age=3600.

What SKILL.md covers

  1. Get a key, POST /v1/keys/provision, no sign-in, returns a free-tier key.
  2. Core calls, /v1/scrape, /v1/extract, /v1/search, plus a quick-reference table (/v1/map, /v1/crawl + /v1/jobs/:id, /v1/batch, /v1/parse).
  3. Hosted MCP is not available. Use the REST API. Local stdio MCP is developer-only.
  4. CLI, the init / scrape / extract / pull commands. The CLI is not published, so it has to be built from a source checkout.
  5. Machine-readable index, /llms.txt, /llms-full.txt, /openapi.json, /agent-onboarding/MANIFEST.md.
  6. Conventions, every error is { "error": "..." } with a 4xx/5xx status; scrape/extract results carry _confidence, _extraction_method, _provenance; default extraction is deterministic (JSON-LD) and free.

Why this exists

Most APIs make an agent read prose documentation and guess at request shapes. SKILL.md is written for an LLM to act on directly: short, example-first, and self-contained enough that an agent can provision a key and make its first call from this one file, without crawling the rest of the docs site.

# The whole bootstrap loop, from zero
curl -s https://api.superscraper.dev/agent-onboarding/SKILL.md   # read the skill
curl -s -X POST https://api.superscraper.dev/v1/keys/provision \
  -H "Content-Type: application/json" -d '{"label":"my-agent"}'  # get a key
curl -s -X POST https://api.superscraper.dev/v1/scrape \
  -H "x-api-key: $SS_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'                             # first call

MANIFEST.md, the full reference

GET /agent-onboarding/MANIFEST.md serves the long-form reference (every endpoint, in depth) from the same source the superscraper-mcp package and the Claude Code plugin ship internally. If the manifest file is missing from a deploy bundle, this route degrades to the curated SKILL.md quick-start rather than erroring, you always get something useful back.

Further reading

  • Quickstart, curl → key → first scrape, for humans
  • Authentication, the two auth header formats and key lifecycle
  • MCP Server, full tool reference for Claude Desktop / Claude Code
  • llms.txt, the condensed and full plain-text API references
MCP Serverllms.txt