Exa: point preset at live OpenAPI spec instead of stale GitHub master

[kjhq]

Problem

Adding an Exa connection shows Degraded on the connection health check:

Degraded: {"requestId":"...","error":"The Exa Research API has been retired and is no
longer available. ...","tag":"RESEARCH_RETIRED"}

Root cause: the exa preset in packages/plugins/openapi/src/sdk/presets.ts
fetches its spec from:

https://raw.githubusercontent.com/exa-labs/openapi-spec/refs/heads/master/exa-openapi-spec.yaml

That repo was last synced 2026-04-03. Exa retired its /research endpoint in
April 2026 (see https://exa.ai/docs/changelog). The stale spec still declares
POST /research/v0/tasks, GET /research/v0/tasks, and
GET /research/v0/tasks/{id}. research-tasks-list is the only cheap
non-mutating GET in that spec, so the health-check candidate ranking picks it
automatically → the probe hits the retired endpoint → connection reports
Degraded. The API key is valid; /search works fine.

The staleness also exposes dead tools (research-tasks-create,
research-tasks-list) and misses newer API surface (Monitors, Agent,
publication category, deep-reasoning/deep-lite search types).

Fix

Exa hosts canonical, always-current spec files on their docs site:

• https://exa.ai/docs/exa-spec.yaml
• https://exa.ai/docs/exa-spec.json

("These links always point at the specs served by this docs deployment." —
https://exa.ai/docs/reference/openapi-spec)

Point the exa preset at the live YAML:

- url: "https://raw.githubusercontent.com/exa-labs/openapi-spec/refs/heads/master/exa-openapi-spec.yaml",+ url: "https://exa.ai/docs/exa-spec.yaml",

No other code references the exa spec URLs; no test fixtures snapshot them.

Why the live spec

Item	stale GitHub master (Apr 3 2026)	live spec (May 2026)
/research/v0/tasks* (retired Apr 2026)	present → Degraded probe	removed
research paper category	present	replaced by publication
pdf, github categories (deprecated)	in enum	removed
search types	neural/auto/fast/deep/deep-reasoning/instant	+ deep-lite
Monitors API	absent	present
Agent API (/agent/runs)	absent	present
GET /v0/teams/me	absent	present → healthy probe, no cost

Side benefit: with the live spec, health-check ranking can pick the cheap
GET /v0/teams/me instead of a POST that would bill per probe.

Notes:

• Deprecated-but-accepted params (livecrawl, numSentences,
  startCrawlDate, highlightScores, resolvedSearchType) still appear in
  the live spec — Exa keeps them for compatibility and documents them as
  ignored. A follow-up cleanup in exa-labs/openapi-spec would be a separate
  PR.
• exa-websets preset keeps its GitHub URL: Exa's docs site only hosts the
  public + team-management specs, and the websets spec has no deprecated paths.
• Prefer GitHub? So do we — exa-labs/openapi-spec hasn't been synced since
  April (several sync PRs sit unmerged). We'd happily point at a maintained
  GitHub source if Exa resumes syncing it.

Verification

1. bun install.
2. bun run format then bun run format:check.
3. bun run lint and bun run typecheck.
4. bun run test (turbo, e2e excluded).
5. curl -sI https://exa.ai/docs/exa-spec.yaml → 200.
6. Add an Exa connection with an API key → health check healthy, no Degraded.
7. Tool catalog includes Monitors/Agent tools, no research-* tools.

All gates pass locally: format/lint/typecheck clean, @executor-js/plugin-openapi
283/283 tests pass. Unrelated failures observed locally were flaky
(@executor-js/sdk oauth/platform-view pass on rerun; @executor-js/cli
suites failing to load is a local Cannot find package 'bun' resolution
quirk — the tests themselves pass).

Changeset

.changeset/exa-live-spec.md — @executor-js/plugin-openapi patch.

[kjhq]

Closing — testing locally before resubmitting.