# Square — API Agent Score

> Score: 81/100 (Grade: A) | Domain: square.com | Rubric: 1.0.0 | Checked: July 29, 2026

Square scored 81/100 (A), classified "ai-ready".

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

## Summary

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

## Category Scores

- API Design: 91/100 (A+)
- Developer Experience: 89/100 (A)
- Agent Discovery: 73/100 (B)
- Agent Understanding: 71/100 (B)
- Agent Usability: 87/100 (A)

## Check Results

### API Design

- [pass] Auth declared & discoverable — authentication documented in the docs site at https://developer.squareup.com/docs/oauth-api/best-practices. Investigated: docs 100%, spec 50%.
- [warn] Schema coverage & depth — Medium parameter complexity (avg 2.6 params/op; nested/body schemas present). Investigated: spec 83%.
- [warn] Machine-readable, versioned contract — info.version="1.0.0" set but no versioning scheme (URL / header / media type) detected. Investigated: spec 75%, docs 50%.
- [pass] Security & governance hygiene — No credential-shaped strings detected in spec. Investigated: spec 100%, wellknown 0%.
- [pass] Example coverage — 100% example coverage across params + responses. Investigated: spec 100%, docs 100%.

### Developer Experience

- [pass] Self-service developer portal — Self-service signup at https://developer.squareup.com/docs/square-get-started; free tier / sandbox documented. Investigated: docs 100%.
- [pass] Code samples in docs — Code samples in 3 language(s) across docs (top: shell, go, curl); 1/3 pages have ≥ 2 languages on the same page. Investigated: docs 100%.
- [pass] Description completeness — 63% description completeness (target 90%+). Investigated: spec 100%.
- [pass] Changelog published — Newest official SDK activity 15 day(s) ago. Investigated: sdk 100%, spec 0%, docs 0%.
- [warn] Quickstart present — Quickstart page reachable (2 variants scanned starting at https://developer.squareup.com/docs/square-get-started) but no runnable code sample detected in HTML or .md variant. Investigated: docs 50%.

### Agent Discovery

- [pass] Registry & SDK presence — Indexed on Context7 (websites/developer_squareup, 11441 snippets). Investigated: docs 100%, sdk 100%, cli 0%.
- [warn] Docs reachable, not hard auth-gated — Server ignores Accept: text/markdown header (0/50 sampled pages return markdown); 28 rate-limited (HTTP 429). Investigated: docs 75%.
- [warn] llms.txt present, valid & comprehensive — No llms.txt directive found in HTML of any of 26 sampled pages; 24 failed to fetch. Investigated: docs 38%.
- [warn] Crawlable / AEO — No sitemap discoverable via robots.txt or /sitemap.xml on the docs host. Investigated: wellknown 50%.

### Agent Understanding

- [pass] Machine-readable errors (RFC 9457) — error codes documented in the docs site at https://developer.squareup.com/docs/payments-api/error-codes. Investigated: spec 100%, docs 100%.
- [pass] Operation purpose clarity — 98% of operations have a clear summary + operationId an agent can select on. Investigated: spec 100%.
- [warn] Agent-navigable, token-efficient docs — 2 of 50 sampled pages appear to be client-side rendered SPA shells (__next detected); agents using HTTP fetches will see no content; 4 more have page structure but little substantive content. Investigated: docs 50%.
- [warn] Description consistency across surfaces — Mean pairwise description similarity across 2 surfaces (spec, docs) is 2% (threshold 35% for full credit).
- [fail] Agent instructions file (AGENTS.md) — No AGENTS.md at the site root or /.well-known/. Investigated: wellknown 0%.
- [fail] Docs structured data — Neither JSON-LD nor OpenGraph/meta tags detected across 1 assessed pages (1 JS-rendered). Investigated: docs 0%.

### Agent Usability

- [pass] Idempotency documented — idempotency documented in the docs site at https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency. Investigated: spec 100%, docs 100%.
- [pass] Pagination documented & consistent — pagination documented in the docs site at https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination. Investigated: docs 100%, spec 50%.
- [pass] Sandbox separation — sandbox documented in the docs site at https://developer.squareup.com/docs/devtools/sandbox/overview. Investigated: spec 100%, docs 100%.
- [warn] Rate-limit signaling — No rate-limit response headers documented. Investigated: spec 50%, docs 50%.
- [warn] Runnable collection with test scripts — No test scripts found in the workspace's collections. Investigated: platform 50%.

## Executive Summary

Square's API Design and Developer Experience are strong foundations that partners can build on with confidence. The critical gap is in Agent Understanding: there is no AGENTS.md instruction file and no structured data on the docs, which means AI coding agents and automated tools cannot reliably interpret or act on Square's API surface without manual intervention. Closing these two gaps — publishing an agent instructions file and adding structured metadata to the docs — should be the immediate priority, followed by ensuring the documentation is fully reachable, crawlable, and machine-readable so partners and their agents can discover Square's APIs without a sales conversation.