@nasebanal/cli 0.6.0 → 0.8.0

package/specs/assurance.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: NASEBANAL - Assurance API
   description: "Backend of NASEBANAL Assurance (quality assurance for APIs and web apps, under NASEBANAL Evolution). Authenticates users via Auth0 JWT and Personal Access Tokens (PAT) and integrates with the Account API. External monitoring: register URLs to be probed on an interval, then read availability reports. Test results: report the normalised result of each CI/CD job into a named project (typically one per repository), then read its runs and suites. Every response is wrapped as `{ success, data }` (or `{ success: false, error }`)."
-  version: 1.0.0
+  version: 1.8.0
   contact:
     name: NASEBANAL
     url: https://www.nasebanal.com
@@ -42,13 +42,33 @@ paths:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
-                  status:
-                    type: string
-                    example: ok
-                  timestamp:
-                    type: string
-                    format: date-time
+                  success:
+                    type: boolean
+                    enum:
+                      - true
+                  data:
+                    type: object
+                    required:
+                      - status
+                      - timestamp
+                    properties:
+                      status:
+                        type: string
+                        example: ok
+                      timestamp:
+                        type: string
+                        format: date-time
+              examples:
+                valid:
+                  value:
+                    success: true
+                    data:
+                      status: ok
+                      timestamp: 2026-05-14T12:00:00Z
   /api/v1/me:
     get:
       tags:
@@ -598,6 +618,48 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+    patch:
+      tags:
+        - Projects
+      operationId: updateProject
+      summary: Update a project
+      description: Rename a project and/or change its repository or description. Send only the fields to change; an empty `repo` clears it. `retention_days` follows the plan and is not editable.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectUpdate"
+      responses:
+        "200":
+          description: Project
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Project"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: A project with this name already exists in the namespace (`CONFLICT`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
     delete:
       tags:
         - Projects
@@ -691,6 +753,8 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+        "422":
+          $ref: "#/components/responses/ApiVersionRequired"
   /api/v1/projects/{id}/runs:
     parameters:
       - name: id
@@ -792,18 +856,36 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
-  /api/v1/contracts:
+  /api/v1/projects/{id}/runs/{runId}/suites/{suiteId}/cases:
     parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - name: runId
+        in: path
+        required: true
+        description: Run id
+        schema:
+          type: string
+      - name: suiteId
+        in: path
+        required: true
+        description: Suite id
+        schema:
+          type: string
       - $ref: "#/components/parameters/ActiveOrganization"
     get:
       tags:
-        - Contracts
-      operationId: listContracts
-      summary: List contracts
-      description: The outsourcing contracts of the active namespace, each with its deliverables, documents and SLA clause. Read-only for now.
+        - Projects
+      operationId: getSuiteCases
+      summary: Get the test cases of a suite
+      description: The per-test cases the reporter sent with the suite result (name, outcome, duration, failure message). 404 when the suite has none.
       responses:
         "200":
-          description: Contracts
+          description: Cases
           content:
             application/json:
               schema:
@@ -816,36 +898,119 @@ paths:
                     type: boolean
                     example: true
                   data:
-                    type: object
-                    properties:
-                      data:
-                        type: array
-                        items:
-                          $ref: "#/components/schemas/Contract"
-                      total:
-                        type: integer
+                    $ref: "#/components/schemas/SuiteCases"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
-  /api/v1/contracts/{id}:
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/projects/{id}/runs/{runId}/suites/{suiteId}/attachment:
     parameters:
       - name: id
         in: path
         required: true
-        description: Contract id
+        description: Project id
+        schema:
+          type: string
+      - name: runId
+        in: path
+        required: true
+        description: Run id
+        schema:
+          type: string
+      - name: suiteId
+        in: path
+        required: true
+        description: Suite id
         schema:
           type: string
       - $ref: "#/components/parameters/ActiveOrganization"
+    put:
+      tags:
+        - Projects
+      operationId: putSuiteAttachment
+      summary: Attach the original report to a result
+      description: "Keeps the tool's own report (a file, or a folder as a zip) with the result: the body is the file as it is, `name` is the file name it is downloaded under. One per result; sending again replaces it (so does reporting the result again). Refused with 403 `ATTACHMENTS_DISABLED` until the project turns `attachments_enabled` on. Up to 20 MiB each and 200 MiB per project. The server only stores it: it is not opened, unzipped or shown."
+      parameters:
+        - name: name
+          in: query
+          required: false
+          description: The file name to download it as (letters, digits, `.`, `_`, `-` and spaces; anything else becomes `_`). Default `report.zip`.
+          schema:
+            type: string
+            maxLength: 100
+      requestBody:
+        required: true
+        description: The report file, or a zip of the report folder
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+          application/zip:
+            schema:
+              type: string
+              format: binary
+      responses:
+        "201":
+          description: Stored
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/AttachmentStored"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: The project already holds 200 MiB of attached reports
+        "413":
+          description: Larger than 20 MiB
+        "503":
+          description: Report storage is not configured
     get:
       tags:
-        - Contracts
-      operationId: getContract
-      summary: Get a contract
-      description: One contract. A contract outside the active namespace is reported as not found.
+        - Projects
+      operationId: getSuiteAttachment
+      summary: Download the original report of a result
+      description: "The bytes that were attached, always as a download (`Content-Disposition: attachment`, `application/octet-stream`, `nosniff`). 404 when nothing is attached."
       responses:
         "200":
-          description: Contract
+          description: The attached report
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    delete:
+      tags:
+        - Projects
+      operationId: deleteSuiteAttachment
+      summary: Remove the attached report of a result
+      description: Drops the attached report; the result stays. 404 when nothing is attached.
+      responses:
+        "200":
+          description: Removed
           content:
             application/json:
               schema:
@@ -858,99 +1023,890 @@ paths:
                     type: boolean
                     example: true
                   data:
