Skip to main content
The @api-explorer tool maps an API from edge to edge starting from just its base URL. It is the agent’s faithful partner for answering “what does this API have and how does it work?” — it discovers the paths, parameters, headers, models, authentication and behavior on its own, without you hand-feeding endpoints. It is read-only (only GET/HEAD/OPTIONS plus the GraphQL introspection query, a pure read) and keyless, so it fans out concurrently and never triggers the confirmation policy.
Point it at an API you need to integrate with and let the agent do the reading: @api-explorer discover {url} returns the whole map, then @api-explorer endpoint {url, path} gives you the exact contract to call.

​
Usage

<tool_call name="@api-explorer" args='{"cmd":"discover","args":{"url":"https://api.example.com"}}' />
<tool_call name="@api-explorer" args='{"cmd":"spec","args":{"url":"https://petstore3.swagger.io/api/v3/openapi.json","filter":"/pet"}}' />
<tool_call name="@api-explorer" args='{"cmd":"endpoint","args":{"url":"https://api.example.com","path":"/pet/{petId}","method":"get"}}' />
<tool_call name="@api-explorer" args='{"cmd":"security","args":{"url":"https://api.example.com"}}' />
<tool_call name="@api-explorer" args='{"cmd":"graphql","args":{"url":"https://api.example.com/graphql"}}' />
The LLM invokes @api-explorer automatically when it needs to understand an API before calling it. Start with discover; the tool tells you where to go next.

​
Subcommands

SubcommandWhat it does
discoverStart here. Multi-vector recon from a base URL: finds the spec, fingerprints tech and auth, probes OIDC, Actuator, health/metrics, versions and GraphQL, then lists the endpoints.
specFetches and fully parses a known OpenAPI 2.0/3.x spec into a catalog of every path, method, parameter, model and security scheme, grouped by tag.
endpointDeep-dives a single operation with $ref-resolved schemas: every parameter with type and constraints, the request body model expanded to its fields, response models per status code, and the required security.
securitySecurity posture report: TLS, security headers, a live CORS preflight, cookie flags, auth challenge, OIDC discovery and framework fingerprint.
graphqlRuns a GraphQL schema introspection query and summarizes the queries, mutations, subscriptions, input types and enums.

​
Discovery is multi-vector

Discovery does not just guess at /openapi.json. From the base URL it tries, concurrently, every angle a spec can hide behind:
1

~20 well-known spec locations

/openapi.json, /swagger.json, /v3/api-docs, /swagger/v1/swagger.json, /.well-known/openapi.json and more — in both JSON and YAML.
2

Embedded in the docs page

The machine spec URL extracted from inside a rendered Swagger-UI / ReDoc / RapiDoc / Stoplight page — the common case where the spec lives at a non-standard path only the HTML knows.
3

/.well-known manifests

OpenID Connect discovery (openid-configuration → the real auth endpoints) and the LLM plugin manifest (ai-plugin.json → its spec URL).
4

Operational surface

Health/readiness/metrics endpoints and Spring Boot Actuator — /actuator/mappings enumerates every route a Spring app serves.
5

Versions & GraphQL

API version roots (/v1../v3, /api/v1..) and a GraphQL endpoint probe.
When several specs are found, the richest one (most paths) wins.

​
Arguments

ArgumentDescriptionDefault
cmddiscover · spec · endpoint · security · graphqldiscover
urlAPI base URL, a direct spec URL, or a docs-page URL (required)(required)
pathThe API path to deep-dive, e.g. /pet/{petId} (endpoint only)(required for endpoint)
methodHTTP method to focus on (endpoint only)(all methods on the path)
filterOnly show paths containing this substring (spec)(all)
tagOnly show operations with this tag (spec)(all)
limitMax endpoints to list (spec)400
formatmarkdown (default) or json (machine-readable inventory) for discover/specmarkdown
A bare URL is treated as discover. The spec-taking subcommands (spec, endpoint) accept a base URL and will auto-locate the spec for you — you rarely need the exact spec path.

​
Deep-dive with $ref resolution

endpoint resolves $ref pointers (into components/definitions) with cycle detection, so you see the actual model fields, enums and constraints instead of an opaque #/components/schemas/Pet. allOf/oneOf/anyOf are flattened for display. 
## POST /pet

operationId: `addPet`
Add a new pet to the store.

### Request body (required)

- application/json → Pet
  - id: integer(int64)
  - name: string *required*
  - status: string [enum: available, pending, sold]
  - tags: array<Tag>
      - id: integer(int64)
      - name: string

### Security

petstore_auth[write:pets read:pets]

​
Security posture

security is observation, not exploitation — a GET for the response headers and a single CORS-preflight OPTIONS. It reports what a defender wants to confirm:
  • TLS and the standard security headers (HSTS, CSP, X-Frame-Options, X-Content-Type-Options, …) present vs missing.
  • A live CORS preflight with a foreign Origin — it flags a dangerous reflected-origin-with-credentials policy.
  • Cookie flags (Secure, HttpOnly, SameSite), the auth challenge, OIDC discovery and a framework fingerprint (from Server/X-Powered-By headers and session-cookie names).

​
GraphQL

When the OpenAPI sweep comes up empty, graphql runs a schema introspection query — a pure read that mutates nothing — and summarizes the queries, mutations, subscriptions with their arguments, the input types with their fields, enums with their values and any deprecations. 
<tool_call name="@api-explorer" args='{"cmd":"graphql","args":{"url":"https://countries.trevorblades.com/"}}' />

​
JSON output

Pass format: "json" to discover or spec to get a normalized, machine-readable inventory the agent can chain — pick an endpoint and drive it with @http — instead of re-parsing the markdown report.

​
Notes

  • It is read-only and concurrency-safe — the orchestrator can run several probes in parallel, and no call ever changes remote state.
  • It uses the shared web-tools HTTP client: it honors the corporate proxy (HTTPS_PROXY) and the global TLS trust (CHATCLI_CA_BUNDLE).
  • Internal APIs (api.company.internal, localhost:8080) work — only cloud metadata and link-local endpoints are blocked (SSRF protection), and every redirect hop is re-validated.
  • YAML specs are handled natively, alongside JSON.
  • The scope is deliberately discovery and documentation — no path brute-forcing or parameter fuzzing.
Pair it with the Scheduler to re-map a third-party API on a schedule and get @send notified when its surface changes.

​
Next Steps

Agentic Plugins

The full builtin tool catalog and how the agent uses them.

Web Tools

@webfetch, @websearch and the shared hardened HTTP client.