Docs for Agents

These docs are written to be read by AI agents as well as people. If you're building an agent that uses scanr.ai, or you are one, this page lists the machine-readable versions and how to use them.

Where an agent should start

Each page also has a Copy page button (top right) that copies its markdown, with a menu to open the page in Claude or ChatGPT.

Agent Skill

The skill at /skill.md is a single SKILL.md file in the Agent Skills format. It teaches an agent the scan model, the payload rules that trip models up, the natural-language workflow and the endpoints worth calling, in a few pages, and points to these docs for the rest.

Install it for Claude Code:

mkdir -p ~/.claude/skills/scanrcurl -s https://api-docs.scanr.ai/skill.md -o ~/.claude/skills/scanr/SKILL.md

Put it in .claude/skills/scanr/ inside a repository instead to share it with a team. Agents without skill support can take the same file as part of their system prompt.

MCP, REST or both?

Both use the same token, plan and data. An MCP-connected assistant with the Agent Skill installed covers most interactive use.

OpenAPI spec

/openapi.json is an OpenAPI 3.1 document for the public API: only the endpoints an API token can call, with their full request and response schemas. Its server is https://scanr.ai and every path starts with /api/v2. Use it to:

• generate a client with a tool such as openapi-generator or openapi-typescript;
• import the API into Postman, Insomnia or Bruno;
• turn endpoints into agent tools: each operation's request schema is a ready-made tool input schema. Pick the handful your agent needs rather than all of them; see Build a Scanning Agent.

The spec is generated from the running API, so it changes when the API does.

Rules for agents

• Scan, don't crawl. One scan answers "which stocks…?" for the whole market. Never loop over tickers calling per-ticker endpoints to filter them yourself.
• Get a payload, don't write one. Generate it with natural_scan / POST /scan/natural, or use one the user exported from the scanr.ai scanner (Filters → Export filters), then edit it with refine. Hand-written payloads are fine for small edits, but check plot names and comparators against Building Scan Payloads.
• Show the reasoning. Before running a generated scan, tell the user what it will screen for (reasoning.summary). It catches misreadings early.
• Keep payloads. A payload is a reusable asset. Re-running it costs no AI credits.
• Read errors. A 400 names the field that's wrong; fix that field rather than regenerating the whole payload. A 429 means wait, not retry.
• Mind the clock. A scan during market hours reads provisional bars. Say so when reporting intraday results. See Coverage & Freshness.
• Use a dedicated token with the read scope only, and never echo it back into a conversation.