-                    $ref: "#/components/schemas/Contract"
+                    type: object
+                    properties:
+                      suite_id:
+                        type: string
+                      deleted:
+                        type: boolean
+                        example: true
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
-components:
-  securitySchemes:
-    BearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT or PAT
-      description: Use either an Auth0 JWT token or a Personal Access Token (PAT) starting with `nbpat_`.
-  schemas:
-    User:
-      type: object
-      properties:
-        id:
-          type: integer
-        auth0_sub:
-          type: string
-        email:
-          type: string
-          format: email
-        name:
-          type: string
-        language:
-          type: string
-          enum:
-            - ja
-            - en
-        plan:
-          type: string
-          enum:
-            - free
-            - pro
-            - family
-            - enterprise
-        subscription_status:
-          type: string
-          enum:
-            - active
-            - canceled
-            - past_due
-            - trialing
-          nullable: true
-        subscription_expires_at:
-          type: string
-          format: date-time
-          nullable: true
-    UserResponse:
-      type: object
-      properties:
-        data:
-          $ref: "#/components/schemas/User"
-    Error:
-      type: object
-      properties:
-        error:
-          type: object
-          properties:
-            code:
-              type: string
-            message:
-              type: string
-    CheckError:
-      type: string
-      nullable: true
-      enum:
-        - timeout
-        - connection_failed
-        - unexpected_status
-        - keyword_not_found
-        - null
-      description: Why a check failed; null when it passed
-    MonitorSettings:
-      type: object
-      properties:
-        name:
+  /api/v1/projects/{id}/runs/{runId}/suites/{suiteId}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
           type: string
-          maxLength: 100
-        url:
+      - name: runId
+        in: path
+        required: true
+        description: Run id
+        schema:
           type: string
-          format: uri
-          maxLength: 2048
-        method:
+      - name: suiteId
+        in: path
+        required: true
+        description: Suite id
+        schema:
           type: string
