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) - Assessment inventory (the codebook)
  version: 1.1.1
  description: |
    The INSTRUMENT behind a campaign's answers. Every other v2 read hands you
    answers keyed by machine name; this hands you what those names asked.

    Per assessment, the question inventory is projected from the SurveyJS body
    the assessment was ANSWERED against (the pinned template version, not
    whatever the template row holds today): name, type, the page it sat on, the
    question title and every part label per locale, the values a stored answer
    can take (matrix rows and columns, multipletext items, choices), the BIMMaS
    coding frame, and the visibleIf routing condition verbatim.

    Each question also carries exportColumns - the `ans:` column
    headers the results export writes, in the same fields export.codebook uses -
    so a downloaded column and a question can be joined by string equality.

    No respondent data is returned. Requires a service token holding
    campaigns:read and scoped to the accountId in the path.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicAssessments
paths:
  /api/v2/public/accounts/{accountId}/campaigns/{campaignId}/assessments:
    get:
      tags: [PublicAssessments]
      operationId: v2ListCampaignAssessments
      summary: The campaign's assessment inventory - the codebook.
      description: |
        Not paginated: a campaign holds a handful of assessments and a codebook
        is read whole. Returns 404 when the campaign does not exist OR belongs
        to another account. Scope campaigns:read - the inventory contains no
        respondent data and is the questionnaire every taker of the campaign is
        already served in full.

        What a schema-only projection cannot show: a part nobody declared but
        somebody answered, and the ::raw escape hatch, both of which a real
        export plans from a census of stored values. The export's shapeReport is
        where those are visible.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/CampaignId'
      responses:
        '200':
          description: Inventory loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssessmentInventoryResponse'
        '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' }
