◎ Discry Score
supertokens.com
auth · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 93 (A)
Discry your API →
AUTH · RANK #10 OF 16

SuperTokens is Good to agents.

Discry independently scored how well an AI agent can discover and understand the SuperTokens API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.

Discry your API — freeView the docs ↗

SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.

Discovery

45% of score · 71/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Pass
llms.txtAn llms.txt index that points agents to the docs that matter.Pass
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Pass
llms-full.txtA full-text bundle agents can load in one request.Pass
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Fail
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Fail
MCP registryThe API is listed in a public MCP registry.Fail
robots.txt AI directivesrobots.txt allows (or explicitly guides) AI crawlers.Pass
SitemapA sitemap so agents can enumerate the docs surface.Partial

Comprehension

55% of score · 96/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass
Realistic examplesRunnable, real-world request/response examples.Pass
Multi-step workflowsDocs that chain calls into complete jobs an agent can follow.Pass
Error-recovery guidanceDocumented failure modes and how to recover from them.Pass
Answer-first formatThe answer leads; preamble does not bury it.Pass
Capability boundariesClear limits — what the API can and cannot do.Pass
Naming consistencyConsistent, predictable naming across endpoints.Pass
Heading hierarchyClean heading structure agents can navigate.Pass
Markdown docsDocs available as clean markdown, not JS-rendered HTML only.Pass
Token efficiencyDocs are concise enough to fit an agent context window.Partial

What we found

  • An agent ingesting SuperTokens would find a near-ideal markdown surface: every doc page is available as plain `.md`, plus a structured llms.txt index and a 5.2MB llms-full.txt that mirrors the entire documentation set — SuperTokens even ships a dedicated 'Build with AI Tools' guide.
  • The Core Driver Interface (CDI) is published as a downloadable OpenAPI spec on SwaggerHub and GitHub, and its error schemas embed actionable recovery data (e.g. `retryAfterMs`) rather than bare status codes.
  • Code examples are genuinely agent-usable: realistic values (john@example.com, somePassword123, +1234567890), copy-pasteable curl, and multi-language SDK samples (Node/Express, Python, Go) with task-oriented 'what this accomplishes' framing.
  • Discovery leaks points on agent-native signals an agent looks for first: no AGENTS.md in the primary repos, no /.well-known/mcp.json, and no SuperTokens listing in major MCP registries (Glama/Smithery/PulseMCP) — their MCP work is a toolkit for securing other MCP servers, not a discoverable SuperTokens server.
  • The sitemap is declared in robots.txt but returns empty/blocked content across three independent fetchers, so an automated crawler cannot use it to enumerate doc pages — a silent discovery gap despite robots.txt being fully AI-permissive.

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

  1. 01Make sitemap.xml actually fetchable by automated clients (it currently returns empty/blocked content to crawlers despite being referenced in robots.txt) so agents can enumerate the full docs tree.
  2. 02Add an AGENTS.md to the primary repos (supertokens-core, supertokens-node, supertokens-auth-react) pointing coding agents at the .md docs, llms-full.txt, and the CDI/FDI specs — a high-leverage, low-effort discovery win.
  3. 03Publish a SuperTokens MCP server entry in Glama/Smithery/PulseMCP (distinct from the auth-for-MCP toolkit) and add a /.well-known/mcp.json so agents can discover programmatic access without crawling docs.
  4. 04Trim or split the llms.txt (currently ~52KB) toward a tighter, top-level capability overview so an agent can grasp core recipes in under 5,000 tokens before drilling into llms-full.txt.
  5. 05Document idempotency behavior for state-changing endpoints (sign-up, session create, bulk import) so agents can safely retry after timeouts without creating duplicates.

Execution coverage · INFORMATIONAL, UNSCORED

Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.

API Key (Core Driver Interface)Session token (HttpOnly cookie or Authorization Bearer header)OAuth2 (Unified Login / OAuth2Provider recipe)JWT✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

Execution characteristics are documented thoroughly. Errors are machine-parseable JSON with a stable `status` enum (e.g. OK, WRONG_CREDENTIALS_ERROR, FIELD_ERROR, LIMIT_REACHED_ERROR, GENERAL_ERROR) and rate-limit responses carry an explicit `retryAfterMs`. Rate limits, cursor pagination (bulk import), and multiple auth modes are all documented; idempotency keys are not mentioned. Claims are documentation-only and would require a live audit to verify.

See your own Discry Score.

Drop your API docs URL. See what an agent sees — in 60 seconds, free.

Discry your API — free