Semgrep is Good to agents.

What we found

• —An agent would discover Semgrep easily: a valid llms.txt at the domain root points straight to docs, the OpenAPI-format API reference, the rule registry, and the official MCP server — plus the API is listed across PulseMCP, Glama, and Smithery.
• —Semgrep is unusually invested in agent tooling: a comprehensive AGENTS.md ships in the primary repo (semgrep/semgrep), an official MCP server (semgrep/mcp, published to PyPI as semgrep-mcp), and a dedicated semgrep/skills repo of skills for AI coding agents.
• —The REST API is documented in OpenAPI format with a downloadable spec, task-oriented endpoint titles, answer-first layout (method/URL/cURL at the top), and realistic response payloads (real file paths, GitHub URLs, plausible IDs and timestamps).
• —The biggest comprehension gap for an agent is error handling: the API reference documents only 200 responses — no error codes, error schema, or recovery guidance — so an agent would only learn how failures behave by failing. Rate limits are likewise undocumented.
• —Naming is inconsistent within a single response object: nested finding fields mix snake_case (created_at, first_seen_scan_id, match_based_id) with camelCase (endColumn, filePath, externalSlug), which forces an agent to handle both conventions.

What to change

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

1. 01Document error responses in the API reference: add the 4xx/5xx status codes, the error response schema, and per-error recovery guidance (e.g. what to do on 401 token/permission failures or 400 invalid-parameter responses) alongside the existing 200 examples.
2. 02Publish rate-limit documentation — the limits themselves and the response headers returned on throttling (e.g. Retry-After) — so agents can back off correctly instead of discovering limits by failing.
3. 03Standardize field naming across the API to a single convention (snake_case throughout is most consistent with the existing finding fields) to remove the camelCase/snake_case mixing inside response objects.
4. 04Add descriptive context to each link in llms.txt (one line per entry) and add an llms-full.txt with concatenated API-usage content so agents can load core capabilities in one fetch.
5. 05Offer multi-language request examples (Python, JavaScript) beyond cURL on endpoint pages to make examples directly copy-pasteable into agent-generated integration code.