openapi: 3.1.0
# Published on the public docs site, as a reference page and as this file.
# A contract without this key is internal.
x-docs-visibility: public
info:
  title: Assessor.io API v2 (public) - Template authoring
  version: 1.3.1
  description: |
    The external-agent door onto the same template-authoring pipeline the
    in-app BIMei AI Assistant uses: retrieval over Action Statements and
    library items, reading templates/scales/labels, and the Blueprint
    create -> run assistant -> validate -> compile flow. Every operation here
    is scoped to the accountId in the path and to one of four scopes:
    statements:read, templates:read, templates:write, blueprints:write.

    ONLY A HUMAN PUBLISHES. No operation in this file
    can set a template Active, distribute it, or attach it to a campaign.
    `POST …/blueprints/{blueprintId}/compile` is the only write that creates a
    template at all, and it is always created Draft.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicRetrieval
  - name: PublicTemplates
  - name: PublicBlueprints
paths:
  /api/v2/public/accounts/{accountId}/retrieval:
    get:
      tags: [PublicRetrieval]
      operationId: v2SearchRetrieval
      summary: Search Action Statements, library items and prior template questions.
      description: |
        Hybrid (lexical + semantic) search over one or more entity types for a
        piece of brief/blueprint text, scoped to what this account can see:
        ONT-mirrored global statements, statements/items distributed to the
        account, and the account's own. Scope statements:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - name: q
          in: query
          required: true
          description: The search text. 400 when missing or empty.
          schema:
            type: string
        - name: types
          in: query
          required: false
          description: Comma-separated entity types. Defaults to all three when omitted or empty.
          schema:
            type: string
            example: statement,item,template_question
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
        - name: vetting
          in: query
          required: false
          description: 'Statements only: comma-separated vetting tiers to keep.'
          schema:
            type: string
            example: ont,local
        - name: liveOnly
          in: query
          required: false
          description: 'Pass liveOnly=false to include withdrawn ONT statements and retired items. Defaults to true.'
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Retrieval hits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/templates:
    get:
      tags: [PublicTemplates]
      operationId: v2ListTemplates
      summary: List the account's assessment templates.
      description: |
        The account's own local templates plus every global template
        distributed to it. Scope templates:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TemplateLifecycleStatus'
        - name: search
          in: query
          required: false
          schema:
            type: string
        - $ref: '../components/v2-common.yaml#/components/parameters/Page'
        - $ref: '../components/v2-common.yaml#/components/parameters/Limit'
      responses:
        '200':
          description: Templates loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTemplateListResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/templates/{templateId}:
    get:
      tags: [PublicTemplates]
      operationId: v2GetTemplate
      summary: Read one template (body + metadata).
      description: |
        404 when the template does not exist, belongs to a different
        account, or is a global template not distributed to this one — an
        integrator cannot probe for ids outside its own scope. Scope templates:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '#/components/parameters/TemplateId'
      responses:
        '200':
          description: Template loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTemplateDetailResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/templates/validate:
    post:
      tags: [PublicTemplates]
      operationId: v2ValidateTemplate
      summary: Run the authoring Check against a template body, without saving it.
      description: |
        Runs the same authoring validation an Active save runs
        (`validateTemplateAuthoring`), resolved against the account's own
        scoring overlay (its visible answer scales and label vocabulary) so
        an asrScale/lbls reference is checked for real. Writes nothing.
        Scope templates:read.
        A retired or merged scale is not resolved (since 1.1.0), so a body
        naming one gets the UNKNOWN_SCALE warning, as in the Studio's Check.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [surveyJsSchema]
              properties:
                surveyJsSchema:
                  type: object
                  description: The raw SurveyJS authoring JSON to check.
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateValidationResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/scales:
    get:
      tags: [PublicTemplates]
      operationId: v2ListScales
      summary: List answer scales usable in this account.
      description: |
        The bimmas-v1 built-in scales plus every scale visible to the
        account (its own custom scales, and every global custom scale).
        Scope templates:read.

        Since 1.1.0 the custom scales are filtered by lifecycle: by default
        only `active` and `deprecated` ones are listed, because a retired or
        merged scale may not be named by a new question. Pass `status=all`
        for every scale. Each custom scale carries its `status`, and a
        deprecated one the key to `useInstead` when it names one.

        Since 1.3.0 a scale carries its French name (`nameFr`) when it has
        one, and a custom scale its own labels for its N/A and not-sure
        values (`sentinelLabels`) when it has any.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - name: status
          in: query
          required: false
          description: |
            Which custom scales to list, by lifecycle: a comma-separated list
            of `active`, `deprecated`, `retired` and `merged`, or `all`.
            Absent means `active,deprecated`. An unknown value is ignored.
          schema:
            type: string
            example: active,deprecated
      responses:
        '200':
          description: Scales loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicScaleListResponse'
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/labels:
    get:
      tags: [PublicTemplates]
      operationId: v2ListLabels
      summary: List the account's visible label vocabulary.
      description: |
        The account's own local labels plus every global label group
        distributed to it. Scope templates:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - name: groupId
          in: query
          required: false
          schema:
            type: string
        - name: scope
          in: query
          required: false
          schema:
            type: string
            enum: [all, global, local]
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Labels loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicLabelListResponse'
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/blueprints:
    post:
      tags: [PublicBlueprints]
      operationId: v2CreateBlueprint
      summary: Start a Blueprint from pasted brief text.
      description: |
        Creates the authoring pre-stage document — not a template, and
        not visible to a respondent. Paste only: a service token has no
        account file to point at. Scope blueprints:write.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlueprintRequest'
      responses:
        '201':
          description: Blueprint created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlueprintResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/blueprints/{blueprintId}:
    get:
      tags: [PublicBlueprints]
      operationId: v2GetBlueprint
      summary: Read a Blueprint's full state.
      description: |
        Version, sources, requirements, matches, proposed
        statements/labels/scales, pages and items. Scope templates:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '#/components/parameters/BlueprintId'
      responses:
        '200':
          description: Blueprint loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlueprintResponse'
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/blueprints/{blueprintId}/validate:
    post:
      tags: [PublicBlueprints]
      operationId: v2ValidateBlueprint
      summary: Run the Blueprint readiness gate, without compiling.
      description: |
        Runs the same gate `asr_compile_blueprint` will run, with the
        account's scales and label vocabulary, and returns the reviewer
        summary. Writes nothing. Scope templates:read — a POST only because
        it carries a body (includePending) and is not cacheable.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '#/components/parameters/BlueprintId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                includePending:
                  type: boolean
                  description: Also check pending (not-yet-accepted) matches/proposals.
      responses:
        '200':
          description: Check summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlueprintCheckResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/blueprints/{blueprintId}/aia:
    post:
      tags: [PublicBlueprints]
      operationId: v2RunBlueprintAssistant
      summary: Run the BIMei AI Assistant over a Blueprint.
      description: |
        step extract|match|draft|all. A MODEL ROUTE: refused with 503 while
        the platform model kill switch is on, checked before authentication.
        Every step is checked by the reference/schema validator before
        anything is saved. Writes the blueprint; never touches a template.
        Scope blueprints:write.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '#/components/parameters/BlueprintId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunAiaRequest'
      responses:
        '200':
          description: Assistant run result (a refused candidate is reported here, not a 4xx).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiaRunResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '409':
          description: Version conflict, or the run's own candidate refusal (CANDIDATE_REFUSED).
          content:
            application/json:
              schema:
                $ref: '../../v1/components/envelopes.yaml#/components/schemas/ErrorEnvelopeWithCode'
        '422':
          description: The model's candidate was refused by the reference/schema validator.
          content:
            application/json:
              schema:
                $ref: '../../v1/components/envelopes.yaml#/components/schemas/ErrorEnvelopeWithCode'
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
        '503':
          description: Model routes are disabled (platform kill switch).
          content:
            application/json:
              schema:
                $ref: '../../v1/components/envelopes.yaml#/components/schemas/ErrorEnvelope'
  /api/v2/public/accounts/{accountId}/blueprints/{blueprintId}/compile:
    post:
      tags: [PublicBlueprints]
      operationId: v2CompileBlueprint
      summary: Compile a ready Blueprint into a Draft template.
      description: |
        The ONLY operation in this file that creates a template, and it is
        ALWAYS created with lifecycle.status Draft — nothing here can set it
        Active, distribute it, or attach it to a campaign (only a human does
        that, from the app). Refused with 409
        BLUEPRINT_NOT_READY unless the gate says ready, or includePending:
        true explicitly asks for a working draft. Requires BOTH
        blueprints:write (this mutates the blueprint) AND templates:write
        (this creates a template) — a token holding only the first is
        refused with 403 naming the missing scope.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '#/components/parameters/BlueprintId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [expectedVersion]
              properties:
                expectedVersion:
                  type: integer
                includePending:
                  type: boolean
      responses:
        '201':
          description: Compiled. A Draft template was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompileBlueprintResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '409':
          description: BLUEPRINT_VERSION_CONFLICT, BLUEPRINT_ALREADY_COMPILED, BLUEPRINT_NOT_READY, or a template name conflict.
          content:
            application/json:
              schema:
                $ref: '../../v1/components/envelopes.yaml#/components/schemas/ErrorEnvelopeWithCode'
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
components:
  securitySchemes:
    serviceToken:
      $ref: '../components/v2-security.yaml#/components/securitySchemes/serviceToken'
  parameters:
    TemplateId:
      name: templateId
      in: path
      required: true
      description: Template id. Must belong to accountId (local) or be distributed to it (global), otherwise 404.
      schema:
        type: string
    BlueprintId:
      name: blueprintId
      in: path
      required: true
      description: Blueprint id. Must belong to accountId, otherwise 404.
      schema:
        type: string
  schemas:
    TemplateLifecycleStatus:
      type: string
      enum: [Draft, Active, Archived]
    RetrievalHit:
      type: object
      required: [entityType, entityId, text, score, via, meta]
      properties:
        entityType:
          type: string
          enum: [statement, item, template_question]
        entityId:
          type: string
          description: 'statement id | assessment_items id | "{templateId}::{questionName}"'
        text:
          type: string
        score:
          type: number
          description: 0..1, comparable within one response only.
        via:
          type: string
          enum: [lexical, semantic, both]
        meta:
          type: object
          properties:
            vetting:
              type: string
              enum: [ont, local, proposed]
            ontIri:
              type: string
              nullable: true
            ontStatus:
              type: string
              enum: [candidate, canonical]
              nullable: true
            scaleKey:
              type: string
              nullable: true
            lbls:
              type: array
              items:
                type: string
            statementRef:
              type: string
              nullable: true
            templateId:
              type: string
            templateName:
              type: string
            accountId:
              type: string
              nullable: true
    RetrievalResult:
      type: object
      required: [hits, mode]
      properties:
        hits:
          type: array
          items:
            $ref: '#/components/schemas/RetrievalHit'
        mode:
          type: string
          enum: [hybrid, lexical-only]
    RetrievalResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/RetrievalResult'
    PublicTemplate:
      type: object
      description: The template contract record (toTemplateContractRecord) — body + metadata.
      required: [id, name, surveyJsSchema, statementIds, lifecycle, scope]
      properties:
        id:
          type: string
        accountId:
          type: string
        name:
          type: string
        description:
          type: string
        isLocked:
          type: boolean
        surveyJsSchema:
          type: object
        customFields:
          type: array
          items:
            type: object
        statementIds:
          type: array
          items:
            type: string
        lifecycle:
          type: object
        createdAt:
          type: integer
          description: Epoch milliseconds.
        updatedAt:
          type: integer
          description: Epoch milliseconds.
        scope:
          type: string
          enum: [global, local]
    PublicTemplateListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data, meta]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicTemplate'
            meta:
              $ref: '../components/v2-common.yaml#/components/schemas/PageMeta'
    PublicTemplateDetailResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/PublicTemplate'
    AuthoringIssue:
      type: object
      required: [code, message, path]
      properties:
        code:
          type: string
        message:
          type: string
        path:
          type: string
        questionName:
          type: string
    TemplateAuthoringValidation:
      type: object
      required: [errors, warnings]
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/AuthoringIssue'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/AuthoringIssue'
    TemplateValidationResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/TemplateAuthoringValidation'
    PublicScale:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
        nameFr:
          type: string
          description: >-
            Since 1.3.0 — the French name (a custom scale's own, or a built-in's
            French label). Absent when there is none; read `name` instead.
        kind:
          type: string
        naValues:
          type: array
          items:
            type: string
        notSureValues:
          type: array
          items:
            type: string
        sentinelLabels:
          type: object
          description: >-
            Since 1.3.0, custom scales only — the scale's own labels for its N/A
            and not-sure values, keyed by the value as listed in `naValues` /
            `notSureValues`. Absent when the scale has none; a value without an
            entry reads the platform's default label ("Not applicable" / "Sans
            objet", "Not sure" / "Je ne sais pas").
          additionalProperties:
            type: object
            required: [label]
            properties:
              label:
                type: string
              labelFr:
                type: string
        levels:
          type: array
          description: >-
            Since 1.2.0, an unordered list with no metric (kind `closed-list`, for
            example) may carry from 1 to 500 options — a single consent or confirm
            step, or a long list. An ordered scale carries 2 to 20 levels.
          items:
            type: object
        status:
          type: string
          enum: [active, deprecated, retired, merged]
          description: Custom scales only (since 1.1.0) — the scale's lifecycle. Absent on a built-in.
        useInstead:
          type: string
          description: A deprecated custom scale only (since 1.1.0) — the key of the scale to use instead, when one is named.
    PublicScaleListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicScale'
    PublicLabel:
      type: object
      properties:
        id:
          type: string
        accountId:
          type: string
        groupId:
          type: string
        groupName:
          type: string
        name:
          type: string
        description:
          type: string
        abbreviation:
          type: string
        position:
          type: integer
        createdAt:
          type: integer
        updatedAt:
          type: integer
        scope:
          type: string
          enum: [global, local]
        groupScope:
          type: string
          enum: [global, local]
    PublicLabelListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicLabel'
    CreateBlueprintRequest:
      type: object
      required: [title, mode, unit, text]
      properties:
        title:
          type: string
        mode:
          type: string
          enum: [manual, copilot, autopilot]
        unit:
          type: string
          enum: [participant, organisation, group]
        text:
          type: string
          description: The pasted brief. No upload source on this surface.
    Blueprint:
      type: object
      description: The Blueprint document. The nested objects (pages, items, requirements and the proposals) are listed by name only; this contract does not describe their fields.
      required: [title, mode, unit, target, version]
      properties:
        title:
          type: string
        mode:
          type: string
          enum: [manual, copilot, autopilot]
        unit:
          type: string
          enum: [participant, organisation, group]
        target:
          type: object
        version:
          type: integer
        status:
          type: string
        pages:
          type: array
          items:
            type: object
        items:
          type: array
          items:
            type: object
        requirements:
          type: array
          items:
            type: object
        matches:
          type: array
          items:
            type: object
        proposedStatements:
          type: array
          items:
            type: object
        proposedLabels:
          type: array
          items:
            type: object
        proposedScales:
          type: array
          description: >-
            Since 1.2.0 a proposed scale's `levels` follow the registry's count
            for its kind: 1 to 500 options for `closed-list` (or another
            unordered kind), 2 to 20 levels for an ordered kind.
          items:
            type: object
    BlueprintResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/Blueprint'
    BlueprintCheckResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: object
              required: [blueprintId, version, ready]
              properties:
                blueprintId:
                  type: string
                version:
                  type: integer
                ready:
                  type: boolean
                issues:
                  type: array
                  items:
                    type: object
    RunAiaRequest:
      type: object
      required: [step, expectedVersion]
      properties:
        step:
          type: string
          enum: [extract, match, draft, all]
        expectedVersion:
          type: integer
        threshold:
          type: number
          minimum: 0
          maximum: 1
    AiaRunResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: object
              required: [runId, version, steps]
              properties:
                runId:
                  type: string
                version:
                  type: integer
                model:
                  type: string
                promptVersions:
                  type: array
                  items:
                    type: string
                steps:
                  type: array
                  items:
                    type: object
    CompileBlueprintResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: object
              required: [templateId, studioUrl]
              properties:
                templateId:
                  type: string
                studioUrl:
                  type: string
                blueprint:
                  $ref: '#/components/schemas/Blueprint'
                check:
                  type: object