-          enum:
-            - GET
-            - HEAD
-          default: GET
-        interval_minutes:
+      - $ref: "#/components/parameters/ActiveOrganization"
+    patch:
+      tags:
+        - Projects
+      operationId: updateSuite
+      summary: Correct a stored test result
+      description: "Edit what a person may correct by hand: the outcome, the counts, the duration, the coverage, the name, the API version and the run's branch / commit / CI link. Kind and tool identify the result and cannot change; the name and the API version can, as long as the run does not already have a result with the same kind, name and version; metrics, failures and cases come from the report itself. A key that is present replaces the value (`null` clears it); an absent key is left alone. Answers the whole run."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SuiteUpdate"
+      responses:
+        "200":
+          description: The run, with its suites
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Run"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: Changing the name or the API version would give the result the same kind, name and version as another result of the run (`CONFLICT`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "422":
+          $ref: "#/components/responses/ApiVersionRequired"
+    delete:
+      tags:
+        - Projects
+      operationId: deleteSuite
+      summary: Delete a stored test result
+      description: Deletes one suite result and its stored cases. A run left with no suite is deleted too (`run_deleted`).
+      responses:
+        "200":
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                      deleted:
+                        type: boolean
+                      run_deleted:
+                        type: boolean
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/projects/{id}/quality:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+    get:
+      tags:
+        - Projects
+      operationId: getProjectQuality
+      summary: Get a project's quality summary
+      description: "The quality summary of one of your projects, computed now, whether or not it is public: one verdict per perspective (unit, E2E, contract, security, performance, availability) and the numbers behind them. There is no weighted total. This is what the report page shows its owner."
+      responses:
+        "200":
+          description: Quality summary
+          headers:
+            Access-Control-Allow-Origin:
+              schema:
+                type: string
+              description: "*"
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/QualityView"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/public/projects/{publicId}/summary:
+    parameters:
+      - name: publicId
+        in: path
+        required: true
+        description: The public token of a project (the `public_id` it got when its owner made it public)
+        schema:
+          type: string
+    get:
+      tags:
+        - Projects
+      operationId: getPublicQualitySummary
+      summary: Public quality summary
+      description: "The quality summary of a project whose report is PUBLIC (`report_access: public`), readable without authentication (Kong Dev Portal and other pages build their own display from it). Aggregate verdicts and numbers only: never a test name, a failure message or a commit. Any other project and a token nobody has both answer 404, so a private project cannot be told from no project. Cached for 5 minutes."
+      security: []
+      responses:
+        "200":
+          description: Quality summary
+          headers:
+            Access-Control-Allow-Origin:
+              schema:
+                type: string
+              description: "*"
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/QualityView"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/shared/projects/{publicId}/summary:
+    parameters:
+      - name: publicId
+        in: path
+        required: true
+        description: The public token of a project (public_id)
+        schema:
+          type: string
+    get:
+      tags:
+        - Projects
+      operationId: getSharedQualitySummary
+      summary: Report summary for a signed-in visitor
+      description: "The quality summary for a visitor who is SIGNED IN: any NASEBANAL account with the link may read it when the report is `login` or `public`. `hidden` and an unknown token answer 404 whoever asks (the report page uses this after a login; without credentials it is a 401)."
+      responses:
+        "200":
+          description: Quality summary
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/QualityView"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/public/projects/{publicId}/badge:
+    parameters:
+      - name: publicId
+        in: path
+        required: true
+        description: The public token of a project (the `public_id` it got when its owner made it public)
+        schema:
+          type: string
+    get:
+      tags:
+        - Projects
+      operationId: getPublicQualityBadge
+      summary: Public quality badge (shields.io endpoint JSON)
+      description: "The JSON a shields.io endpoint badge reads (`https://img.shields.io/endpoint?url=...`), for READMEs on GitHub and GitLab. The message is how many perspectives pass out of all of them (`5/6`); the colour is red when one fails, green when all pass, yellow when some are not measured yet, light grey when nothing is. 404 when the badge is not public (`public_badge`) or the token is unknown (the two are not told apart): through shields.io that shows shields.io's own error badge, so use the SVG endpoint where nothing at all should show. `?label=` sets the left text (30 characters at most)."
+      security: []
+      parameters:
+        - name: label
+          in: query
+          required: false
+          schema:
+            type: string
+            maxLength: 30
+            example: Target API
+      responses:
+        "200":
+          description: shields.io endpoint badge
+          headers:
+            Access-Control-Allow-Origin:
+              schema:
+                type: string
+              description: "*"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ShieldsBadge"
+  /api/v1/public/projects/{publicId}/badge.svg:
+    parameters:
+      - name: publicId
+        in: path
+        required: true
+        description: The public token of a project (the `public_id` it got when its owner made it public)
+        schema:
+          type: string
+    get:
+      tags:
+        - Projects
+      operationId: getPublicQualityBadgeSvg
+      summary: Public quality badge (SVG)
+      description: The badge itself, in shields.io flat style, to use as an image in a README, a page or Kong Dev Portal without going through shields.io. Same content and colours as the JSON badge. When the badge is not public (or the token is unknown) it answers 200 with an empty image of zero size, so a README shows no badge and no broken-image icon.
+      security: []
+      parameters:
+        - name: label
+          in: query
+          required: false
+          schema:
+            type: string
+            maxLength: 30
+      responses:
+        "200":
+          description: SVG image
+          headers:
+            Access-Control-Allow-Origin:
+              schema:
+                type: string
+              description: "*"
+          content:
+            image/svg+xml:
+              schema:
+                type: string
+  /api/v1/projects/{id}/components:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+    get:
+      tags:
+        - Projects
+      operationId: listComponents
+      summary: List components
+      description: "The components of a project: what its results are reported under (the front end, the back end, a service of a monorepo), each with the number of results it holds. A component exists before it has a result."
+      responses:
+        "200":
+          description: Components
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Component"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    post:
+      tags:
+        - Projects
+      operationId: createComponent
+      summary: Add a component
+      description: Registers a component of a project ahead of its first result. Reporting a result under a new name creates the component by itself, so this is only needed to prepare one. The name is unique in the project (case-insensitive).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ComponentWrite"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Component"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: A component with this name already exists in the project (`CONFLICT`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/v1/projects/{id}/components/{componentId}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+      - name: componentId
+        in: path
+        required: true
+        description: Component id
+        schema:
+          type: string
+    patch:
+      tags:
+        - Projects
+      operationId: updateComponent
+      summary: Rename a component
+      description: Renames a component; its results follow, since they refer to it by id. A name another component of the project already has is refused (409).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ComponentWrite"
+      responses:
+        "200":
+          description: Component
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Component"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: Another component of the project already has this name (`CONFLICT`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    delete:
+      tags:
+        - Projects
+      operationId: deleteComponent
+      summary: Delete a component
+      description: "Removes the component from every result it belongs to. A result that belongs to no other component is **deleted** (with its stored cases) and so is a run left empty; a result that also belongs to other components stays. Refused (409, nothing deleted) when taking the component off would make a result identical to another one of the same run, kind and version. This cannot be undone; ask the person first. Monitors tied to the component are never deleted: they stay, no longer tied to it."
+      responses:
+        "200":
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                      deleted:
+                        type: boolean
+                      results_deleted:
+                        type: integer
+                      results_detached:
+                        type: integer
+                        description: Results that also belong to other components, which stay (only this component is taken off them)
+                      monitors_detached:
+                        type: integer
+                        description: Monitors that were tied to it. They stay, untied.
+                      runs_deleted:
+                        type: integer
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: Taking the component off a result would make it identical to another result of the run (`CONFLICT`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/v1/projects/{id}/components/{componentId}/merge:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - name: componentId
+        in: path
+        required: true
+        description: Id of the component that is merged away
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+    post:
+      tags:
+        - Projects
+      operationId: mergeComponent
+      summary: Merge a component into another
+      description: Replaces the component by another one of the same project in every result it belongs to, then deletes it. Refused (409, nothing moved) when a result would then be identical to another one of the same run, kind and version. This cannot be undone; ask the person first. Monitors tied to the component are tied to the other one instead.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ComponentMerge"
+      responses:
+        "200":
+          description: Merged
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        description: The receiving component
+                      merged_id:
+                        type: string
+                        description: The component that was merged away and deleted
+                      results_moved:
+                        type: integer
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: A result would become identical to another one of the same run, kind and API version (`CONFLICT`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/v1/contracts:
+    parameters:
+      - $ref: "#/components/parameters/ActiveOrganization"
+    get:
+      tags:
+        - Contracts
+      operationId: listContracts
+      summary: List contracts
+      description: The outsourcing contracts of the active namespace, each with its deliverables, documents and SLA clause.
+      responses:
+        "200":
+          description: Contracts
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Contract"
+                      total:
+                        type: integer
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    post:
+      tags:
+        - Contracts
+      operationId: createContract
+      summary: Create a contract
+      description: Create a contract with its deliverables, documents and optional SLA clause in the active namespace. Projects and the related contract must belong to the same namespace.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ContractInput"
+      responses:
+        "201":
+          description: Contract created
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Contract"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: The per-namespace contract limit is reached (`LIMIT_REACHED`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/v1/contracts/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Contract id
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+    get:
+      tags:
+        - Contracts
+      operationId: getContract
+      summary: Get a contract
+      description: One contract. A contract outside the active namespace is reported as not found.
+      responses:
+        "200":
+          description: Contract
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Contract"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    put:
+      tags:
+        - Contracts
+      operationId: updateContract
+      summary: Replace a contract
+      description: Replaces the whole contract, deliverables and documents included (the body is the full document, not a patch). A deliverable keeps its id, and so its record, only when its `id` from an earlier read is sent back; any other id is ignored and a new one issued.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ContractInput"
+      responses:
+        "200":
+          description: Contract
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Contract"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    delete:
+      tags:
+        - Contracts
+      operationId: deleteContract
+      summary: Delete a contract
+      description: Also deletes its deliverables and documents. Contracts that pointed at it keep existing, unlinked.
+      responses:
+        "200":
+          description: Deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                      deleted:
+                        type: boolean
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/public/projects/{publicId}/report:
+    parameters:
+      - name: publicId
+        in: path
+        required: true
+        schema:
+          type: string
+        description: The public token of a project (public_id)
+    get:
+      tags:
+        - Projects
+      operationId: getPublicQualityReport
+      summary: Dashboard report of a public project
+      description: "The dashboard data of a project whose report is PUBLIC (`report_access: public`), readable without authentication: the same runs and monitoring the owner's Charts screen draws, with everything that identifies something removed (no commit, branch, CI URL, test name, failure text or monitored URL). Any other project and an unknown token answer 404. Cached for 10 minutes."
+      responses:
+        "200":
+          description: Dashboard report
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/QualityReport"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/shared/projects/{publicId}/report:
+    parameters:
+      - name: publicId
+        in: path
+        required: true
+        schema:
+          type: string
+        description: The public token of a project (public_id)
+    get:
+      tags:
+        - Projects
+      operationId: getSharedQualityReport
+      summary: Dashboard report for a signed-in visitor
+      description: The same dashboard data for a SIGNED-IN visitor when `report_access` is `login` or `public`. `hidden` and an unknown token answer 404; without credentials it is a 401.
+      responses:
+        "200":
+          description: Dashboard report
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/QualityReport"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT or PAT
+      description: Use either an Auth0 JWT token or a Personal Access Token (PAT) starting with `nbpat_`.
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+        auth0_sub:
+          type: string
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        language:
+          type: string
+          enum:
+            - ja
+            - en
+        plan:
+          type: string
+          enum:
+            - free
+            - pro
+            - family
+            - enterprise
+        subscription_status:
+          type: string
+          enum:
+            - active
+            - canceled
+            - past_due
+            - trialing
+          nullable: true
+        subscription_expires_at:
+          type: string
+          format: date-time
+          nullable: true
+    UserResponse:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/User"
+    Error:
+      type: object
+      properties:
+        error:
+          type: object
+          properties:
+            code:
+              type: string
+            message:
+              type: string
+    CheckError:
+      type: string
+      nullable: true
+      enum:
+        - timeout
+        - connection_failed
+        - unexpected_status
+        - keyword_not_found
+        - null
+      description: Why a check failed; null when it passed
+    MonitorSettings:
+      type: object
+      properties:
+        name:
+          type: string
+          maxLength: 100
+          description: Optional. Left out, the name is the host and path of the URL (`api.example.com/health`), and it then follows the URL when that changes.
+        url:
+          type: string
+          format: uri
+          maxLength: 2048
+        method:
+          type: string
+          enum:
+            - GET
+            - HEAD
+          default: GET
+        interval_minutes:
           type: integer
           enum:
             - 5
@@ -978,11 +1934,32 @@ components:
         enabled:
           type: boolean
           default: true
+        project_id:
+          type: string
+          nullable: true
+          description: Project this monitor belongs to; its uptime then counts toward that project's quality gates. null = not assigned.
+        api_version:
+          type: string
+          nullable: true
+          maxLength: 32
+          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
+          description: API version this monitor checks (e.g. `v1`, `v2`), when the project serves several versions from one repository. null = not tied to a version (it counts for every version).
+        description:
+          type: string
+          nullable: true
+          maxLength: 500
+          description: "Free text about the monitor: what it watches, why it exists. Up to 500 characters; an empty string clears it."
+        components:
+          type: array
+          maxItems: 20
+          description: "Names of the components of the project this monitor is about (the front end, the back end, a gateway in front of both). New names are created in the project. Needs `project_id`. Send `[]` for none: the monitor is then about the whole project and counts in every component's view. Changing `project_id` without sending this drops the old project's components. Up to 20."
+          items:
+            type: string
+            maxLength: 100
     MonitorCreate:
       allOf:
         - $ref: "#/components/schemas/MonitorSettings"
       required:
-        - name
         - url
     MonitorUpdate:
       allOf:
@@ -1048,6 +2025,24 @@ components:
           nullable: true
           description: Owning organization; null for a personal monitor.
           example: null
+        project_id:
+          type: string
+          nullable: true
+          description: Project this monitor belongs to; its uptime then counts toward that project's quality gates. null = not assigned.
+        api_version:
+          type: string
+          nullable: true
+          maxLength: 32
+          description: API version this monitor checks (e.g. `v1`, `v2`), when the project serves several versions from one repository. null = not tied to a version (it counts for every version).
+        description:
+          type: string
+          nullable: true
+          description: Free text; null = none.
+        components:
+          type: array
+          description: The components this monitor is tied to; empty = about the whole project, so it counts in every component's view.
+          items:
+            $ref: "#/components/schemas/ComponentRef"
     MonitorWithUptime:
       allOf:
         - $ref: "#/components/schemas/Monitor"
@@ -1216,6 +2211,77 @@ components:
           maxLength: 200
           description: "Where the code lives, as `owner/name` (or `group/subgroup/project`, optionally prefixed by a host). Informational: several projects may share one repository, and it may be omitted."
           example: nasebanal/nb-target-api
+        description:
+          type: string
+          nullable: true
+          maxLength: 500
+          description: A short free-text summary of what the project is. Informational; may be omitted.
+        spec_id:
+          type: string
+          nullable: true
+          maxLength: 64
+          description: "The API this project assesses: the id of a spec in the API catalog (nb-specs-api). Stored as an id only; whether it exists is not checked. Optional."
+        spec_environment:
+          type: string
+          nullable: true
+          maxLength: 40
+          description: Which environment of that API the project covers (production, staging, development, or any label), up to 40 characters. Needs spec_id. Optional.
+    ProjectUpdate:
+      type: object
+      minProperties: 1
+      properties:
+        name:
+          type: string
+          maxLength: 100
+          description: Unique within the namespace, ignoring case.
+        repo:
+          type: string
+          nullable: true
+          maxLength: 200
+          description: "`owner/name` (or `group/subgroup/project`). An empty string clears it."
+          example: nasebanal/nb-target-api
+        description:
+          type: string
+          nullable: true
+          maxLength: 500
+          description: Free-text summary. An empty string clears it.
+        spec_id:
+          type: string
+          nullable: true
+          maxLength: 64
+          description: The API this project assesses (a spec id of the API catalog). An empty string or null clears it, and spec_environment with it.
+        spec_environment:
+          type: string
+          nullable: true
+          maxLength: 40
+          description: The environment of that API the project covers, up to 40 characters. Needs spec_id. An empty string or null clears it.
+        public_badge:
+          type: boolean
+          description: true makes the badge readable without authentication (issues the public token the first time); false makes the badge show nothing at all. The token is kept, and this does not change report_access.
+        attachments_enabled:
+          type: boolean
+          description: true lets reports be attached to this project's results (`PUT .../attachment`); false (the default) refuses them with 403 `ATTACHMENTS_DISABLED`. Off by default because a report can hold secrets and every member of the project's namespace can download it. Turning it off stops new attachments; what is already stored stays until it is removed.
+        api_version_required_kinds:
+          type: array
+          items:
+            type: string
+            enum:
+              - unit
+              - e2e
+              - load
+              - contract
+              - security
+          description: "The kinds of result (`unit`, `e2e`, `load`, `contract`, `security`) that must carry an `api_version`. A result of such a kind without one is refused with 422 `API_VERSION_REQUIRED`, and so is an edit that clears its version. Use it for a project whose versions are kept apart (a branch each, or /v1 and /v2 side by side), where a forgotten label would put one version's result in every version's view. An empty list (the default) requires none. It governs only what arrives or is edited from now on: stored results are untouched."
+        report_access:
+          type: string
+          enum:
+            - hidden
+            - login
+            - public
+          description: hidden, login or public (see the Project schema). Setting it away from hidden issues the public token the first time. Does not change public_badge.
+        rotate_public_id:
+          type: boolean
+          description: "true replaces the public token: every old link stops working."
     Project:
       type: object
       required:
@@ -1236,6 +2302,48 @@ components:
         repo:
           type: string
           nullable: true
+        description:
+          type: string
+          nullable: true
+          description: Free-text summary a person wrote; null = none
+        spec_id:
+          type: string
+          nullable: true
+          maxLength: 64
+          description: "The API this project assesses: the id of a spec in the API catalog (nb-specs-api), kept as an id only (whether it exists is not checked). null = none. Clearing it clears spec_environment too."
+        spec_environment:
+          type: string
+          nullable: true
+          maxLength: 40
+          description: Which environment of that API the project covers (production, staging, development, or any label), up to 40 characters. Needs spec_id. null = not said.
+        public_badge:
+          type: boolean
+          description: true = the badge ("5/6" and a colour) is readable without authentication by public_id; false = it shows nothing at all. Independent of report_access.
+        attachments_enabled:
+          type: boolean
+          description: Whether reports may be attached to this project's results. false until someone who can edit the project turns it on.
+        api_version_required_kinds:
+          type: array
+          items:
+            type: string
+            enum:
+              - unit
+              - e2e
+              - load
+              - contract
+              - security
+          description: The kinds of result that must carry an `api_version` (see the update schema). [] = none.
+        report_access:
+          type: string
+          enum:
+            - hidden
+            - login
+            - public
+          description: "Who may read the quality report (the summary, the report page and its embed): hidden = nobody (404 whoever asks), login = anyone signed in to NASEBANAL who has the link, public = anyone with the link, no login. Independent of public_badge."
+        public_id:
+          type: string
+          nullable: true
+          description: The unguessable token of the public URLs; issued when the project is first made public and kept when it is turned off. null = never made public.
         retention_days:
           type: integer
           description: Runs older than this are deleted daily. Follows the reporter's plan, refreshed on every report.
@@ -1244,47 +2352,344 @@ components:
           format: date-time
         updated_at:
           type: string
-          format: date-time
-    ProjectWithLatestRun:
-      allOf:
-        - $ref: "#/components/schemas/Project"
-        - type: object
+          format: date-time
+    QualityGate:
+      type: object
+      required:
+        - id
+        - state
+        - facts
+      properties:
+        id:
+          type: string
+          enum:
+            - unit
+            - e2e
+            - contract
+            - security
+            - performance
+            - availability
+        state:
+          type: string
+          enum:
+            - pass
+            - fail
+            - unmeasured
+          description: "`unmeasured` = nothing was reported for this perspective yet"
+        facts:
+          type: object
+          additionalProperties:
+            type: number
+          description: The aggregate numbers behind the verdict (passed / total tests, coverage_pct, p95_ms, error_rate_pct, high_risk / medium / low findings, uptime_pct). Only what applies to the perspective.
+    QualityView:
+      type: object
+      required:
+        - name
+        - gates
+        - measured
+        - total
+        - failing
+        - computed_at
+      properties:
+        name:
+          type: string
+        environment:
+          type: string
+          nullable: true
+          description: The environment of an API the project covers (production, staging, ...); null = not said
+        gates:
+          type: array
+          items:
+            $ref: "#/components/schemas/QualityGate"
+        measured:
+          type: integer
+          description: How many perspectives have a verdict
+        total:
+          type: integer
+          description: How many perspectives exist (six)
+        failing:
+          type: integer
+          description: How many of the measured perspectives fail
+        computed_at:
+          type: string
+          format: date-time
+    ShieldsBadge:
+      type: object
+      description: The JSON a shields.io endpoint badge reads (https://shields.io/badges/endpoint-badge)
+      required:
+        - schemaVersion
+        - label
+        - message
+        - color
+      properties:
+        schemaVersion:
+          type: integer
+          enum:
+            - 1
+        label:
+          type: string
+        message:
+          type: string
+          example: 5/6
+        color:
+          type: string
+          enum:
+            - brightgreen
+            - yellow
+            - red
+            - lightgrey
+        cacheSeconds:
+          type: integer
+          example: 300
+    ProjectWithLatestRun:
+      allOf:
+        - $ref: "#/components/schemas/Project"
+        - type: object
+          properties:
+            latest_run:
+              allOf:
+                - $ref: "#/components/schemas/Run"
+              nullable: true
+    SuiteTests:
+      type: object
+      properties:
+        total:
+          type: integer
+          minimum: 0
+          nullable: true
+        passed:
+          type: integer
+          minimum: 0
+          nullable: true
+        failed:
+          type: integer
+          minimum: 0
+          nullable: true
+        skipped:
+          type: integer
+          minimum: 0
+          nullable: true
+    SuiteFailure:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          maxLength: 300
+        message:
+          type: string
+          nullable: true
+          maxLength: 500
+    SuiteCase:
+      type: object
+      required:
+        - name
+        - status
+      properties:
+        name:
+          type: string
+          maxLength: 300
+        status:
+          type: string
+          enum:
+            - passed
+            - failed
+            - skipped
+        duration_ms:
+          type: integer
+          minimum: 0
+          nullable: true
+        message:
+          type: string
+          nullable: true
+          maxLength: 2000
+          description: Failure or error message, truncated by the reporter
+    ComponentMerge:
+      type: object
+      required:
+        - into
+      properties:
+        into:
+          type: string
+          description: Id of the component that receives the results. It must belong to the same project and differ from the one in the path.
+    ComponentWrite:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: The component's name, such as `web`, `api` or `backend-provider`. Unique in the project (case-insensitive).
+    ComponentRef:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+    Component:
+      type: object
+      required:
+        - id
+        - name
+        - results_count
+        - exclusive_results_count
+        - monitors_count
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+          description: The component's name, such as `web`, `api` or `backend-provider`. Unique in the project (case-insensitive).
+        results_count:
+          type: integer
+          minimum: 0
+          description: Number of results that belong to this component (a result of several components counts for each).
+        exclusive_results_count:
+          type: integer
+          minimum: 0
+          description: "How many of those belong to no other component: the ones deleted along with it."
+        monitors_count:
+          type: integer
+          minimum: 0
+          description: How many monitors are tied to this component (they stay when it is deleted, just no longer tied).
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    SuiteUpdate:
+      type: object
+      description: Fields of a stored suite result that may be corrected. At least one is required.
+      properties:
+        name:
+          type: string
+          maxLength: 100
+          description: Move the result to this one component (created when new); shorthand for a `components` of one. An empty string means `default`.
+        components:
+          type: array
+          maxItems: 20
+          description: Replace the components the result belongs to (created when new; an empty list means `default`). A result of the run that already has the same kind, set of components and version makes it a conflict (409).
+          items:
+            type: string
+            maxLength: 100
+        description:
+          type: string
+          nullable: true
+          maxLength: 500
+          description: Free text about the result (up to 500 characters). `null` or an empty string clears it.
+        label:
+          type: string
+          nullable: true
+          maxLength: 100
+          description: Correct the label (see `Suite.label`). `null` or an empty string clears it. Refused (409) when the run already has a result with the same kind, components, API version and label.
+        api_version:
+          type: string
+          nullable: true
+          maxLength: 32
+          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
+          description: Correct the API version of this result. `null` clears it (the result then applies to every version).
+        status:
+          type: string
+          enum:
+            - passed
+            - failed
+        tests:
+          type: object
+          description: Merged with the stored counts; passed + failed + skipped must not exceed total. `null` clears all four.
+          nullable: true
           properties:
-            latest_run:
-              allOf:
-                - $ref: "#/components/schemas/Run"
+            total:
+              type: integer
+              minimum: 0
               nullable: true
-    SuiteTests:
-      type: object
-      properties:
-        total:
-          type: integer
-          minimum: 0
-          nullable: true
-        passed:
-          type: integer
-          minimum: 0
-          nullable: true
-        failed:
+            passed:
+              type: integer
+              minimum: 0
+              nullable: true
+            failed:
+              type: integer
+              minimum: 0
+              nullable: true
+            skipped:
+              type: integer
+              minimum: 0
+              nullable: true
+        duration_ms:
           type: integer
           minimum: 0
           nullable: true
-        skipped:
-          type: integer
-          minimum: 0
+        coverage:
+          type: object
           nullable: true
-    SuiteFailure:
+          properties:
+            lines_pct:
+              type: number
+              minimum: 0
+              maximum: 100
+              nullable: true
+            branches_pct:
+              type: number
+              minimum: 0
+              maximum: 100
+              nullable: true
+        run:
+          type: object
+          description: Run-level fields, shared by every suite of the run
+          properties:
+            commit_sha:
+              type: string
+              maxLength: 64
+              nullable: true
+            branch:
+              type: string
+              maxLength: 255
+              nullable: true
+            ci_url:
+              type: string
+              maxLength: 2048
+              nullable: true
+              description: http(s) URL of the CI run
+            provider:
+              type: string
+              nullable: true
+              maxLength: 20
+              description: The CI provider the run came from (`github` or `gitlab`; `other` for anything else), when the sender knew it. With the project's repository and the commit it lets a page link to a file in the repository.
+    AttachmentStored:
       type: object
+      description: What was stored for the result.
       required:
+        - suite_id
         - name
+        - size_bytes
       properties:
+        suite_id:
+          type: string
         name:
           type: string
-          maxLength: 300
-        message:
+          description: The file name it is downloaded under.
+        size_bytes:
+          type: integer
+          description: Its size in bytes.
+    SuiteCases:
+      type: object
+      required:
+        - suite_id
+        - cases
+      properties:
+        suite_id:
           type: string
-          nullable: true
-          maxLength: 500
+        cases:
+          type: array
+          items:
+            $ref: "#/components/schemas/SuiteCase"
     Suite:
       type: object
       required:
@@ -1306,17 +2711,36 @@ components:
             - security
         tool:
           type: string
-          enum:
-            - vitest
-            - pytest
-            - playwright
-            - specmatic
-            - zap
-            - locust
+          description: "The producing tool, as a label (lower-case letters, digits, `.`, `_`, `-`; up to 50), for example vitest, pytest, playwright, specmatic, zap, locust, trivy, k6. It is not a closed list: what a result means is carried by `kind` and by the normalised `metrics`, so a tool can be swapped for another that reports the same things. Converting a tool's own report into that shape is the sender's job (the nb CLI, a script). Matching is case-insensitive."
           example: vitest
+        tool_version:
+          type: string
+          nullable: true
+          maxLength: 50
+          description: "The version of the tool that produced the report (e.g. `9.1.0`), when the sender knew it. Informational: it is not part of the result's identity, and a report sent again replaces it."
+        report_path:
+          type: string
+          nullable: true
+          maxLength: 512
+          description: "Where the report file is in the repository, relative to the repository root (for example `reports/junit.xml`), when the report is committed there. Only set it for a file that is in the commit: with the run's `commit_sha` and `provider` it becomes a link to the file. Informational; a report sent again replaces it."
+        attachment:
+          type: object
+          nullable: true
+          description: The original report kept with the result (download it from `.../attachment`); null when none was attached.
+          properties:
+            name:
+              type: string
+            size_bytes:
+              type: integer
         name:
           type: string
-          description: Tells apart several suites of one kind in a run; empty when single
+          description: "A label for display: the names of the result's components, joined with `, `."
+        components:
+          type: array
+          minItems: 1
+          description: The components the result belongs to (at least one). A result may be about several, such as an end-to-end test of the front end and the back end together.
+          items:
+            $ref: "#/components/schemas/ComponentRef"
         status:
           type: string
           enum:
@@ -1348,9 +2772,27 @@ components:
           nullable: true
           items:
             $ref: "#/components/schemas/SuiteFailure"
+        description:
+          type: string
+          nullable: true
+          description: Free text; null = none.
+        label:
+          type: string
+          nullable: true
+          maxLength: 100
+          description: "A name that tells apart results of one run, kind, components and API version, such as two scans of one tool (`baseline`, `full-scan`). null = none. It is part of the result's identity: the same combination with the same label replaces it."
+        cases_count:
+          type: integer
+          minimum: 0
+          nullable: true
+          description: Number of per-test cases stored for this suite (read them with `getSuiteCases`); null when the reporter sent none
         updated_at:
           type: string
           format: date-time
+        api_version:
+          type: string
+          nullable: true
+          description: API version this result is for (e.g. `v1`, `v2`). null or absent = it applies to every version (unit tests usually do). Within one run a suite is identified by `kind`, `name` and `api_version`, so the results for v1 and v2 of the same kind and name sit side by side (one with no version is a third, shared one); reporting the same combination again replaces it.
     Run:
       type: object
       required:
@@ -1374,6 +2816,11 @@ components:
         ci_url:
           type: string
           nullable: true
+        provider:
+          type: string
+          nullable: true
+          maxLength: 20
+          description: The CI provider the run came from (`github` or `gitlab`; `other` for anything else), when the sender knew it. With the project's repository and the commit it lets a page link to a file in the repository.
         started_at:
           type: string
           format: date-time
@@ -1418,6 +2865,13 @@ components:
               type: string
               maxLength: 2048
               description: http(s) URL of the CI run
+            provider:
+              type: string
+              enum:
+                - github
+                - gitlab
+                - other
+              description: The CI provider the run came from (`github` or `gitlab`; `other` for anything else), when the sender knew it. With the project's repository and the commit it lets a page link to a file in the repository.
             started_at:
               type: string
               format: date-time
@@ -1439,18 +2893,42 @@ components:
             tool:
               type: string
               maxLength: 50
-              enum:
-                - vitest
-                - pytest
-                - playwright
-                - specmatic
-                - zap
-                - locust
-              description: "The producing tool. Supported per kind: unit = vitest | pytest, e2e = playwright, contract = specmatic, security = zap, load = locust. Any other tool, or a tool paired with the wrong kind, is rejected with 400. Matching is case-insensitive."
+              pattern: ^[a-z0-9][a-z0-9._-]{0,49}$
+              description: "The producing tool, as a label (lower-case letters, digits, `.`, `_`, `-`; up to 50), for example vitest, pytest, playwright, specmatic, zap, locust, trivy, k6. It is not a closed list: what a result means is carried by `kind` and by the normalised `metrics`, so a tool can be swapped for another that reports the same things. Converting a tool's own report into that shape is the sender's job (the nb CLI, a script). Matching is case-insensitive."
               example: playwright
+            api_version:
+              type: string
+              nullable: true
+              maxLength: 32
+              pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
+              description: API version this result is for (e.g. `v1`, `v2`). null or absent = it applies to every version (unit tests usually do). Within one run a suite is identified by `kind`, `name` and `api_version`, so the results for v1 and v2 of the same kind and name sit side by side (one with no version is a third, shared one); reporting the same combination again replaces it.
             name:
               type: string
               maxLength: 100
+              description: One component this result is for. Shorthand for a `components` of one; if both are sent, the result belongs to all of them. Omit both for the component `default`.
+            components:
+              type: array
+              maxItems: 20
+              description: "The components this result is for: the front end, the back end, a service. Each is created in the project when new. Up to 20. Omitted or empty (with no `name`) means `default`. A suite in a run is identified by `kind`, the set of components, `api_version` and `label`; reporting the same combination again replaces it."
+              items:
+                type: string
+                maxLength: 100
+            description:
+              type: string
+              maxLength: 500
+              description: "Free text about the result: what it covers, why it is as it is. Up to 500 characters. Reporting the same result again without one keeps the earlier text; with one replaces it."
+            label:
+              type: string
+              maxLength: 100
+              description: A name that tells apart results that are otherwise the same (same kind, components and API version), such as two scans of one tool (`baseline`, `full-scan`). Optional; up to 100 characters. Reporting the same combination with the same label again replaces the result.
+            tool_version:
+              type: string
+              maxLength: 50
+              description: "The version of the tool that produced the report (e.g. `9.1.0`). Optional; up to 50 characters. Informational: it is not part of the result's identity."
+            report_path:
+              type: string
+              maxLength: 512
+              description: "The report file's path in the repository, relative to its root (for example `reports/junit.xml`). Optional; up to 512 characters; no `..` segments. Send it only when the file is committed at the run's `commit_sha`. Informational: it is not part of the result's identity."
             status:
               type: string
               enum:
@@ -1492,7 +2970,7 @@ components:
               maxProperties: 20
               additionalProperties:
                 type: number
-              description: "snake_case keys, finite numbers. Conventional keys: load -> p95_ms, rps, error_rate_pct; security -> critical, high, medium, low, info; contract -> coverage_pct."
+              description: "snake_case keys, finite numbers. The conventional keys are what the dashboard reads, whatever the tool: load -> p95_ms, rps, error_rate_pct; security -> critical, high, medium, low, info (findings by severity, so a scanner maps its own levels onto these); contract -> coverage_pct (share of the spec's operations exercised). Counts and coverage of unit and e2e suites travel in `tests` and `coverage`, not here."
               example:
                 p95_ms: 240
                 rps: 120.5
@@ -1502,6 +2980,12 @@ components:
               items:
                 $ref: "#/components/schemas/SuiteFailure"
               description: The first failures only
+            cases:
+              type: array
+              maxItems: 5000
+              items:
+                $ref: "#/components/schemas/SuiteCase"
+              description: Every test case of a JUnit-based report (vitest, pytest, playwright, specmatic). Kept in object storage and read back with `getSuiteCases`; D1 keeps only the summary. Omit for locust and zap. A retried job replaces the earlier list.
     ResultAccepted:
       type: object
       required:
@@ -1592,6 +3076,119 @@ components:
         date:
           type: string
           format: date
+    ContractDeliverableInput:
+      type: object
+      required:
+        - name
+        - due
+        - amount
+      properties:
+        id:
+          type: string
+          description: Send back an existing id to keep that deliverable; omitted or unknown ids get a new one
+        name:
+          type: string
+          maxLength: 120
+        project_id:
+          type: string
+          nullable: true
+        version:
+          type: string
+          nullable: true
+          maxLength: 32
+          pattern: ^[A-Za-z0-9._-]+$
+        due:
+          type: string
+          format: date
+        amount:
+          type: integer
+          minimum: 0
+          maximum: 1000000000
+        paid:
+          type: boolean
+          default: false
+    ContractInput:
+      type: object
+      required:
+        - title
+        - kind
+        - status
+        - orderer
+        - vendor
+        - start
+        - end
+        - amount
+      properties:
+        title:
+          type: string
+          maxLength: 160
+          description: Bilingual, "ja / en"
+        kind:
+          type: string
+          enum:
+            - development
+            - maintenance
+        status:
+          type: string
+          enum:
+            - draft
+            - active
+            - completed
+        orderer:
+          type: string
+          maxLength: 100
+        vendor:
+          type: string
+          maxLength: 100
+        start:
+          type: string
+          format: date
+        end:
+          type: string
+          format: date
+          description: ">= start"
+        amount:
+          type: integer
+          minimum: 0
+          maximum: 100000000000
+        oas_url:
+          type: string
+          format: uri
+          nullable: true
+          description: http(s) URL of the OpenAPI document
+        sla_project_id:
+          type: string
+          nullable: true
+        sla:
+          allOf:
+            - $ref: "#/components/schemas/ContractSla"
+          nullable: true
+          description: Operations contracts only. Omit or null for none.
+        related:
+          type: object
+          nullable: true
+          description: Link to another contract of the same namespace
+          required:
+            - id
+            - relation
+          properties:
+            id:
+              type: string
+            relation:
+              type: string
+              enum:
+                - follows
+                - change_order
+        deliverables:
+          type: array
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/ContractDeliverableInput"
+        documents:
+          type: array
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/ContractDocument"
     Contract:
       type: object
       required:
@@ -1680,6 +3277,54 @@ components:
         updated_at:
           type: string
           format: date-time
+    QualityReport:
+      type: object
+      description: "The dashboard data of a public report: the project's name, environment, component names and recent runs (verdicts, counts, coverage, metrics only), and its monitors' uptime and daily states (named Monitor 1, 2, ...)."
+      required:
+        - project
+        - monitoring
+        - built_at
+      properties:
+        project:
+          type: object
+          required:
+            - name
+            - environment
+            - components
+            - runs
+          properties:
+            name:
+              type: string
+            environment:
+              type: string
+              nullable: true
+            components:
+              type: array
+              items:
+                type: object
+                properties:
+                  name:
+                    type: string
+            runs:
+              type: array
+              items:
+                $ref: "#/components/schemas/Run"
+        monitoring:
+          type: object
+          required:
+            - monitors
+            - uptime_30d
+          properties:
+            monitors:
+              type: array
+              items:
+                type: object
+            uptime_30d:
+              type: number
+              nullable: true
+        built_at:
+          type: string
+          format: date-time
   responses:
     Unauthorized:
       description: Authentication required or invalid token
@@ -1713,6 +3358,17 @@ components:
             error:
               code: NOT_FOUND
               message: Monitor not found
+    ApiVersionRequired:
+      description: The project requires an `api_version` for this kind of result (`API_VERSION_REQUIRED`)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          example:
+            success: false
+            error:
+              code: API_VERSION_REQUIRED
+              message: "This project requires an API version for contract results: send api_version (nb: --api-version, or NB_API_VERSION)"
     Forbidden:
       description: The caller does not belong to the active organization (`FORBIDDEN`)
       content: