retrain.ai is Poor to agents.
Discry independently scored how well an AI agent can discover and understand the retrain.ai API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
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 · 50/100Comprehension
55% of score · 54/100What we found
- The docs site is genuinely agent-addressable: a well-structured llms.txt indexes every page, all pages are served as native text/markdown at .md URLs, and each page carries an explicit 'For AI agents' banner pointing back to the index.
- An agent will likely fail at the front door: the auth guide contradicts the OpenAPI spec on the exact fields to send (client_id/client_secret vs clientId/clientSecret), calls the response field access_token where the schema says token, and shows a nonstandard 'authentication: Bearer<TOKEN>' header instead of Authorization.
- The Career Paths spec requires a field named roleName but only defines a property named roleTitle, so an agent building requests strictly from the spec gets a guaranteed 422 with no recovery guidance.
- There is no consolidated downloadable OpenAPI spec — valid OpenAPI 3.0.2 fragments are embedded per endpoint page (with artifacts like a stray colon in the jd2skills path), forcing an agent to stitch the API together page by page.
- Errors are bare status codes ('400: Bad request', '500: Service temporarily unavailable') with zero recovery guidance, and no rate limits or capability boundaries are documented — an agent discovers every limit by failing.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Fix the auth documentation contradictions (clientId casing, token vs access_token, Authorization header name) — this is the highest-impact fix since every agent interaction starts there.
- 02Fix the Career Paths spec bug: the required field roleName does not exist in the schema (the property is roleTitle), which breaks any spec-driven client.
- 03Publish one consolidated OpenAPI spec at a stable URL (e.g. /openapi.json) instead of per-page embedded fragments.
- 04Add worked request/response examples with realistic values to each endpoint page — the docs currently contain schemas only, with placeholder examples like YOUR_CLIENT_ID.
- 05Document rate limits and add per-error recovery guidance (what to do on 401 token expiry, 422 field errors, 500/503), and enable llms-full.txt and sitemap.xml on the ReadMe project.
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.
Auth flow (client credentials to 1-hour JWT) is documented, and 422 validation errors have a machine-parseable schema (loc/msg/type), but all other errors are bare status codes. No rate limits, pagination, or idempotency documentation exists anywhere.