# Clerk — API Agent Score

> Score: 80/100 (Grade: A) | Domain: clerk.com | Rubric: 1.0.0 | Checked: July 24, 2026

Clerk scored 80/100 (A), classified "ai-ready".

[View full report](https://www.postman.com/ai/ai-ready-apis/company/clerk)
[All organizations](https://www.postman.com/ai/ai-ready-apis/llms.txt)

## Summary

- Overall: 80/100 (A)
- Classification: ai-ready

## Category Scores

- API Design: 98/100 (A+)
- Developer Experience: 100/100 (A+)
- Agent Discovery: 84/100 (A)
- Agent Understanding: 79/100 (B)
- Agent Usability: 56/100 (D)

## Check Results

### API Design

- [pass] Schema coverage & depth — 1/1 enums are named types (not bare strings). Investigated: sdk 100%, spec 61%.
- [pass] Auth declared & discoverable — Authentication required (global or on every operation). Investigated: spec 100%, docs 100%.
- [warn] Machine-readable, versioned contract — info.version="v1" set but no versioning scheme (URL / header / media type) detected. Investigated: spec 92%, docs 83%.
- [pass] Security & governance hygiene — No credential-shaped strings detected in spec. Investigated: spec 100%, wellknown 100%.
- [pass] Example coverage — Code samples in 3 language(s) across docs (top: shell, typescript, curl); 1/19 pages have ≥ 2 languages on the same page. Investigated: docs 100%, sdk 50%, spec 0%.

### Developer Experience

- [pass] Self-service developer portal — Signup page at https://dashboard.clerk.com/sign-up; no free-tier language detected in docs/pricing. Investigated: docs 100%.
- [pass] Quickstart present — Quickstart at https://clerk.com/docs/nextjs/getting-started/quickstart has a runnable sample in the .md variant (https://clerk.com/docs/nextjs/getting-started/quickstart.md). Investigated: docs 100%.
- [pass] Code samples in docs — Code samples in 3 language(s) across docs (top: shell, typescript, curl); 1/19 pages have ≥ 2 languages on the same page. Investigated: docs 100%.
- [pass] Description completeness — 89% description completeness (target 90%+). Investigated: spec 100%.
- [pass] Changelog published — changelog documented in the docs site at https://clerk.com/changelog. Investigated: spec 100%, docs 100%, sdk 100%.

### Agent Discovery

- [pass] Registry & SDK presence — Official CLI at clerk/cli with published releases (installable). Investigated: cli 100%, sdk 67%, docs 0%.
- [warn] Docs reachable, not hard auth-gated — 1 of 50 sampled pages require authentication (49 accessible). Investigated: docs 90%.
- [warn] llms.txt present, valid & comprehensive — No llms.txt directive found in HTML of any of 50 sampled pages. Investigated: docs 69%, sdk 0%.
- [warn] Crawlable / AEO — robots.txt blocks 1 of 7 monitored AI crawlers on docs paths (ccbot). Investigated: wellknown 50%.

### Agent Understanding

- [pass] Machine-readable errors (RFC 9457) — 11 distinct 4xx/5xx response codes documented. Investigated: docs 100%, spec 50%, sdk 50%.
- [pass] Operation purpose clarity — 100% of operations have a clear summary + operationId an agent can select on. Investigated: spec 100%.
- [warn] Agent-navigable, token-efficient docs — 22 of 50 pages have substantive content differences between markdown and HTML (avg 18% missing). Investigated: docs 61%.
- [pass] Docs structured data — JSON-LD Article markup on 10/15 assessed pages (67%) with dateModified present. Investigated: docs 100%.
- [fail] Agent instructions file (AGENTS.md) — No AGENTS.md at the site root or /.well-known/. Investigated: wellknown 0%.
- [fail] Description consistency across surfaces — Mean pairwise description similarity across 2 surfaces (spec, docs) is 0% (threshold 35% for full credit).

### Agent Usability

- [pass] Pagination documented & consistent — Pagination params detected on 8 list endpoint(s). Investigated: spec 100%, docs 100%.
- [pass] Sandbox separation — Sandbox environments are exposed (sandbox). Investigated: sdk 100%, spec 0%, docs 0%.
- [fail] Idempotency documented — 0% of mutating operations document idempotency. Investigated: spec 0%, docs 0%, sdk 0%.
- [fail] Rate-limit signaling — No rate-limit response headers documented. Investigated: spec 0%, docs 0%.
- [fail] Runnable collection with test scripts — No public Postman workspace discovered for the org. Investigated: platform 0%.

## Executive Summary

Clerk's API program has strong fundamentals in discovery and API design — partners can find and understand the contract surface without friction. However, two areas put partner integration success at risk: agents and coding tools lack the contextual instructions and consistent descriptions needed to generate correct, trustworthy integrations, and the absence of runnable collections with test scripts means partners must build blindly without validated workflows or clear operational guardrails around idempotency and rate limits. Prioritize closing the agent-context and operational-reliability gaps first to ensure partners and their AI agents can integrate confidently and at speed.