Bitbucket is Needs Work to agents.
Discry independently scored how well an AI agent can discover and understand the Bitbucket 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 · 52/100Comprehension
55% of score · 72/100What we found
- An agent can fully reconstruct the API surface without scraping: Bitbucket publishes a complete, public Swagger 2.0 spec at api.bitbucket.org/swagger.json (~1.3MB, every endpoint described with curl examples), which is the single strongest agent-readiness signal here.
- Core mechanics an agent must understand to chain calls — pagination, filtering/sorting query language, partial responses, and a standardized machine-parseable error envelope — are all documented clearly on one REST intro page with consistent snake_case fields and ISO-8601 timestamps.
- Discovery is weak on agent-native signals: no llms.txt, no llms-full.txt, and no .well-known/mcp.json on either bitbucket.org or developer.atlassian.com, so an agent gets no curated entry point and must rely on the sitemap or the raw spec.
- An agent looking for a maintained integration would find one: Bitbucket is heavily represented across MCP registries (18+ servers on PulseMCP, plus Glama and Smithery listings), though these are community-built rather than official.
- Examples skew curl-only and workflow guidance is conceptual — there are no dedicated multi-step 'do X then Y' guides in the reference docs, so an agent stitching real tasks together must infer sequencing from individual endpoint pages.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish an llms.txt at developer.atlassian.com (and ideally bitbucket.org) that links the REST intro, auth, pagination, error, and rate-limit pages plus the Swagger spec — the highest-leverage discovery fix, currently a hard fail.
- 02Add a .well-known/mcp.json or an official MCP server reference so agents can discover a first-party tool surface instead of relying on third-party community servers.
- 03Add 2-3 end-to-end workflow guides (e.g. 'create a repo -> push -> open a pull request -> merge') to the reference docs so agents can chain operations without inferring sequencing.
- 04Surface explicit error-recovery guidance (especially for 429 and 401/token-refresh) inside the REST reference rather than only on the separate support rate-limit page, including the relevant retry/refresh steps.
- 05Add request/response examples in more than one language (at minimum a non-curl HTTP example) and ensure POST/PUT endpoints show realistic request bodies, not just response schemas.
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.
Execution characteristics are well documented: a standardized JSON error envelope (type/error/message/fields/detail/id), page-based pagination with opaque next links and documented min/max pagelen, multiple auth schemes, and a 1,000 req/hour rate limit on a dedicated support page. Idempotency keys are not documented.