Improve API subcommand experience

[patrikbraborec]

Background

Follow-up to #1075 (the apify api subcommand).

Smithery's MCP vs CLI Is the Wrong Fight benchmarked 756 runs of agents against raw APIs, CLIs, and MCP. Findings relevant to our CLI:

• Priors are unreliable for APIs that aren't well-represented in training data. Blind API calling success was 91.7% on GitHub but 16.7% on Linear and 41.7% on a niche REST API. Apify's API is closer to the latter.
• Specs buy correctness: giving agents OpenAPI/schema lifted success from 53% → 76%.
• Descriptions beat hierarchy: a tree without descriptions performed identically to a flat list; adding descriptions + aliases raised success from 45.8% → 79%.
• Search is the biggest multiplier at scale: on an 826-tool catalog, adding a search primitive took Sonnet from 67% → 92%.

Our api-endpoints.json has ~160 entries exposed only as a flat list with method + path + one-line summary. Agents using apify api today must dump the full list to discover anything, and there's no way to ask "what parameters does this endpoint take?" short of leaving the CLI.

Proposed features

1. --search <query> on --list-endpoints

Filter the endpoint list by a space-separated query. Each token must appear (case-insensitive) in method + path + summary.

apify api --list-endpoints --search "actor run"
apify api --list-endpoints --search "GET dataset"

Simple substring match is sufficient at ~160 endpoints; fuzzy matching is overkill.

2. --describe <endpoint>

Print what an agent needs to call a single endpoint without leaving the CLI.

apify api --describe actor-runs/{runId}
apify api --describe /v2/actor-runs/{runId}

Normalize the input the same way the main command does (strip leading /, strip v2/ prefix), then:

• Exact match: print every HTTP method on that path, its summary, path params extracted from {…} tokens, and a link to https://docs.apify.com/api/v2.
• No match: print the top N substring matches as "did you mean" suggestions.

3. 404 recovery suggestions

When a real request returns 404, run the same closest-match lookup against the attempted path and print suggestions alongside the existing --list-endpoints hint. Turns a blind-guess failure into a self-correction loop.

Out of scope for this issue

• Enriching api-endpoints.json with richer descriptions, parameter schemas, and example payloads — a separate content task that would further raise agent success but is independent of the CLI plumbing.
• Shipping a native MCP server for the Apify API. The article's top finding is that native MCP still beats a well-designed CLI for agent task success (91.7% vs 83.3%; CLI used 2.9× tokens, 2.4× longer). Worth tracking separately.

Acceptance criteria

• apify api --list-endpoints --search "..." filters output; tests cover hits, misses, and multi-token queries.
• apify api --describe <path> prints methods/summary/path params for exact matches and suggestions for misses; tests cover both.
• 404 responses from real requests include suggested endpoints.
• yarn update-docs regenerated and committed.