shipshapedata-com Ai Readiness API

openapi: 3.2.0
info:
  title: Shipshape Data Ai Readiness 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: Ai Readiness
paths:
  /v1/ai-readiness/questions:
    get:
      operationId: getAiReadinessQuestions
      summary: Get the AI readiness assessment
      description: 16 questions across four areas (strategy, people, data, change); 15 are scored, one is unscored sizing context. Ask a user each question, then POST the answers to /v1/ai-readiness/score.
      parameters:
      - name: section
        in: query
        required: false
        schema:
          type: string
          enum:
          - strategy
          - people
          - data
          - change
        description: 'Optional: return just one area''s questions'
        example: data
      responses:
        '200':
          description: Sections, questions, options, and band thresholds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assessment'
      tags:
      - Ai Readiness
  /v1/ai-readiness/score:
    post:
      operationId: scoreAiReadiness
      summary: Score AI readiness answers
      description: 'Stateless scoring with the same maths as shipshapedata.com/ai-readiness: mean of the 15 scored answers mapped to five maturity bands. Returns a 0-100 score, band guidance, per-area averages, and advice for the weakest area. Nothing is stored, so repeat calls with the same body always return the same result.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - answers
              properties:
                answers:
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 5
                  description: Either 16 option indices (0-4, all questions in order) or 15 point values (1-5, scored questions only, in order)
            example:
              answers:
              - 3
              - 2
              - 1
              - 3
              - 2
              - 3
              - 2
              - 3
              - 3
              - 2
              - 2
              - 3
              - 3
              - 3
              - 4
              - 3
      responses:
        '200':
          description: The scored result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessResult'
        '400':
          $ref: '#/components/responses/BadRequest'
      tags:
      - Ai Readiness
components:
  schemas:
    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
    ReadinessResult:
      type: object
      required:
      - score
      - band
      - pillars
      - weakestPillar
      properties:
        score:
          type: integer
          minimum: 0
          maximum: 100
        scale:
          type: string
        average:
          type: number
          description: Mean of scored answers on the 1-5 scale
        band:
          type: object
          required:
          - name
          - guidance
          properties:
            name:
              type: string
            guidance:
              type: array
              items:
                type: string
        pillars:
          type: object
          description: Keyed strategy/people/data/change
          additionalProperties:
            type: object
            required:
            - title
            - average
            properties:
              title:
                type: string
              average:
                type: number
              advice:
                type:
                - string
                - 'null'
        weakestPillar:
          type: string
          enum:
          - strategy
          - people
          - data
          - change
        scoredQuestions:
          type: integer
        interactiveVersion:
          type: string
          format: uri
        nextStep:
          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
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        pattern: ^[A-Za-z0-9._-]{1,255}$
      description: Optional client-chosen key. Every endpoint is stateless and side-effect free, so identical requests always produce identical results; the key is echoed back with an Idempotency-Status header so clients can confirm safe replay.
  responses:
    BadRequest:
      description: Invalid input
      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