{
  "openapi": "3.1.0",
  "info": {
    "title": "KidArt AI API",
    "version": "1",
    "description": "A creative companion for children's artwork. Send a photo of a drawing with the child's age band and the materials at home, and get the colours and shapes measured in the picture, a warm descriptive reading, and two or three art activities picked from a curated catalogue and re-checked against age and materials. Everything is descriptive and positive: there is no score, grade or ranking, no comparison with other children, and no emotional or developmental reading. Authenticate with an API key (Authorization: Bearer <key> or X-API-Key). Only starting an analysis is billed, once, after it is delivered; preview, the activity library, listings and trends are free."
  },
  "servers": [
    {
      "url": "https://kidartai.sensifai.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Analysis",
      "description": "Photograph in, report out."
    },
    {
      "name": "Reference",
      "description": "Free reads."
    }
  ],
  "paths": {
    "/api/v1/meta": {
      "get": {
        "summary": "List the closed vocabularies",
        "operationId": "getMeta",
        "tags": [
          "Reference"
        ],
        "description": "The age bands, materials, subjects, techniques, shapes and hazards that requests are validated against and responses are written in. Free.",
        "responses": {
          "200": {
            "description": "The vocabularies.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meta"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/preview": {
      "post": {
        "summary": "Preview a photo (free)",
        "operationId": "previewPhoto",
        "tags": [
          "Analysis"
        ],
        "description": "Measures a photo locally: quality, crayon-box colours, shapes and how the page is used. No model is called, nothing is stored, nothing is billed, so use it to check a photo before paying for an analysis. The photo must be a JPEG or PNG, at least 240 px on its shorter side, up to 10 MB. Photograph the page flat, in daylight, with the whole sheet in frame. An unusable photo (blank page, too dark, blurry, too small) is a 200 with usable false and a message.",
        "responses": {
          "200": {
            "description": "The measurements, or usable false with a message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/Unsupported"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "photo": {
                    "type": "string",
                    "description": "Base64 JPEG or PNG; a data: URL is accepted.",
                    "format": "byte"
                  }
                },
                "required": [
                  "photo"
                ]
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "photo": {
                    "type": "string",
                    "description": "The photo file.",
                    "format": "binary"
                  }
                },
                "required": [
                  "photo"
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses": {
      "post": {
        "summary": "Start an analysis (billed on success)",
        "operationId": "createAnalysis",
        "tags": [
          "Analysis"
        ],
        "description": "Queues one analysis of a child's drawing or painting and answers 202 with a job to poll. The photo is measured locally, read by one bounded vision-model call, and the colours, shapes, composition and two or three activities are assembled and verified in Go. Billing: one unit per delivered analysis, reported to the Sensifai Marketplace only after the job succeeded and under one identifier minted when the request was admitted, so a retry never charges twice. A photo that is not a drawing, an unusable photo and any failure are not charged. The first analyses may be inside a free allowance and the rest follow the price model on the marketplace listing. A request refused with 402 (empty prepaid wallet) or 403 (no active subscription) runs nothing. The photo must be a JPEG or PNG, at least 240 px on its shorter side, up to 10 MB. Photograph the page flat, in daylight, with the whole sheet in frame. The photo is never stored: it waits on the job until the job ends, goes to the model inline with storage disabled, and metadata (EXIF, location) is removed first.",
        "responses": {
          "202": {
            "description": "Accepted. Poll the job.",
            "headers": {
              "Location": {
                "description": "Path of the job.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Accepted"
                },
                "example": {
                  "job_id": "01a2b3c4",
                  "status": "queued",
                  "poll": "/api/v1/jobs/01a2b3c4"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "The prepaid wallet is empty and the free allowance is used up. The problem carries top_up_url.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "No active subscription to KidArt AI. The problem carries subscribe_url.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/Unsupported"
          },
          "422": {
            "description": "The choices are invalid (unknown age band, material, subject or album) or the photo cannot be used (no drawing visible, too dark, blurry, too small). Nothing is queued or charged.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "502": {
            "description": "The subscription or wallet could not be verified; try again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "photo": {
                    "type": "string",
                    "description": "The photo file.",
                    "format": "binary"
                  },
                  "age_band": {
                    "type": "string",
                    "enum": [
                      "3-4",
                      "5-6",
                      "7-9",
                      "10-12"
                    ]
                  },
                  "materials": {
                    "type": "string",
                    "description": "Comma-separated, for example crayons,glue,scissors."
                  },
                  "subject": {
                    "type": "string",
                    "enum": [
                      "garden",
                      "flowers",
                      "tree",
                      "sun_sky",
                      "rainbow",
                      "house",
                      "animals",
                      "birds",
                      "sea",
                      "insects",
                      "vehicles",
                      "people",
                      "food",
                      "space",
                      "fantasy",
                      "pattern",
                      "landscape",
                      "other"
                    ]
                  },
                  "album_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "photo",
                  "age_band"
                ]
              }
            }
          }
        }
      },
      "get": {
        "summary": "List analyses",
        "operationId": "listAnalyses",
        "tags": [
          "Analysis"
        ],
        "description": "The account's analyses and jobs, newest first. Free.",
        "responses": {
          "200": {
            "description": "A page of analyses.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AnalysisSummary"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 30
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ]
      }
    },
    "/api/v1/analyses/{id}": {
      "get": {
        "summary": "Get one analysis",
        "operationId": "getAnalysis",
        "tags": [
          "Analysis"
        ],
        "description": "A delivered analysis with its full report. A job that is still running, failed, or another account's id is a 404 here; use the job endpoint for progress. Free.",
        "responses": {
          "200": {
            "description": "The analysis.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Analysis"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/jobs/{id}": {
      "get": {
        "summary": "Poll a job",
        "operationId": "getJob",
        "tags": [
          "Analysis"
        ],
        "description": "queued, running, then succeeded (with analysis_id) or failed (with error). Free.",
        "responses": {
          "200": {
            "description": "The job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/activities": {
      "get": {
        "summary": "Browse the activity library (free)",
        "operationId": "listActivities",
        "tags": [
          "Reference"
        ],
        "description": "The curated art activities for an age band, with their steps, materials, hazards and supervision level. No analysis is needed and nothing is billed.",
        "responses": {
          "200": {
            "description": "The activities.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Library"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "Missing or unknown age or material.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "3-4",
                "5-6",
                "7-9",
                "10-12"
              ]
            }
          },
          {
            "name": "materials",
            "in": "query",
            "description": "Comma-separated materials the family has; marks which items are ready.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hook",
            "in": "query",
            "description": "Only activities that build on this theme.",
            "schema": {
              "type": "string",
              "enum": [
                "circles",
                "repetition",
                "lines",
                "colour_contrast",
                "warm_colours",
                "cool_colours",
                "bold_strokes",
                "fine_detail",
                "full_page",
                "open_space",
                "symmetry",
                "nature",
                "animals",
                "story",
                "pattern",
                "texture",
                "colour_mixing",
                "building",
                "figures",
                "space",
                "sea",
                "food"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "A word in the title or summary.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ready",
            "in": "query",
            "description": "true keeps only activities the family can start today.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ]
      }
    },
    "/api/v1/history": {
      "get": {
        "summary": "Trends across analyses (free)",
        "operationId": "getHistory",
        "tags": [
          "Reference"
        ],
        "description": "Aggregated colours, techniques, shapes, subjects and a weekly strip for the account. Only analyses delivered while the portfolio history was kept are counted.",
        "responses": {
          "200": {
            "description": "The trends.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/History"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "description": "Window in days, 1 to 730.",
            "schema": {
              "type": "integer",
              "default": 90,
              "minimum": 1,
              "maximum": 730
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key created on the KidArt AI dashboard."
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "No valid API key. Send it as Authorization: Bearer <key> or X-API-Key. Create keys on the dashboard (an account admin can).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          },
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such item for this account. Another account's ids look exactly like missing ones.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          },
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "TooMany": {
        "description": "A per-account hourly limit was reached (by default 30 analyses and 120 previews an hour). Try again later.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          },
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "BadRequest": {
        "description": "The request could not be read: malformed JSON or base64, an unknown field, or no photo.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          },
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "TooLarge": {
        "description": "The upload is larger than the limit (10 MB by default).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          },
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Unsupported": {
        "description": "The photo is not a JPEG or PNG, or the body is not JSON / multipart.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          },
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "A relative URI naming the kind of problem, such as /errors/validation-error."
          },
          "title": {
            "type": "string",
            "description": "A short, stable summary."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status."
          },
          "code": {
            "type": "string",
            "description": "A stable machine-readable code, such as VALIDATION_ERROR or PAYMENT_REQUIRED."
          },
          "detail": {
            "type": "string",
            "description": "A sentence for a person, safe to show to the adult using your product."
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            },
            "description": "Per-field messages when the problem is about specific inputs."
          },
          "timestamp": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "subscribe_url": {
            "type": "string",
            "description": "On a 403 for a missing subscription: where the customer subscribes to KidArt AI on the Sensifai Marketplace."
          },
          "top_up_url": {
            "type": "string",
            "description": "On a 402: where the customer tops up the prepaid wallet."
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "code",
          "timestamp"
        ],
        "description": "An RFC 7807 problem. The same shape the Sensifai Gatekeeper returns, so one parser handles both."
      },
      "Option": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "label",
          "hint"
        ],
        "description": "One value of a closed list: a stable id to send, a friendly label and a short hint."
      },
      "Meta": {
        "type": "object",
        "properties": {
          "age_bands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Option"
            }
          },
          "materials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Option"
            }
          },
          "subjects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Option"
            }
          },
          "techniques": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Option"
            }
          },
          "shapes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Option"
            }
          },
          "hazards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Option"
            }
          },
          "max_album_title": {
            "type": "integer"
          },
          "max_entry_title": {
            "type": "integer"
          },
          "max_entry_note": {
            "type": "integer"
          }
        },
        "required": [
          "age_bands",
          "materials",
          "subjects",
          "techniques",
          "shapes",
          "hazards"
        ],
        "description": "Every closed list the API accepts or returns, so a client never hard-codes one. The three max_* values are limits for the dashboard's portfolio texts and are not used by this API."
      },
      "StartRequest": {
        "type": "object",
        "properties": {
          "photo": {
            "type": "string",
            "description": "The picture as base64 (a data: URL is accepted), JPEG or PNG, up to the size limit. Required in the JSON form; in multipart send a file field named photo instead.",
            "format": "byte"
          },
          "age_band": {
            "type": "string",
            "description": "The child's age range, chosen by the adult.",
            "enum": [
              "3-4",
              "5-6",
              "7-9",
              "10-12"
            ]
          },
          "materials": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "paper",
                "crayons",
                "markers",
                "pencils",
                "paints",
                "glue",
                "scissors",
                "colored_paper",
                "cardboard",
                "clay",
                "stickers",
                "natural",
                "recycled",
                "yarn",
                "cotton_balls",
                "sponges",
                "tape"
              ]
            },
            "description": "What the family has at home. Paper is always implied. Activities are chosen so that every material they need is in this list."
          },
          "subject": {
            "type": "string",
            "description": "What the adult says the picture shows. Optional; when given it steers the activity choice and is echoed in report.subject.",
            "enum": [
              "garden",
              "flowers",
              "tree",
              "sun_sky",
              "rainbow",
              "house",
              "animals",
              "birds",
              "sea",
              "insects",
              "vehicles",
              "people",
              "food",
              "space",
              "fantasy",
              "pattern",
              "landscape",
              "other"
            ]
          },
          "album_id": {
            "type": "string",
            "description": "File the result into one of the account's portfolio albums when the portfolio is kept. Optional; an unknown id is a 422."
          }
        },
        "required": [
          "photo",
          "age_band"
        ],
        "description": "Send as JSON, or as multipart/form-data with a photo file and the other fields as text fields (materials comma-separated)."
      },
      "Accepted": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string",
            "description": "Also the analysis id once the job has succeeded."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued"
            ]
          },
          "poll": {
            "type": "string",
            "description": "Path of the job to poll, for example /api/v1/jobs/{job_id}. Also sent in the Location header."
          }
        },
        "required": [
          "job_id",
          "status",
          "poll"
        ]
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ]
          },
          "analysis_id": {
            "type": "string",
            "description": "Set once the job succeeded; fetch /api/v1/analyses/{analysis_id}."
          },
          "age_band": {
            "type": "string",
            "enum": [
              "3-4",
              "5-6",
              "7-9",
              "10-12"
            ]
          },
          "error": {
            "type": "string",
            "description": "When status is failed: a sentence saying why (for example that no drawing could be seen in the photo). A failed job is never charged."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "status",
          "age_band",
          "created_at"
        ],
        "description": "The state of one analysis. Poll about every two seconds; most finish in a few seconds to half a minute."
      },
      "Quality": {
        "type": "object",
        "properties": {
          "score": {
            "type": "integer",
            "description": "Photo quality, 0 to 100. This describes the photograph (light, focus, framing), never the artwork or the child."
          },
          "usable": {
            "type": "boolean",
            "description": "False when the photo is too dark, blurry, small or empty to read reliably."
          },
          "problems": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Short words for what lowered the score, such as too_dark, blurry, glare, small_in_frame."
          }
        },
        "required": [
          "score",
          "usable",
          "problems"
        ]
      },
      "Measured": {
        "type": "object",
        "properties": {
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "crop_applied": {
            "type": "boolean",
            "description": "True when the paper edges or background were cut away first."
          },
          "paper_hex": {
            "type": "string"
          },
          "palette": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "hex": {
                  "type": "string"
                },
                "share": {
                  "type": "number",
                  "description": "Share of the marked area, 0 to 1."
                }
              },
              "required": [
                "hex",
                "share"
              ]
            }
          },
          "coverage": {
            "type": "number",
            "description": "Fraction of the page carrying marks, 0 to 1."
          },
          "centroid_x": {
            "type": "number"
          },
          "centroid_y": {
            "type": "number"
          },
          "symmetry": {
            "type": "number",
            "description": "Left-right mirror similarity of the marks, 0 to 1."
          },
          "spread": {
            "type": "number",
            "description": "Share of a 3x3 grid of the page that holds marks."
          },
          "stroke_width": {
            "type": "number",
            "description": "Median mark thickness as a fraction of the page's shorter side."
          },
          "edge_density": {
            "type": "number"
          },
          "Round": {
            "type": "integer",
            "description": "Count of roundish regions."
          },
          "Lines": {
            "type": "integer",
            "description": "Count of elongated marks."
          },
          "Dots": {
            "type": "integer",
            "description": "Count of tiny round marks."
          },
          "RoundSimilar": {
            "type": "integer",
            "description": "Largest group of roundish regions of similar size."
          },
          "Regions": {
            "type": "integer",
            "description": "All separate marks."
          }
        },
        "description": "The raw numbers measured from the pixels, in Go, with no model. Everything in the report that is a fact derives from these. Note: the five counts (Round, Lines, Dots, RoundSimilar, Regions) are currently emitted with capitalised names; treat the object as informational and prefer the derived fields of the report.",
        "additionalProperties": true
      },
      "ObservedColor": {
        "type": "object",
        "properties": {
          "hex": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "A crayon-box name derived from the hex value, such as sunshine yellow."
          },
          "family": {
            "type": "string",
            "enum": [
              "red",
              "orange",
              "yellow",
              "green",
              "blue",
              "purple",
              "pink",
              "brown",
              "black",
              "white",
              "gray"
            ]
          },
          "share_percent": {
            "type": "integer",
            "description": "Whole percent of the marked area."
          }
        },
        "required": [
          "hex",
          "name",
          "family",
          "share_percent"
        ],
        "description": "A colour measured in the picture. Colours are never chosen by a model."
      },
      "ShapeObs": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "circle",
              "line",
              "dots",
              "zigzag",
              "wavy_line",
              "spiral",
              "square",
              "triangle",
              "star",
              "heart",
              "cross",
              "blob"
            ]
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "description": "Present only for shapes that were measured (circle, line, dots)."
          },
          "source": {
            "type": "string",
            "description": "measured: counted in Go from the pixels. ai: the model's reading of the picture, shown as such and never counted.",
            "enum": [
              "measured",
              "ai"
            ]
          }
        },
        "required": [
          "id",
          "label",
          "source"
        ]
      },
      "CompositionFact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "fill",
              "placement",
              "balance",
              "stroke",
              "contrast",
              "variety"
            ]
          },
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string",
            "description": "A fixed word, such as sparse, moderate or full for fill; centred, left, bottom and so on for placement."
          },
          "text": {
            "type": "string",
            "description": "A sentence generated from the measurement by a template."
          },
          "basis": {
            "type": "string",
            "description": "The measurement behind it, in words, for example marks cover 13% of the page."
          }
        },
        "required": [
          "id",
          "label",
          "value",
          "text",
          "basis"
        ],
        "description": "One statement about how the page is used, derived from the measurements."
      },
      "StyleDial": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "low_label": {
            "type": "string"
          },
          "high_label": {
            "type": "string"
          },
          "value": {
            "type": "integer",
            "description": "0 to 10 on an intensity scale between the two poles.",
            "minimum": 0,
            "maximum": 10
          },
          "basis": {
            "type": "string",
            "description": "The measurement behind the value, in words."
          }
        },
        "required": [
          "id",
          "label",
          "low_label",
          "high_label",
          "value",
          "basis"
        ],
        "description": "A dial describing how the picture is made, for example fine to bold strokes. Neither end is better; it is not a grade and says nothing about the child."
      },
      "TechniqueObs": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "crayon",
              "marker",
              "colored_pencil",
              "watercolor_wash",
              "paint_brushstrokes",
              "finger_paint",
              "collage",
              "stamping",
              "stickers",
              "mixed_media",
              "scribble_fill",
              "outline_and_fill",
              "dotting",
              "layering"
            ]
          },
          "label": {
            "type": "string"
          },
          "confidence": {
            "type": "string",
            "description": "A photo cannot prove a medium, so a technique is only ever possible or likely.",
            "enum": [
              "possible",
              "likely"
            ]
          }
        },
        "required": [
          "id",
          "label",
          "confidence"
        ]
      },
      "MaterialRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "paper",
              "crayons",
              "markers",
              "pencils",
              "paints",
              "glue",
              "scissors",
              "colored_paper",
              "cardboard",
              "clay",
              "stickers",
              "natural",
              "recycled",
              "yarn",
              "cotton_balls",
              "sponges",
              "tape"
            ]
          },
          "label": {
            "type": "string"
          },
          "owned": {
            "type": "boolean",
            "description": "True when the family has it."
          }
        },
        "required": [
          "id",
          "label",
          "owned"
        ]
      },
      "ActivityCard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "A stable id from the curated catalogue."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "why": {
            "type": "string",
            "description": "Ties the activity to this picture. A template, or a model sentence that passed the safety filter."
          },
          "why_by_ai": {
            "type": "boolean"
          },
          "minutes": {
            "type": "integer"
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "materials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MaterialRef"
            },
            "description": "Required materials; all of them are owned in a delivered report."
          },
          "optional_materials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MaterialRef"
            }
          },
          "hooks": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "circles",
                "repetition",
                "lines",
                "colour_contrast",
                "warm_colours",
                "cool_colours",
                "bold_strokes",
                "fine_detail",
                "full_page",
                "open_space",
                "symmetry",
                "nature",
                "animals",
                "story",
                "pattern",
                "texture",
                "colour_mixing",
                "building",
                "figures",
                "space",
                "sea",
                "food"
              ]
            },
            "description": "The themes the activity builds on."
          },
          "hazards": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "small_parts",
                "scissors",
                "mess",
                "glue",
                "ingestion",
                "natural",
                "outdoors"
              ]
            }
          },
          "supervision": {
            "type": "string",
            "description": "How close an adult should be for this activity at this age.",
            "enum": [
              "independent",
              "nearby",
              "hands_on"
            ]
          },
          "age_band": {
            "type": "string",
            "enum": [
              "3-4",
              "5-6",
              "7-9",
              "10-12"
            ]
          },
          "matched_on": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "circles",
                "repetition",
                "lines",
                "colour_contrast",
                "warm_colours",
                "cool_colours",
                "bold_strokes",
                "fine_detail",
                "full_page",
                "open_space",
                "symmetry",
                "nature",
                "animals",
                "story",
                "pattern",
                "texture",
                "colour_mixing",
                "building",
                "figures",
                "space",
                "sea",
                "food"
              ]
            },
            "description": "The observed themes of this picture the activity grew from."
          }
        },
        "required": [
          "id",
          "title",
          "summary",
          "why",
          "minutes",
          "steps",
          "materials",
          "supervision",
          "age_band"
        ],
        "description": "One suggested activity. Activities are picked from a curated catalogue and re-checked in Go against the age band and the materials at home; the model only chooses among a shortlist and writes the why."
      },
      "Check": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "detail": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "label",
          "ok"
        ],
        "description": "One result of the independent verifier. A failing check is shown, never hidden."
      },
      "Report": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "age_band": {
            "type": "string",
            "enum": [
              "3-4",
              "5-6",
              "7-9",
              "10-12"
            ]
          },
          "subject": {
            "type": "string",
            "description": "The adult-confirmed subject, when given.",
            "enum": [
              "garden",
              "flowers",
              "tree",
              "sun_sky",
              "rainbow",
              "house",
              "animals",
              "birds",
              "sea",
              "insects",
              "vehicles",
              "people",
              "food",
              "space",
              "fantasy",
              "pattern",
              "landscape",
              "other"
            ]
          },
          "observed_colors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ObservedColor"
            },
            "description": "Measured, descending share."
          },
          "shapes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShapeObs"
            }
          },
          "composition": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompositionFact"
            }
          },
          "style_scores": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StyleDial"
            },
            "description": "Eight descriptive dials."
          },
          "possible_techniques": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TechniqueObs"
            }
          },
          "subjects": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "garden",
                "flowers",
                "tree",
                "sun_sky",
                "rainbow",
                "house",
                "animals",
                "birds",
                "sea",
                "insects",
                "vehicles",
                "people",
                "food",
                "space",
                "fantasy",
                "pattern",
                "landscape",
                "other"
              ]
            },
            "description": "What the model saw in the picture, from a closed list. This is the model's reading."
          },
          "description": {
            "type": "string",
            "description": "One warm descriptive paragraph about the picture. Never about the child."
          },
          "description_by_ai": {
            "type": "boolean",
            "description": "False when the model's sentence failed the safety filter and a template was used instead."
          },
          "positive_feedback": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Short, specific, positive remarks about what is in the picture."
          },
          "feedback_by_ai": {
            "type": "boolean"
          },
          "activities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActivityCard"
            },
            "description": "Two or three activities."
          },
          "materials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MaterialRef"
            },
            "description": "The union of what the suggested activities need, with whether the family has it."
          },
          "supervision_notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Adult-facing safety lines derived from the activities' hazards and the age band."
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Check"
            }
          },
          "checks_passed": {
            "type": "boolean",
            "description": "True when every check passed."
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Honest limits, for example a shape the model read but Go could not confirm, writing seen in the picture, or a fallback that was used."
          },
          "identifying_text_visible": {
            "type": "boolean",
            "description": "True when the model saw writing (such as a name) in the artwork. The thumbnail is not kept then."
          }
        },
        "required": [
          "version",
          "age_band",
          "observed_colors",
          "shapes",
          "composition",
          "possible_techniques",
          "description",
          "positive_feedback",
          "activities",
          "materials",
          "supervision_notes",
          "checks",
          "checks_passed"
        ],
        "description": "The reading of one drawing. Facts (colours, counts, composition words, activities, materials, supervision notes) come from Go; the model reads subjects, shapes and techniques from closed lists and writes sentences, and any sentence that grades, compares, diagnoses, quotes a number or talks about the child is replaced by a template. There is no score, grade, rank or comparison with other children, and no emotional, personality or developmental reading."
      },
      "Result": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "image_quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "measured": {
            "$ref": "#/components/schemas/Measured"
          },
          "white_balanced": {
            "type": "boolean",
            "description": "True when uneven light was corrected for the measurements."
          },
          "report": {
            "$ref": "#/components/schemas/Report"
          },
          "prompt": {
            "type": "string",
            "description": "The reading prompt and version used."
          },
          "prompt_fingerprint": {
            "type": "string"
          }
        },
        "required": [
          "version",
          "image_quality",
          "measured",
          "report"
        ]
      },
      "Entry": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "album_id": {
            "type": "string"
          },
          "favourite": {
            "type": "boolean"
          },
          "saved_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "description": "The adult's portfolio entry, when the dashboard saved one. The portfolio is managed on the dashboard, not through this API."
      },
      "SavedActivity": {
        "type": "object",
        "properties": {
          "artwork_id": {
            "type": "string"
          },
          "activity_id": {
            "type": "string"
          },
          "done": {
            "type": "boolean"
          },
          "saved_at": {
            "type": "string",
            "format": "date-time"
          },
          "done_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "activity_id",
          "done",
          "saved_at"
        ]
      },
      "Analysis": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "result": {
            "$ref": "#/components/schemas/Result"
          },
          "has_thumbnail": {
            "type": "boolean",
            "description": "A small thumbnail is kept only when the adult's setting allows it and no writing was seen. It is shown on the dashboard, not through this API."
          },
          "units": {
            "type": "integer",
            "description": "Units reported to the marketplace for this analysis (one)."
          },
          "cost_eur": {
            "type": "number",
            "description": "What this analysis cost the customer on their plan; 0 inside the free allowance."
          },
          "source": {
            "type": "string",
            "enum": [
              "dashboard",
              "api"
            ]
          },
          "entry": {
            "$ref": "#/components/schemas/Entry"
          },
          "saved_activities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SavedActivity"
            }
          }
        },
        "required": [
          "id",
          "created_at",
          "result",
          "units",
          "source",
          "saved_activities"
        ],
        "description": "One delivered analysis."
      },
      "AnalysisSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "age_band": {
            "type": "string",
            "enum": [
              "3-4",
              "5-6",
              "7-9",
              "10-12"
            ]
          },
          "palette": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Up to six hex colours, descending share."
          },
          "color_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Crayon names of the top three colours."
          },
          "subjects": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "activities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Titles of the suggested activities."
          },
          "checks_passed": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          },
          "has_thumbnail": {
            "type": "boolean"
          },
          "units": {
            "type": "integer"
          },
          "entry": {
            "$ref": "#/components/schemas/Entry"
          }
        },
        "required": [
          "id",
          "status",
          "created_at",
          "age_band",
          "palette",
          "color_names",
          "subjects",
          "activities",
          "checks_passed",
          "units"
        ],
        "description": "One row of the list."
      },
      "PreviewResult": {
        "type": "object",
        "properties": {
          "usable": {
            "type": "boolean",
            "description": "False when the photo cannot be analysed; message then says why. A preview of an unusable photo is still a 200."
          },
          "message": {
            "type": "string",
            "description": "A sentence for the adult when usable is false."
          },
          "image_quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "measured": {
            "$ref": "#/components/schemas/Measured"
          },
          "white_balanced": {
            "type": "boolean"
          },
          "observed_colors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ObservedColor"
            }
          },
          "shapes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShapeObs"
            }
          },
          "composition": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompositionFact"
            }
          },
          "thumbnail": {
            "type": "string",
            "description": "A JPEG of the cropped page, base64, at most 480 px. Not stored."
          }
        },
        "required": [
          "usable",
          "image_quality",
          "observed_colors",
          "shapes",
          "composition"
        ],
        "description": "The free, local half of an analysis: photo quality and what was measured. No model is called, nothing is stored and nothing is billed."
      },
      "LibraryItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ActivityCard"
          },
          {
            "type": "object",
            "properties": {
              "ready": {
                "type": "boolean",
                "description": "True when the family already has every required material."
              }
            },
            "required": [
              "ready"
            ]
          }
        ]
      },
      "Library": {
        "type": "object",
        "properties": {
          "age_band": {
            "type": "string",
            "enum": [
              "3-4",
              "5-6",
              "7-9",
              "10-12"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LibraryItem"
            }
          },
          "total": {
            "type": "integer"
          }
        },
        "required": [
          "age_band",
          "items",
          "total"
        ],
        "description": "The curated activity catalogue for an age band. Items that need nothing the family lacks come first. The cards carry no why or matched_on (nothing was observed)."
      },
      "CountRow": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          }
        },
        "required": [
          "name",
          "count"
        ]
      },
      "History": {
        "type": "object",
        "properties": {
          "keep_portfolio": {
            "type": "boolean",
            "description": "False when the account turned the portfolio history off; new analyses then add nothing here."
          },
          "days": {
            "type": "integer",
            "description": "The window the counts cover."
          },
          "total": {
            "type": "integer",
            "description": "Analyses in the window."
          },
          "weekly": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "week": {
                  "type": "string",
                  "description": "The Monday of the week, YYYY-MM-DD."
                },
                "count": {
                  "type": "integer"
                },
                "coverage": {
                  "type": "number",
                  "description": "Mean share of the page carrying marks, 0 to 1."
                }
              },
              "required": [
                "week",
                "count",
                "coverage"
              ]
            }
          },
          "colors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountRow"
            },
            "description": "Crayon colour families, most common first."
          },
          "techniques": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountRow"
            }
          },
          "shapes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountRow"
            }
          },
          "subjects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountRow"
            }
          },
          "activities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountRow"
            },
            "description": "Suggested activity ids."
          }
        },
        "required": [
          "keep_portfolio",
          "days",
          "total",
          "weekly",
          "colors",
          "techniques",
          "shapes",
          "subjects",
          "activities"
        ],
        "description": "Trends across the account's delivered analyses: aggregated counts of colours, techniques, shapes and subjects, and a weekly strip. Nothing here compares children or the account with anyone else."
      }
    }
  }
}
