shipshapedata-com Case Studies API

openapi: 3.2.0
info:
  title: Shipshape Data Case Studies API
  version: 1.1.0
  summary: Public read API for Shipshape Data, a London AI consultancy
  description: 'Keyless, read-only API for Shipshape Data (shipshapedata.com): services, industries, case studies with real outcomes, a cursor-paginated searchable library of 169 practical guides on data and AI, and the 16-question AI readiness assessment with server-side scoring. No authentication except the bulk export (free self-serve OAuth, see https://shipshapedata.com/auth.md). Open CORS, no write endpoints. Fair use is 300 requests/minute/IP, advertised via draft RateLimit headers (429 + Retry-After beyond it). All endpoints are stateless, so every request is idempotent; send an Idempotency-Key header and it is echoed back with Idempotency-Status. Versioning and deprecation policy: the version lives in the URL (/v1); breaking changes only ever ship as a new versioned path, deprecated versions keep working for at least 6 months and respond with Deprecation and Sunset headers for their final period (nothing is deprecated today; policy at https://shipshapedata.com/developers/). MCP servers offering the same capabilities: https://shipshapedata.com/mcp (product) and https://shipshapedata.com/mcp/docs (docs); NLWeb endpoint at https://shipshapedata.com/ask; A2A agent card at https://shipshapedata.com/.well-known/agent-card.json.'
  contact:
    name: Shipshape Data
    email: hello@shipshapedata.com
    url: https://shipshapedata.com/developers/
  termsOfService: https://shipshapedata.com/terms-of-use/
servers:
- url: https://shipshapedata.com/api
  description: Production
- url: https://shipshapedata.com/api/sandbox
  description: 'Sandbox: identical endpoints and data; every call is stateless and side-effect free, responses carry X-Sandbox: true'
tags:
- name: Case Studies
paths:
  /v1/case-studies:
    get:
      operationId: listCaseStudies
      summary: List case studies
      description: Three published case studies with real, verifiable outcomes (Smarter Services, 1NCE, Slimstock). Optional keyword filter.
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: 'Optional: filter case studies by keyword across name and description'
        example: supply chain
      responses:
        '200':
          description: All case studies
          content:
            application/json:
              schema:
                type: object
                required:
                - caseStudies
                properties:
                  caseStudies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Page'
      tags:
      - Case Studies
  /v1/case-studies/{slug}:
    get:
      operationId: getCaseStudy
      summary: Get one case study
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        description: Case study slug
        example: 1nce
      responses:
        '200':
          description: The case study
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Case Studies
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            docs:
              type: string
              format: uri
            openapi:
              type: string
              format: uri
    Page:
      type: object
      required:
      - name
      - slug
      - url
      - description
      properties:
        name:
          type: string
        slug:
          type: string
        url:
          type: string
          format: uri
          description: Canonical HTML page; a markdown twin is at this URL plus index.md
        description:
          type: string
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    shipshapeOAuth:
      type: oauth2
      description: 'Free, self-serve client credentials: register at /oauth/register (open, anonymous), then exchange for a bearer token. Only the bulk export needs it.'
      flows:
        clientCredentials:
          tokenUrl: https://shipshapedata.com/oauth/token
          scopes:
            export: Read the complete dataset in one call