Skip to content

docs(api): document Find Tools in the v2 OpenAPI spec #1503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
micahstairs merged 2 commits into from
Oct 2, 2026
Merged

docs(api): document Find Tools in the v2 OpenAPI spec #1503

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fddd080
docs(api): document Find Tools in the v2 OpenAPI spec
claude Oct 2, 2026
00bd705
docs(api): reference Find Tools schemas from Alexandria calls and res…
claude Oct 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
217 changes: 214 additions & 3 deletions api-reference/v2-openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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
}
}
}
}
}
}
}
Expand Down Expand Up @@ -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": [
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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.",
Expand Down
Loading