BuildBatch Ask.json API

openapi: 3.2.0
info:
  title: BuildBatch assistant interface Ask.json API
  version: '1'
  summary: Ask a person the right questions, then get the shopping list for their room as data.
  description: 'BuildBatch is a free UK job planner for paint, wallpaper, tiles, flooring, carpet, sheet vinyl, skirting, plasterboard, loft insulation, a concrete slab, a patio, and sub-base and gravel. This interface lets an AI assistant find out what to ask a person (GET /ask.json), call the planner with their answers (GET /plan.json), and show them the finished list, with a link that opens the same list for them.


    The list is the one the planner makes: the same code (list template 1.41.0) and, for the parameters, the same grammar as a list link (https://buildbatch.co.uk/links/). Only use measurements the person gave you; never guess one. No key, no account and no cookie: GET only, free, one room a call. An MCP client can use the same planner at https://buildbatch.co.uk/mcp, through four tools (quick_room_list, plan_room, find_guide, ask_questions) and one prompt.


    Honest limits, repeated in every answer (honesty): the figures are typical figures or labelled examples unless a product''s own figures are sent; BuildBatch is built and checked with AI tools and nobody outside the build has reviewed it; an answer shows no price, and BuildBatch does not know whether a shop has an item; the person should check the figures and follow each product''s own instructions.'
  termsOfService: https://buildbatch.co.uk/terms/
servers:
- url: https://buildbatch.co.uk
tags:
- name: Ask.json
paths:
  /ask.json:
    get:
      operationId: getQuestionScript
      summary: What to ask the person
      description: 'The ordered questions to put to a person before calling /plan.json: the wording, the allowed answers, the parameter each fills, whether it is required, when to ask it, what to do if the person does not know, the typical rooms and door and window names, and rules for the assistant. Version 1; the script is generated from the planner''s own tables.'
      responses:
        '200':
          description: The question script.
          headers:
            Access-Control-Allow-Origin:
              description: Any website may read this answer.
              schema:
                type: string
                const: '*'
            Cache-Control:
              description: public, short-lived
              schema:
                type: string
            X-Robots-Tag:
              description: 'noindex: the answer is for programs and is not a page for a search engine.'
              schema:
                type: string
                const: noindex
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionScript'
              examples:
                questions:
                  summary: 'The first question (abridged: the real answer has every question)'
                  x-request: /ask.json
                  value:
                    api: buildbatch-assistant
                    document: question-script
                    v: 1
                    questions:
                    - id: job
                      ask: What are you planning to do in the room?
                      required: true
                      fills:
                      - job
      tags:
      - Ask.json
components:
  schemas:
    Question:
      type: object
      required:
      - id
      - ask
      - type
      - required
      - fills
      properties:
        id:
          type: string
        ask:
          type: string
          description: The wording to use.
        type:
          type: string
          enum:
          - choice
          - yes-no
          - length
          - lengths
          - openings
          - corners
        required:
          type: boolean
          description: 'True: the planner refuses without it whenever the question applies.'
        requiredWhen:
          type: object
          description: Another condition under which it is required.
        when:
          type:
          - object
          - 'null'
          description: 'When to ask: null is always; otherwise every key must hold (job is one of the values listed).'
        whenText:
          type: string
        fills:
          type: array
          items:
            type: string
          description: The /plan.json parameters the answer fills.
        choices:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              label:
                type: string
              sets:
                type: object
                additionalProperties:
                  type: string
                description: The parameters to send for this answer.
        ifUnknown:
          type: string
          description: What to do if the person does not know.
        default:
          type: string
          description: What the planner assumes if the parameter is left out.
        notes:
          type: array
          items:
            type: string
    QuestionScript:
      type: object
      required:
      - api
      - document
      - v
      - instructions
      - questions
      properties:
        api:
          type: string
          const: buildbatch-assistant
        document:
          type: string
          const: question-script
        v:
          type: integer
          const: 1
        instructions:
          type: object
          description: 'Rules for the assistant: what to ask, what never to do, and what to tell the person afterwards.'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
        productFigures:
          type: array
          description: Optional figures a person may read off a tin, pack, roll or box.
          items:
            type: object
        typicalRooms:
          type: array
          description: Offer only if the person does not know their room's size.
          items:
            type: object
        typicalOpenings:
          type: array
          description: The door and window names a call may use.
          items:
            type: object
externalDocs:
  description: The same thing for people, and how list links work
  url: https://buildbatch.co.uk/links/
x-buildbatch:
  jobs:
  - paint
  - wallpaper
  - tiles
  - flooring
  - carpet
  - loft
  - both
  - paint-carpet
  - skirting
  - plasterboard
  - concrete
  - patio
  - groundwork
  questions: https://buildbatch.co.uk/ask.json
  llms: https://buildbatch.co.uk/llms.txt
  note: The jobs are the values of the job parameter.