shipshapedata-com Export API

openapi: 3.2.0
info:
  title: Shipshape Data Export 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: Export
paths:
  /v1/export:
    get:
      operationId: getBulkExport
      summary: The whole dataset in one call
      description: 'Complete export: services, industries, case studies, all 169 guides, and the assessment, as one JSON document. The only authenticated endpoint: takes a free OAuth 2.0 bearer token (client credentials; self-serve registration at /oauth/register, tokens at /oauth/token, walkthrough at https://shipshapedata.com/auth.md). Without a token it returns 401 with a WWW-Authenticate header pointing at the RFC 9728 resource metadata.'
      security:
      - shipshapeOAuth:
        - export
      responses:
        '200':
          description: The complete dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkExport'
        '401':
          description: Missing or invalid bearer token; WWW-Authenticate carries the resource metadata URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Export
components:
  schemas:
    Resource:
      type: object
      required:
      - title
      - slug
      - url
      - category
      - description
      properties:
        title:
          type: string
        slug:
          type: string
        url:
          type: string
          format: uri
        category:
          type: string
        description:
          type: string
        answers:
          type: array
          items:
            type: string
          description: The questions this guide answers
        relevance:
          type: integer
          description: 'Present on keyword searches: how many query terms matched'
    Assessment:
      type: object
      required:
      - title
      - sections
      - bands
      properties:
        title:
          type: string
        instructions:
          type: string
        sections:
          type: array
          items:
            type: object
            required:
            - title
            - key
            - questions
            properties:
              title:
                type: string
              key:
                type: string
                enum:
                - strategy
                - people
                - data
                - change
              desc:
                type: string
              questions:
                type: array
                items:
                  type: object
                  required:
                  - q
                  - opts
                  properties:
                    q:
                      type: string
                    scored:
                      type: boolean
                      description: false = unscored sizing context
                    ctx:
                      type: string
                    opts:
                      type: array
                      items:
                        type: string
                      description: Five options; the answer is the option index 0-4
        bands:
          type: array
          items:
            type: object
            required:
            - min
            - name
            properties:
              min:
                type: number
              name:
                type: string
    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
    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
    Contact:
      type: object
      required:
      - company
      - email
      - website
      properties:
        company:
          type: string
        location:
          type: string
        email:
          type: string
          format: email
        website:
          type: string
          format: uri
        how:
          type: string
        note:
          type: string
    BulkExport:
      type: object
      required:
      - exportedAt
      - services
      - industries
      - caseStudies
      - resources
      - assessment
      properties:
        exportedAt:
          type: string
          format: date-time
        client:
          type: string
          description: The client_id the token was issued to
        services:
          type: array
          items:
            $ref: '#/components/schemas/Page'
        industries:
          type: array
          items:
            $ref: '#/components/schemas/Page'
        caseStudies:
          type: array
          items:
            $ref: '#/components/schemas/Page'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        assessment:
          $ref: '#/components/schemas/Assessment'
        contact:
          $ref: '#/components/schemas/Contact'
  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