Skip to content

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

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鈥檒l 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): type requiresAction as an object, add search toolDetail, fix DiscoveredTool required fields #1502

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e4eddc4
docs(api): type requiresAction as an object and add search toolDetail
claude Oct 2, 2026
4aab81b
docs(api): match DiscoveredTool required fields to toolDetail output
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
66 changes: 50 additions & 16 deletions api-reference/v2-openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -615,8 +615,36 @@
"example": "THIRD_PARTY_DATA_TERMS_REQUIRED"
},
"requiresAction": {
"type": "boolean",
"description": "Present when the team must take action (e.g. accept third-party data terms) before this request can be retried."
"type": "object",
"description": "Present with `THIRD_PARTY_DATA_TERMS_REQUIRED`. Tells you which provider terms an organization admin must accept before you retry this request.",
"properties": {
"type": {
"type": "string",
"enum": [
"accept_terms"
],
"description": "The action to take. Always `accept_terms`."
},
"terms": {
"type": "string",
"description": "The provider whose terms must be accepted."
},
"version": {
"type": "string",
"description": "The version of the provider's terms that must be accepted."
},
"url": {
"type": "string",
"format": "uri",
"description": "The dashboard page where a human (an organization admin) accepts the terms. Send this URL to a person; do not accept the terms automatically."
}
},
"required": [
"type",
"terms",
"version",
"url"
]
},
"chargeId": {
"type": "string"
Expand Down Expand Up @@ -4271,6 +4299,16 @@
"type": "boolean",
"description": "Include tool contracts whose provider matches the domains of the returned web results. Defaults to on when `alexandria` is among the sources; set `false` to disable, or `true` alone to add domain-matched tools beside ordinary web results. Free."
},
"toolDetail": {
"type": "string",
"enum": [
"compact",
"summary",
"full"
],
"default": "compact",
"description": "How much of each tool contract to return in `data.tools`. `compact` returns only `provider`, `capability`, and `description`. `summary` returns the full tool entry without `options` and `response`. `full` also returns `options`, `response`, and `examples`."
},
"categories": {
"type": "array",
"items": {
Expand Down Expand Up @@ -10492,12 +10530,12 @@
},
"DiscoveredTool": {
"type": "object",
"description": "A catalogued provider tool discovered via Alexandria, semantic search, or domain matching.",
"description": "A catalogued provider tool discovered via Alexandria, semantic search, or domain matching. The `toolDetail` request parameter sets which fields appear: `compact` returns only `provider`, `capability`, and `description`; `summary` adds the other fields except `options` and `response`; `full` also adds `options`, `response`, and `examples`.",
"additionalProperties": true,
"properties": {
"id": {
"type": "string",
"description": "The tool's identifier, formatted as `provider/capability`."
"description": "The tool's identifier, formatted as `provider/capability`. Omitted when `toolDetail` is `compact`."
},
"provider": {
"type": "string",
Expand All @@ -10509,7 +10547,7 @@
},
"name": {
"type": "string",
"description": "Human-readable name of the tool."
"description": "Human-readable name of the tool. Omitted when `toolDetail` is `compact`."
},
"description": {
"type": "string",
Expand All @@ -10518,15 +10556,15 @@
"creditsCost": {
"type": "integer",
"minimum": 0,
"description": "Credits charged per execution of this tool."
"description": "Credits charged per execution of this tool. Omitted when `toolDetail` is `compact`."
},
"perRecord": {
"type": "boolean",
"description": "Whether `creditsCost` is charged per record returned rather than per call."
"description": "Whether `creditsCost` is charged per record returned rather than per call. Omitted when `toolDetail` is `compact`."
},
"options": {
"type": "array",
"description": "The capability's accepted options.",
"description": "The capability's accepted options. Present only when `toolDetail` is `full`.",
"items": {
"type": "object",
"additionalProperties": true,
Expand All @@ -10545,7 +10583,7 @@
"response": {
"type": "object",
"additionalProperties": true,
"description": "Description of the shape of a successful response's `data`.",
"description": "Description of the shape of a successful response's `data`. Present only when `toolDetail` is `full`.",
"properties": {
"about": {
"type": "string",
Expand All @@ -10567,7 +10605,7 @@
},
"matchedBy": {
"type": "array",
"description": "Why this tool was surfaced.",
"description": "Why this tool was surfaced. Omitted when `toolDetail` is `compact`.",
"items": {
"type": "string",
"enum": [
Expand All @@ -10578,20 +10616,16 @@
},
"matchedUrls": {
"type": "array",
"description": "URLs whose domain matched this tool, when matched by domain.",
"description": "URLs whose domain matched this tool, when matched by domain. Omitted when `toolDetail` is `compact`.",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"provider",
"capability",
"name",
"description",
"creditsCost",
"perRecord"
"description"
]
},
"AlexandriaScrapeResponse": {
Expand Down
Loading