diff --git a/api-reference/v2-openapi.json b/api-reference/v2-openapi.json index 0b8d221b6..e432e32ec 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 + } + } + } + } } } } @@ -10397,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": [ @@ -10427,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", @@ -10594,6 +10646,165 @@ "perRecord" ] }, + "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": { + "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", + "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": { + "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.",