docs(api): type requiresAction as an object, add search toolDetail, fix DiscoveredTool required fields

[claude]

Requested by Micah Stairs · Slack thread

Before: The POST /scrape 403 THIRD_PARTY_DATA_TERMS_REQUIRED response typed requiresAction as a boolean. The API sends an object, so clients that read the spec did not know where to find the terms URL. The POST /search request schema did not list toolDetail, so users could not find out how to get more detail in data.tools. The DiscoveredTool schema also required id, name, creditsCost, and perRecord. With the default toolDetail (compact), the API does not return these fields.

After: requiresAction is an object with type (accept_terms), terms (the provider), version, and url. The url description says it is the dashboard page where a human accepts the terms. POST /search lists toolDetail (compact, summary, full, default compact) and explains what each value returns in data.tools. DiscoveredTool now requires only provider, capability, and description, which are the fields that every level returns. Each of the other fields says which toolDetail levels return it.

How: I changed only api-reference/v2-openapi.json. Sources in firecrawl/firecrawl at e76d5b6:

• requiresAction shape: apps/api/src/lib/exchange.ts:680-687 (getter) and exchange.ts:648-650 (the URL is <dashboard>/app/alexandria/<provider>). response() at exchange.ts:689-696 sends it in the 403 body.
• toolDetail param and default: apps/api/src/controllers/v2/types.ts:2553. The search controller passes it at controllers/v2/search.ts:411.
• Effect on data.tools and on DiscoveredTool:
  • apps/api/src/search/alexandria.ts:214-221: compact keeps only provider, capability, and description.
  • alexandria.ts:111-116: other levels add id, matchedBy, and matchedUrls.
  • services/alexandria/contracts.ts:71-79: summary drops options and response.
  • alexandria.ts:68-71 and :85: full expands options, response, and examples (contracts.ts:51-70).

This is the only requiresAction in the spec. The agent endpoint uses a different requiresAction shape (controllers/v2/types.ts:1748), and crawl errors also carry it (controllers/v2/crawl-errors.ts:92). The spec does not document either one yet, so I left them for a follow-up. I validated the JSON with python3 -m json.tool. I did not change localized files.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LKCJJgeohVR5dnd1MDBzAR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
firecrawl	🟢 Ready	View Preview	Oct 2, 2026, 2:06 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[claude]

The failing check is "Locale literals and extraction-hostile markdown". The step that fails is "Keep API literals untranslated" (scripts/check-locale-api-literals.sh).

This failure is not caused by this PR. The check fails the same way on main at d8ab99e. The likely cause is the locadex translations in #1500. Some localized pages use translated API identifiers. Clear examples:

• es/features/change-tracking.mdx:44 uses seguimientoDeCambios
• es/webhooks/events.mdx:67 uses rastreo.iniciado
• pt-BR/v0/sdks/node.mdx:66 uses dadosRaspados

This PR changes only English source files and adds no findings. There is no fix yet. The repo's CLAUDE.md says the translation pipeline owns localized files, so this PR does not edit them.

---

Generated by Claude Code