components:
  securitySchemes:
    serviceToken:
      $ref: '../components/v2-security.yaml#/components/securitySchemes/serviceToken'
  schemas:
    LocalizedText:
      type: object
      description: |
        A localized string, both ways. `text` is the resolved default-locale
        value - the same string export.codebook prints as questionTitle.
        `byLocale` is what the body declared, verbatim and unmerged, so an
        absent locale key means the body has no translation for it.
      properties:
        text: { type: string }
        byLocale:
          type: object
          additionalProperties: { type: string }
          examples:
            - { default: 'Policy', fr: 'Politique' }
    QuestionLabels:
      type: object
      description: |
        The coding frame as the author declared it (question metadata is
        labels, not structure). The five descriptive axes are reported as LABEL
        KEYS - the folded half of the question's `<groupKey>:<labelKey>`
        reference, so `D2` reads as `d2` and `MT-Po-10` as `mt_po_10`. This is
        the codebook's view and its job is to say what the body declared; the
        maturity engine is the layer that resolves a key back to a taxonomy code
        and reports the ones that resolve to nothing as a coverage gap. Nothing
        is validated here and nothing is silently dropped.
      properties:
        refs:
          type: array
          items: { type: string }
          description: |
            Every `<groupKey>:<labelKey>` reference the question carries, verbatim. The named
            fields below are the built-in axes; this is the generic half, so an account whose
            questions are labelled on a vocabulary of its own can read its own instrument.
        domain: { type: string, description: 'The domain: reference key - d1 to d9.' }
        theme: { type: string, description: 'The theme: reference key - a to d.' }
        topic: { type: string, description: "The reserved topic: reference key; read by nothing that scores." }
        tier: { type: string, description: 'The tier: reference key - mop, moe or moo.' }
        thread: { type: string, description: 'The thread: reference key - mt_po_10 and the like.' }
        scale: { type: string, description: 'asrScale - what the integers MEAN: maturity-5, bimmas-frequency-5, bimmas-trend-5.' }
        role: { type: string, description: 'asrRole - item, qualifier or ignore.' }
        qualifier: { type: string, description: 'The qualifier: reference key - which cohort axis this question supplies, e.g. province or org_size.' }
        weight: { type: number, description: 'asrWeight.' }
    InventoryPart:
      type: object
      description: |
        One addressable part of a question - a matrix row or column, a
        multipletext item, a choice. `value` is what a stored answer holds and
        what the ans: header's part segment carries.
      required: [value]
      properties:
        value: { type: string }
        label: { $ref: '#/components/schemas/LocalizedText' }
        cellType: { type: string }
        inputType: { type: string }
        choices:
          type: array
          items: { $ref: '#/components/schemas/InventoryPart' }
        labels:
          allOf:
            - $ref: '#/components/schemas/QuestionLabels'
          description: Row-level overrides - a matrix carries one maturity item per row.
    InventoryColumn:
      type: object
      description: |
        One export column this question generates, in export.codebook's own
        fields minus the four the parent question and assessment already state.
      required: [column, kind, description]
      properties:
        column: { type: string, examples: ['ans:maturity::policy'] }
        kind:
          type: string
          description: |
            The export codebook's kind. choice is a 0/1 indicator for one
            checkbox or tagbox choice; rank is one ranking choice, holding its
            1-based position in the respondent's order.
          enum: [value, cell, gridCell, choice, rank, file, raw]
        part: { type: string }
        partLabel: { type: string }
        subPart: { type: string }
        subPartLabel: { type: string }
        description: { type: string }
    InventoryQuestion:
      type: object
      required: [name, title, pageIndex, rows, columns, items, choices, exportColumns]
      properties:
        name: { type: string, description: 'The answer key a submission stores this question under.' }
        type: { type: string }
        page: { type: string }
        pageTitle: { $ref: '#/components/schemas/LocalizedText' }
        pageIndex: { type: integer }
        title: { $ref: '#/components/schemas/LocalizedText' }
        inputType: { type: string }
        cellType: { type: string }
        isRequired: { type: boolean }
        visibleIf:
          type: string
          description: |
            The routing condition, verbatim. Routing into Specialized Sets means
            different respondents answer different item sets; this is how an
            analyst tells a SKIPPED item from an unanswered one.
        enableIf: { type: string }
        requiredIf: { type: string }
        rows: { type: array, items: { $ref: '#/components/schemas/InventoryPart' } }
        columns: { type: array, items: { $ref: '#/components/schemas/InventoryPart' } }
        items: { type: array, items: { $ref: '#/components/schemas/InventoryPart' } }
        choices: { type: array, items: { $ref: '#/components/schemas/InventoryPart' } }
        labels: { $ref: '#/components/schemas/QuestionLabels' }
        legacy:
          type: object
          description: 'Pre-BIMMaS tags kept in the body: question_id (the legacy export Item ID) and "Topic id".'
          properties:
            questionId: { type: string }
            topicId: { type: string }
        exportColumns:
          type: array
          description: |
            Empty when another assessment of the same campaign declares this
            question name first - one file column exists, so exactly one
            assessment may claim it.
          items: { $ref: '#/components/schemas/InventoryColumn' }
    AssessmentInventory:
      type: object
      required: [assessmentId, questionCount, questions]
      properties:
        assessmentId: { type: string }
        assessmentKey: { type: string }
        assessmentName: { type: string }
        status:
          type: string
          enum: [Draft, Active, Completed]
        unit:
          type: object
          description: |
            WHO answers this instrument: `participant` (each
            person for themselves), `organisation` (once per organisation) or
            `group` (once per instance of the group `labelGroupId` names). A
            submission row alone cannot say whether one answer speaks for one
            person or for a department, and that decides what the row may be
            aggregated with.

            `labelGroupId` may be absent on a `group` unit whose label group has
            since been deleted; the assessment survives the deletion.
          required: [kind]
          properties:
            kind:
              type: string
              enum: [participant, organisation, group]
            labelGroupId: { type: string }
        defaultAvailability:
          type: string
          enum: [mandatory, optional, hidden]
          description: |
            What a participant is shown before any availability
            rule fires. The DEFAULT, not the resolved state: a rule over another
            assessment's answers can move it.
        templateId: { type: string }
        templateVersion: { type: string }
        templateVersionId:
          type: string
          description: 'The survey_template_versions row the questions were read from; empty when the live template was read.'
        templateFingerprint:
          type: string
          description: 'Digest of the question schema - the same value the export row prints, so a file and an inventory can be proved to describe one questionnaire.'
        questionCount: { type: integer }
        questions:
          type: array
          items: { $ref: '#/components/schemas/InventoryQuestion' }
    AssessmentInventoryResponse:
      type: object
      required: [success, data]
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          required: [campaignId, languages, assessmentCount, assessments]
          properties:
            campaignId: { type: string }
            languages:
              type: array
              description: "The account's enabled languages, filtered by the supported set - the locales byLocale can carry."
              items: { type: string }
            assessmentCount: { type: integer }
            assessments:
              type: array
              items: { $ref: '#/components/schemas/AssessmentInventory' }
