◎ Discry Score
segment.com
analytics · API
C
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 92 (A)
Discry your API →
ANALYTICS · RANK #16 OF 29

Segment is Needs Work to agents.

Discry independently scored how well an AI agent can discover and understand the Segment 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 · 43/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.Fail
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Fail
llms-full.txtA full-text bundle agents can load in one request.Fail
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 · 90/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.Partial
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 looking for Segment's API spec would find it via docs.segmentapis.com, which powers auto-generated SDKs in 6 languages — strong OpenAPI presence.
  • An agent consuming Segment docs would benefit from markdown availability (every page has a .md variant) and consistently task-oriented endpoint descriptions.
  • An agent searching for Segment via llms.txt or MCP registries would find nothing — zero AI-native discovery signals despite excellent underlying documentation.
  • An agent encountering errors would get actionable recovery guidance including Retry-After headers for 429s and specific troubleshooting steps for common failures.
  • Segment's migration to Twilio's domain has created discovery fragmentation — segment.com redirects confuse automated crawlers while docs live at twilio.com/docs/segment.

What to change

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

  1. 01Add llms.txt at segment.com (or twilio.com/docs/segment) covering core Tracking API methods (identify, track, group, page) and Public API capabilities — immediate high-impact improvement.
  2. 02Publish the OpenAPI spec at a stable, publicly accessible URL (e.g., docs.segmentapis.com/openapi.json) rather than requiring users to navigate the reference site.
  3. 03Create dedicated multi-step workflow guides showing common agent patterns: source setup -> tracking plan -> event sending -> destination verification.
  4. 04Register an official Segment MCP server in Glama/Smithery covering workspace management operations via the Public API.
  5. 05Add AGENTS.md to the segmentio/public-api-sdk-python or analytics-next repos with integration guidance for coding agents.

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 (writeKey)Basic AuthOAuth2 Bearer Token✓ Error format documented✓ Rate limits documented✓ Pagination documented✓ Idempotency documented

Comprehensive execution documentation including rate limits (1000 req/s), payload limits (32KB/500KB batch), cursor-based pagination, and messageId-based idempotency/deduplication. Error format uses standard HTTP status codes with specific error descriptions.

See your own Discry Score.

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

Discry your API — free