We tell clients their AI is only as good as the data foundation underneath it, so our own site practises what we preach: everything on shipshapedata.com is reachable programmatically. The whole surface is read-only and needs no authentication. Full details for agents are in agents.md; the auth story (there is none to configure) is in auth.md.
Quickstart
The API lives at https://shipshapedata.com/api/v1 and describes itself:
The machine-readable spec is at /openapi.json (OpenAPI 3.1, clean operationIds, works as function-calling definitions as-is).
Endpoints
| Endpoint | What it returns |
|---|---|
GET /api/v1/services | The 13 services, with descriptions and page URLs |
GET /api/v1/services/{slug} | One service |
GET /api/v1/industries | The 6 industry pages |
GET /api/v1/case-studies | Three case studies with real outcomes |
GET /api/v1/resources?q=&category=&limit= | Search the guides library |
GET /api/v1/resources/categories | The seven categories with counts |
GET /api/v1/ai-readiness/questions | The 16-question assessment |
POST /api/v1/ai-readiness/score | Stateless scoring: 0–100, band, per-area advice |
POST /api/v1/batch | Up to 20 GET paths in one round trip |
GET /api/v1/export | The whole dataset in one call (free OAuth token; see auth.md) |
GET /api/v1/contact | How to reach the team |
Errors are always JSON with an error.code, error.message, and a docs link, including 404s and 405s under /api. Every response carries draft RateLimit headers (fair use is 300 requests a minute per IP; beyond that you get a JSON 429 with Retry-After). Because every endpoint is stateless, requests are idempotent by construction: send an Idempotency-Key header (a formal parameter in the spec) and it is echoed back with Idempotency-Status. Resource search pages with an opaque cursor: follow nextCursor until it is null.
Versioning and deprecation
The API version lives in the URL: everything today is /v1, and breaking changes only ever ship as a new versioned path. When a version is deprecated it keeps working for at least six months, and its responses carry Deprecation and Sunset headers for that final period so clients and agents get machine-readable notice. Nothing is deprecated today, and additive changes (new endpoints, new optional fields) land in /v1 without ceremony.
MCP servers
Two Streamable HTTP servers, both keyless and read-only:
| Server | Endpoint | Tools |
|---|---|---|
| Product | https://shipshapedata.com/mcp | list_services, get_case_studies, search_resources, get_ai_readiness_questions, score_ai_readiness, get_contact_info |
| Docs | https://shipshapedata.com/mcp/docs | search_docs, get_page (full markdown of any page), list_sections |
Connect from Claude Code:
Or in any client that takes a JSON server config:
The server card is at /.well-known/mcp/server-card.json. Both servers are published in the official MCP registry as com.shipshapedata/shipshape-data and com.shipshapedata/shipshape-data-docs.
Skills, configs, and source
The official agent toolkit lives at github.com/shipshapedata/agent-tools: agent skills (install with npx skills add shipshapedata/agent-tools, listed on skills.sh), drop-in MCP configs for Claude Code and Cursor, a Claude Code plugin manifest, and the source of the CLI and SDK packages.
CLI and SDKs
shipshape-data is published on npm and PyPI: zero-dependency SDKs for Node and Python, each with a CLI that runs the whole surface from a terminal, including the AI readiness assessment.
Read the site as markdown
Every content page has a markdown twin at its URL plus index.md, and the same twin is served at ?mode=agent:
Start from /llms.txt (the site guide, under 8k characters) or the section indexes it links.
Discovery files
| /openapi.json | OpenAPI 3.1 spec for the API |
| /.well-known/ard.json | Agent readiness descriptor: every agent-facing surface |
| /.well-known/mcp/server-card.json | MCP server card (product; docs card sits beside it) |
| /.well-known/agent-card.json | A2A agent card; message/send to /a2a for answers with sources |
| /ask | NLWeb endpoint: POST {"query": "..."}, SSE with streaming=true |
| /.well-known/api-catalog | RFC 9727 API catalog |
| /agents.md | The agent guide |
| /auth.md | Auth: keyless reads; free self-serve OAuth for the bulk export |
| /.well-known/oauth-authorization-server | RFC 8414 authorization server metadata |
| /.well-known/oauth-protected-resource | RFC 9728 protected resource metadata |
| /schemamap.xml | NLWeb schema feed of key pages |
No writes, by design. The API and MCP servers read public content and score assessments statelessly; nothing stores data. To reach the team, email hello@shipshapedata.com.
Sandbox
A sandbox environment lives at https://shipshapedata.com/api/sandbox/v1. Because every endpoint is stateless and side-effect free, the sandbox serves identical endpoints and data to production; it exists so test configurations have an explicit base URL, and its responses carry X-Sandbox: true. Point anything at it, as often as is reasonable, without consequences.
Want this for your own product?
This page is the deliverable we build for clients: governed data underneath, then MCP connections and APIs that let models reach it safely. If you want your product to be this easy for agents to use, talk to us.