From fddd080e1f70ef65cd1609ca07dc74fbf66813c5 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 14:03:43 +0000 Subject: [PATCH 1/2] docs(api): document Find Tools in the v2 OpenAPI spec Find Tools is a POST /v2/scrape call with provider "firecrawl" and capability "find-tools". The spec did not say so. - Mention Find Tools in the `alexandria` property description. - Add named request examples on POST /scrape: a plain URL scrape (kept first, so it stays the default) and a Find Tools call. - Add the FindToolsOptions and FindToolsData schemas. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01LKCJJgeohVR5dnd1MDBzAR --- api-reference/v2-openapi.json | 191 +++++++++++++++++++++++++++++++++- 1 file changed, 190 insertions(+), 1 deletion(-) diff --git a/api-reference/v2-openapi.json b/api-reference/v2-openapi.json index 0b8d221b6..2e28c4125 100644 --- a/api-reference/v2-openapi.json +++ b/api-reference/v2-openapi.json @@ -511,7 +511,7 @@ } } ], - "description": "Execute one or more catalogued provider tools instead of scraping a URL. Cannot be combined with `url`, `formats`, or other scrape options (400); the only allowed sibling keys are `timeout`, `origin`, and `integration`. Use the `x-request-id` request header as a client-chosen idempotency key (1 to 128 characters of letters, digits, `.`, `_`, `:`, `-`) — it is echoed back, and a completed request with the same key replays its original response and `scrape_id` instead of re-executing." + "description": "Execute one or more catalogued provider tools instead of scraping a URL. Cannot be combined with `url`, `formats`, or other scrape options (400); the only allowed sibling keys are `timeout`, `origin`, and `integration`. Use the `x-request-id` request header as a client-chosen idempotency key (1 to 128 characters of letters, digits, `.`, `_`, `:`, `-`) — it is echoed back, and a completed request with the same key replays its original response and `scrape_id` instead of re-executing. To browse the catalogue and read tool contracts for free, call Find Tools: set `provider` to `firecrawl`, `capability` to `find-tools`, and `options` to a `FindToolsOptions` object. The result `data` is a `FindToolsData` page." }, "domainTools": { "type": "boolean", @@ -521,6 +521,38 @@ } } ] + }, + "examples": { + "scrapeUrl": { + "summary": "Scrape a URL", + "value": { + "url": "https://example.com", + "formats": [ + "markdown" + ] + } + }, + "findTools": { + "summary": "Find Tools: browse the Alexandria catalogue (free)", + "description": "Calls the `firecrawl/find-tools` capability. It lists the tools of the `particle` provider and does not execute them. Follow an item's `next` call, or the page's `next` call, with another `alexandria` request.", + "value": { + "alexandria": { + "provider": "firecrawl", + "capability": "find-tools", + "options": { + "providers": [ + "particle" + ], + "level": "tools", + "expand": [ + "options", + "response" + ], + "limit": 2 + } + } + } + } } } } @@ -10594,6 +10626,163 @@ "perRecord" ] }, + "FindToolsOptions": { + "type": "object", + "description": "Options for the Find Tools capability (`provider: firecrawl`, `capability: find-tools`) in an `alexandria` call. Find Tools is free and does not execute the tools it returns. All fields are optional. Selectors narrow the results.", + "properties": { + "query": { + "type": "string", + "description": "Natural-language description of the data you need. Returns tools that match by meaning." + }, + "urls": { + "type": "array", + "description": "Website URLs. Returns tools whose provider matches the domain of a URL.", + "items": { + "type": "string", + "format": "uri" + } + }, + "providers": { + "type": "array", + "description": "Provider IDs to browse, e.g. `particle`.", + "items": { + "type": "string" + } + }, + "categories": { + "type": "array", + "description": "Category IDs to browse.", + "items": { + "type": "string" + } + }, + "groups": { + "type": "array", + "description": "Group IDs to browse.", + "items": { + "type": "string" + } + }, + "capabilities": { + "type": "array", + "description": "Exact capability IDs to return.", + "items": { + "type": "string" + } + }, + "level": { + "type": "string", + "enum": [ + "providers", + "groups", + "tools" + ], + "description": "The catalogue level to list in `items`." + }, + "expand": { + "type": "array", + "description": "Contract parts to include on each tool. Use `[\"options\", \"response\"]` for inputs and output shape, add `examples` for example payloads, or use `[]` for compact results.", + "items": { + "type": "string", + "enum": [ + "options", + "response", + "examples" + ] + } + }, + "limit": { + "type": "integer", + "minimum": 1, + "description": "Maximum number of items on the page." + }, + "offset": { + "type": "integer", + "minimum": 0, + "description": "Number of items to skip, for pagination." + } + } + }, + "FindToolsData": { + "type": "object", + "description": "One page of the Alexandria catalogue, returned in `data.alexandria[].data` for a Find Tools call. The call costs 0 credits.", + "properties": { + "level": { + "type": "string", + "enum": [ + "providers", + "groups", + "tools" + ], + "description": "The catalogue level of the items on this page." + }, + "items": { + "type": "array", + "description": "Catalogue entries at `level`. At the `tools` level, each item also has the tool fields of `DiscoveredTool` (`provider`, `capability`, `description`, `creditsCost`, `perRecord`), plus `options` and `response` when `expand` asks for them.", + "items": { + "type": "object", + "additionalProperties": true, + "properties": { + "id": { + "type": "string", + "description": "The entry's identifier." + }, + "name": { + "type": "string", + "description": "Human-readable name of the entry." + }, + "next": { + "allOf": [ + { + "$ref": "#/components/schemas/AlexandriaCall" + } + ], + "description": "An `alexandria` call that returns more detail for this entry." + }, + "execute": { + "type": "object", + "description": "The `provider` and `capability` to put in an `alexandria` call to execute this tool.", + "properties": { + "provider": { + "type": "string" + }, + "capability": { + "type": "string" + } + }, + "required": [ + "provider", + "capability" + ] + } + }, + "required": [ + "id", + "name" + ] + } + }, + "total": { + "type": "integer", + "minimum": 0, + "description": "Total number of entries that match the selectors." + }, + "next": { + "allOf": [ + { + "$ref": "#/components/schemas/AlexandriaCall" + } + ], + "nullable": true, + "description": "An `alexandria` call for the next page of this listing, or `null` on the last page." + } + }, + "required": [ + "level", + "items", + "total" + ] + }, "AlexandriaScrapeResponse": { "type": "object", "description": "Response returned when the request executed Alexandria provider tools instead of scraping a URL.", From 00bd705b95a4523dd50744148094a0ccbe0fc937 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 14:04:51 +0000 Subject: [PATCH 2/2] docs(api): reference Find Tools schemas from Alexandria calls and results Unreferenced component schemas do not render in Mintlify. Wire them in: - AlexandriaCall.options is now anyOf FindToolsOptions or any capability options object. - AlexandriaResult success data is now anyOf FindToolsData or any capability response. Both second branches accept the values that were valid before. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01LKCJJgeohVR5dnd1MDBzAR --- api-reference/v2-openapi.json | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/api-reference/v2-openapi.json b/api-reference/v2-openapi.json index 2e28c4125..e432e32ec 100644 --- a/api-reference/v2-openapi.json +++ b/api-reference/v2-openapi.json @@ -10429,7 +10429,18 @@ "options": { "type": "object", "default": {}, - "description": "Capability-specific options passed through to the provider tool." + "description": "Capability-specific options passed through to the provider tool. For Find Tools (`provider: firecrawl`, `capability: find-tools`), use `FindToolsOptions`.", + "anyOf": [ + { + "$ref": "#/components/schemas/FindToolsOptions" + }, + { + "type": "object", + "title": "Capability options", + "description": "Options for any other capability, as its contract defines them.", + "additionalProperties": true + } + ] } }, "required": [ @@ -10459,7 +10470,16 @@ "description": "Credits charged for this call." }, "data": { - "description": "The provider's response payload." + "description": "The provider's response payload. For Find Tools (`provider: firecrawl`, `capability: find-tools`), this is a `FindToolsData` page.", + "anyOf": [ + { + "$ref": "#/components/schemas/FindToolsData" + }, + { + "title": "Capability response", + "description": "The response of any other capability, as its contract defines it." + } + ] }, "records": { "type": "integer", @@ -10628,6 +10648,7 @@ }, "FindToolsOptions": { "type": "object", + "title": "Find Tools options", "description": "Options for the Find Tools capability (`provider: firecrawl`, `capability: find-tools`) in an `alexandria` call. Find Tools is free and does not execute the tools it returns. All fields are optional. Selectors narrow the results.", "properties": { "query": { @@ -10705,6 +10726,7 @@ }, "FindToolsData": { "type": "object", + "title": "Find Tools result", "description": "One page of the Alexandria catalogue, returned in `data.alexandria[].data` for a Find Tools call. The call costs 0 credits.", "properties": { "level": {