@nasebanal/cli 0.1.0 → 0.2.0

package/specs/assurance.yaml

@@ -0,0 +1,1730 @@
+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
+  contact:
+    name: NASEBANAL
+    url: https://www.nasebanal.com
+servers:
+  - url: http://localhost:8791
+    description: Local dev (wrangler dev)
+  - url: https://api.assurance.nasebanal.com
+    description: Production
+security:
+  - BearerAuth: []
+tags:
+  - name: Health
+    description: Health check endpoints
+  - name: User
+    description: User profile endpoints
+  - name: Monitors
+    description: "External monitoring: URLs probed on an interval"
+  - name: Reports
+    description: Availability reports built from daily rollups and incidents
+  - name: Projects
+    description: "Test results reported from CI/CD: named projects (typically one per repository), one run per pipeline run, one suite result per job"
+  - name: Contracts
+    description: "Outsourcing contracts: deliverables tied to projects, documents and the SLA clause"
+paths:
+  /api/v1/health:
+    get:
+      tags:
+        - Health
+      operationId: getHealth
+      summary: Health check
+      description: Returns the health status of the API.
+      security: []
+      responses:
+        "200":
+          description: API is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+                  timestamp:
+                    type: string
+                    format: date-time
+  /api/v1/me:
+    get:
+      tags:
+        - User
+      operationId: getCurrentUser
+      summary: Get current user profile
+      description: Returns the authenticated user's profile information from the Account API.
+      responses:
+        "200":
+          description: User profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v1/monitors:
+    get:
+      tags:
+        - Monitors
+      operationId: listMonitors
+      summary: List monitors
+      description: Monitors owned by the caller, newest first, each with its 7-day uptime.
+      responses:
+        "200":
+          description: Monitors
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    required:
+                      - data
+                      - total
+                      - limit
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/MonitorWithUptime"
+                      total:
+                        type: integer
+                      limit:
+                        type: integer
+                        description: Maximum monitors per user
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+    post:
+      tags:
+        - Monitors
+      operationId: createMonitor
+      summary: Create a monitor
+      description: The URL must be a public http(s) host on port 80, 443, 8080 or 8443; private, loopback, link-local and single-label hosts are refused.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MonitorCreate"
+      responses:
+        "201":
+          description: Monitor created
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Monitor"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "409":
+          description: The per-user monitor limit is reached (`LIMIT_REACHED`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+  /api/v1/monitors/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Monitor id
+    get:
+      tags:
+        - Monitors
+      operationId: getMonitor
+      summary: Get a monitor
+      description: One monitor with its settings and latest state.
+      responses:
+        "200":
+          description: Monitor
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Monitor"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+    patch:
+      tags:
+        - Monitors
+      operationId: updateMonitor
+      summary: Update a monitor
+      description: Send only the fields to change. Changing `url` resets the monitor to `pending` and closes any open incident.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MonitorUpdate"
+      responses:
+        "200":
+          description: Updated monitor
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Monitor"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+    delete:
+      tags:
+        - Monitors
+      operationId: deleteMonitor
+      summary: Delete a monitor
+      description: Also deletes its results, daily rollups and incidents.
+      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"
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+  /api/v1/monitors/{id}/check:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Monitor id
+    post:
+      tags:
+        - Monitors
+      operationId: checkMonitor
+      summary: Run a check now
+      description: "Probes the URL immediately and records the outcome. A target that is down still returns 200 with `ok: false` (the check ran). Refused with 429 within 10 seconds of the previous check."
+      responses:
+        "200":
+          description: Check outcome
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    properties:
+                      ok:
+                        type: boolean
+                      status_code:
+                        type: integer
+                        nullable: true
+                      response_ms:
+                        type: integer
+                      error:
+                        $ref: "#/components/schemas/CheckError"
+                      monitor:
+                        $ref: "#/components/schemas/Monitor"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          description: Checked moments ago (`RATE_LIMITED`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+  /api/v1/monitors/{id}/results:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Monitor id
+    get:
+      tags:
+        - Monitors
+      operationId: listMonitorResults
+      summary: List recent check results
+      description: Newest first. Raw results are kept for 7 days; use the report for longer windows.
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 500
+            default: 100
+        - $ref: "#/components/parameters/ActiveOrganization"
+      responses:
+        "200":
+          description: Results
+          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/CheckResult"
+                      total:
+                        type: integer
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/monitors/{id}/report:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Monitor id
+    get:
+      tags:
+        - Reports
+      operationId: getMonitorReport
+      summary: Availability report for one monitor
+      description: "Availability report for one monitor over the last `days` UTC days: uptime, downtime, response times, a daily series and incidents."
+      parameters:
+        - name: days
+          in: query
+          required: false
+          schema:
+            type: integer
+            enum:
+              - 1
+              - 7
+              - 30
+              - 90
+            default: 7
+          description: Report window in UTC days, ending today
+        - $ref: "#/components/parameters/ActiveOrganization"
+      responses:
+        "200":
+          description: Report
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/MonitorReport"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/report:
+    get:
+      tags:
+        - Reports
+      operationId: getReportOverview
+      summary: Availability report across all monitors
+      description: Availability report across all of the caller's monitors over the last `days` UTC days.
+      parameters:
+        - name: days
+          in: query
+          required: false
+          schema:
+            type: integer
+            enum:
+              - 1
+              - 7
+              - 30
+              - 90
+            default: 7
+          description: Report window in UTC days, ending today
+        - $ref: "#/components/parameters/ActiveOrganization"
+      responses:
+        "200":
+          description: Report
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/ReportOverview"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /api/v1/projects:
+    get:
+      tags:
+        - Projects
+      operationId: listProjects
+      summary: List projects
+      description: Projects in the caller's namespace (personal, or the active organization), newest first, each with its latest run and that run's suites.
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+        - name: name
+          in: query
+          required: false
+          description: Return only the project with this name (exact match, ignoring case).
+          schema:
+            type: string
+            maxLength: 100
+      responses:
+        "200":
+          description: Projects
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    required:
+                      - data
+                      - total
+                      - limit
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/ProjectWithLatestRun"
+                      total:
+                        type: integer
+                      limit:
+                        type: integer
+                        description: Maximum projects per namespace
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    post:
+      tags:
+        - Projects
+      operationId: createProject
+      summary: Create a project
+      description: One project tracks one repository's CI/CD quality record. `retention_days` is set from the caller's plan.
+      parameters:
+        - $ref: "#/components/parameters/ActiveOrganization"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectCreate"
+      responses:
+        "201":
+          description: Project created
+          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"
+        "409":
+          description: The per-namespace project limit is reached (`LIMIT_REACHED`), or a project with this name already exists in the namespace (`CONFLICT`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /api/v1/projects/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+    get:
+      tags:
+        - Projects
+      operationId: getProject
+      summary: Get a project
+      description: One project with its settings, including the retention window.
+      responses:
+        "200":
+          description: Project
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Project"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    delete:
+      tags:
+        - Projects
+      operationId: deleteProject
+      summary: Delete a project
+      description: Also deletes its runs and suite results.
+      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/projects/{id}/results:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+    post:
+      tags:
+        - Projects
+      operationId: reportResult
+      summary: Report a test result
+      description: Called once per CI job with the NORMALISED summary of one report (not the raw file). The run is found or created by `run.key`; the suite is upserted by (run, `suite.kind`, `suite.name`), so a retried job replaces its own result and another job of the same pipeline adds a suite to the same run. 201 when the suite is new, 200 when it replaced an earlier report.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ResultReport"
+      responses:
+        "200":
+          description: An earlier report of this suite was replaced
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/ResultAccepted"
+        "201":
+          description: Result stored
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/ResultAccepted"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/projects/{id}/runs:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Project id
+        schema:
+          type: string
+      - $ref: "#/components/parameters/ActiveOrganization"
+    get:
+      tags:
+        - Projects
+      operationId: listRuns
+      summary: List runs
+      description: Newest first, each with its suite results.
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        "200":
+          description: Runs
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    type: object
+                    required:
+                      - data
+                      - limit
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/Run"
+                      limit:
+                        type: integer
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/projects/{id}/runs/{runId}:
+    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
+      - $ref: "#/components/parameters/ActiveOrganization"
+    get:
+      tags:
+        - Projects
+      operationId: getRun
+      summary: Get a run
+      description: One run with all of its suite results.
+      responses:
+        "200":
+          description: Run
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  data:
+                    $ref: "#/components/schemas/Run"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /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. Read-only for now.
+      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"
+  /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"
+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
+        url:
+          type: string
+          format: uri
+          maxLength: 2048
+        method:
+          type: string
+          enum:
+            - GET
+            - HEAD
+          default: GET
+        interval_minutes:
+          type: integer
+          enum:
+            - 5
+            - 10
+            - 15
+            - 30
+            - 60
+          default: 5
+        timeout_ms:
+          type: integer
+          minimum: 1000
+          maximum: 30000
+          default: 10000
+        expected_status:
+          type: integer
+          nullable: true
+          minimum: 100
+          maximum: 599
+          description: Exact status that counts as up; null means any 2xx or 3xx
+        keyword:
+          type: string
+          nullable: true
+          maxLength: 200
+          description: Text the response body must contain (GET only)
+        enabled:
+          type: boolean
+          default: true
+    MonitorCreate:
+      allOf:
+        - $ref: "#/components/schemas/MonitorSettings"
+      required:
+        - name
+        - url
+    MonitorUpdate:
+      allOf:
+        - $ref: "#/components/schemas/MonitorSettings"
+      minProperties: 1
+      description: Any subset of the settings
+    Monitor:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        url:
+          type: string
+        method:
+          type: string
+          enum:
+            - GET
+            - HEAD
+        interval_minutes:
+          type: integer
+        timeout_ms:
+          type: integer
+        expected_status:
+          type: integer
+          nullable: true
+        keyword:
+          type: string
+          nullable: true
+        enabled:
+          type: boolean
+        state:
+          type: string
+          enum:
+            - pending
+            - up
+            - down
+        state_since:
+          type: string
+          format: date-time
+          nullable: true
+        last_checked_at:
+          type: string
+          format: date-time
+          nullable: true
+        last_status_code:
+          type: integer
+          nullable: true
+        last_response_ms:
+          type: integer
+          nullable: true
+        last_error:
+          $ref: "#/components/schemas/CheckError"
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        organization_id:
+          type: integer
+          nullable: true
+          description: Owning organization; null for a personal monitor.
+          example: null
+    MonitorWithUptime:
+      allOf:
+        - $ref: "#/components/schemas/Monitor"
+        - type: object
+          properties:
+            uptime_7d:
+              type: number
+              nullable: true
+              description: Percent, null before the first check
+    CheckResult:
+      type: object
+      properties:
+        id:
+          type: integer
+        monitor_id:
+          type: string
+        checked_at:
+          type: string
+          format: date-time
+        ok:
+          type: boolean
+        status_code:
+          type: integer
+          nullable: true
+        response_ms:
+          type: integer
+        error:
+          $ref: "#/components/schemas/CheckError"
+    Totals:
+      type: object
+      properties:
+        checks:
+          type: integer
+        failures:
+          type: integer
+        uptime_pct:
+          type: number
+          nullable: true
+          description: Percent, two decimals; null when no checks ran
+        avg_response_ms:
+          type: integer
+          nullable: true
+          description: Successful checks only
+        max_response_ms:
+          type: integer
+          nullable: true
+          description: Successful checks only
+    DailyPoint:
+      allOf:
+        - $ref: "#/components/schemas/Totals"
+        - type: object
+          properties:
+            day:
+              type: string
+              format: date
+              description: UTC date
+    Incident:
+      type: object
+      properties:
+        id:
+          type: integer
+        monitor_id:
+          type: string
+        started_at:
+          type: string
+          format: date-time
+        ended_at:
+          type: string
+          format: date-time
+          nullable: true
+        ongoing:
+          type: boolean
+        duration_seconds:
+          type: integer
+          description: Clipped to the report window; open incidents run to now
+        status_code:
+          type: integer
+          nullable: true
+        error:
+          $ref: "#/components/schemas/CheckError"
+    MonitorReport:
+      allOf:
+        - $ref: "#/components/schemas/Totals"
+        - type: object
+          properties:
+            monitor:
+              $ref: "#/components/schemas/Monitor"
+            days:
+              type: integer
+            from:
+              type: string
+              format: date-time
+            to:
+              type: string
+              format: date-time
+            incident_count:
+              type: integer
+            total_downtime_seconds:
+              type: integer
+            incidents:
+              type: array
+              items:
+                $ref: "#/components/schemas/Incident"
+              description: Newest first, at most 100
+            daily:
+              type: array
+              items:
+                $ref: "#/components/schemas/DailyPoint"
+              description: One entry per UTC day of the window, empty days included
+    ReportOverview:
+      allOf:
+        - $ref: "#/components/schemas/Totals"
+        - type: object
+          properties:
+            days:
+              type: integer
+            from:
+              type: string
+              format: date-time
+            to:
+              type: string
+              format: date-time
+            incident_count:
+              type: integer
+            total_downtime_seconds:
+              type: integer
+            incidents:
+              type: array
+              items:
+                $ref: "#/components/schemas/Incident"
+              description: Newest first, at most 100
+            daily:
+              type: array
+              items:
+                $ref: "#/components/schemas/DailyPoint"
+              description: One entry per UTC day of the window, empty days included
+            monitor_count:
+              type: integer
+            down_now:
+              type: integer
+            monitors:
+              type: array
+              items:
+                allOf:
+                  - $ref: "#/components/schemas/Totals"
+                  - type: object
+                    properties:
+                      monitor:
+                        $ref: "#/components/schemas/Monitor"
+                      incident_count:
+                        type: integer
+                      total_downtime_seconds:
+                        type: integer
+    ProjectCreate:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          maxLength: 100
+          description: Unique within the namespace, ignoring case. The CLI finds or creates a project by this name.
+        repo:
+          type: string
+          nullable: true
+          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
+    Project:
+      type: object
+      required:
+        - id
+        - name
+        - retention_days
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+        organization_id:
+          type: integer
+          nullable: true
+          description: Owning organization; null = personal
+        name:
+          type: string
+        repo:
+          type: string
+          nullable: true
+        retention_days:
+          type: integer
+          description: Runs older than this are deleted daily. Follows the reporter's plan, refreshed on every report.
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    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
+    Suite:
+      type: object
+      required:
+        - id
+        - kind
+        - tool
+        - name
+        - status
+      properties:
+        id:
+          type: string
+        kind:
+          type: string
+          enum:
+            - unit
+            - e2e
+            - load
+            - contract
+            - security
+        tool:
+          type: string
+          enum:
+            - vitest
+            - pytest
+            - playwright
+            - specmatic
+            - zap
+            - locust
+          example: vitest
+        name:
+          type: string
+          description: Tells apart several suites of one kind in a run; empty when single
+        status:
+          type: string
+          enum:
+            - passed
+            - failed
+        tests:
+          $ref: "#/components/schemas/SuiteTests"
+        duration_ms:
+          type: integer
+          minimum: 0
+          nullable: true
+        coverage:
+          type: object
+          properties:
+            lines_pct:
+              type: number
+              nullable: true
+            branches_pct:
+              type: number
+              nullable: true
+        metrics:
+          type: object
+          nullable: true
+          additionalProperties:
+            type: number
+          description: Kind-specific numbers
+        failures:
+          type: array
+          nullable: true
+          items:
+            $ref: "#/components/schemas/SuiteFailure"
+        updated_at:
+          type: string
+          format: date-time
+    Run:
+      type: object
+      required:
+        - id
+        - key
+        - status
+        - suites
+        - created_at
+      properties:
+        id:
+          type: string
+        key:
+          type: string
+          description: The caller's identity for the pipeline run
+        commit_sha:
+          type: string
+          nullable: true
+        branch:
+          type: string
+          nullable: true
+        ci_url:
+          type: string
+          nullable: true
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        status:
+          type: string
+          enum:
+            - passed
+            - failed
+            - empty
+          description: failed if any suite failed; passed if there is at least one suite and none failed
+        suites:
+          type: array
+          items:
+            $ref: "#/components/schemas/Suite"
+    ResultReport:
+      type: object
+      required:
+        - run
+        - suite
+      properties:
+        run:
+          type: object
+          required:
+            - key
+          properties:
+            key:
+              type: string
+              maxLength: 128
+              description: Stable per pipeline run, e.g. the CI run id plus attempt. Every job of one run must send the same key.
+              example: 12345678-1
+            commit_sha:
+              type: string
+              maxLength: 64
+            branch:
+              type: string
+              maxLength: 255
+            ci_url:
+              type: string
+              maxLength: 2048
+              description: http(s) URL of the CI run
+            started_at:
+              type: string
+              format: date-time
+        suite:
+          type: object
+          required:
+            - kind
+            - tool
+            - status
+          properties:
+            kind:
+              type: string
+              enum:
+                - unit
+                - e2e
+                - load
+                - contract
+                - security
+            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."
+              example: playwright
+            name:
+              type: string
+              maxLength: 100
+            status:
+              type: string
+              enum:
+                - passed
+                - failed
+              description: Decided by the reporter, which alone knows the tool's pass/fail semantics
+            tests:
+              type: object
+              properties:
+                total:
+                  type: integer
+                  minimum: 0
+                passed:
+                  type: integer
+                  minimum: 0
+                failed:
+                  type: integer
+                  minimum: 0
+                skipped:
+                  type: integer
+                  minimum: 0
+              description: passed + failed + skipped must not exceed total
+            duration_ms:
+              type: integer
+              minimum: 0
+            coverage:
+              type: object
+              properties:
+                lines_pct:
+                  type: number
+                  minimum: 0
+                  maximum: 100
+                branches_pct:
+                  type: number
+                  minimum: 0
+                  maximum: 100
+            metrics:
+              type: object
+              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."
+              example:
+                p95_ms: 240
+                rps: 120.5
+            failures:
+              type: array
+              maxItems: 20
+              items:
+                $ref: "#/components/schemas/SuiteFailure"
+              description: The first failures only
+    ResultAccepted:
+      type: object
+      required:
+        - run_id
+        - suite_id
+        - replaced
+      properties:
+        run_id:
+          type: string
+        suite_id:
+          type: string
+        replaced:
+          type: boolean
+    ContractCreditTier:
+      type: object
+      required:
+        - below_pct
+        - credit_pct
+      properties:
+        below_pct:
+          type: number
+          description: Below this uptime percentage the credit applies
+        credit_pct:
+          type: number
+          description: Share of the monthly fee credited back
+    ContractSla:
+      type: object
+      required:
+        - uptime_target_pct
+        - monthly_fee
+        - credit_tiers
+      properties:
+        uptime_target_pct:
+          type: number
+        monthly_fee:
+          type: integer
+        credit_tiers:
+          type: array
+          items:
+            $ref: "#/components/schemas/ContractCreditTier"
+    ContractDeliverable:
+      type: object
+      required:
+        - id
+        - name
+        - project_id
+        - version
+        - due
+        - amount
+        - paid
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        project_id:
+          type: string
+          nullable: true
+          description: The project this deliverable is a version of; null once that project is deleted
+        version:
+          type: string
+          nullable: true
+          description: The delivered version, if it has been delivered
+        due:
+          type: string
+          format: date
+        amount:
+          type: integer
+          description: Released on acceptance
+        paid:
+          type: boolean
+    ContractDocument:
+      type: object
+      required:
+        - name
+        - kind
+        - date
+      properties:
+        name:
+          type: string
+        kind:
+          type: string
+          enum:
+            - contract
+            - spec
+            - sla
+            - acceptance
+        date:
+          type: string
+          format: date
+    Contract:
+      type: object
+      required:
+        - id
+        - title
+        - kind
+        - status
+        - orderer
+        - vendor
+        - start
+        - end
+        - amount
+        - oas_url
+        - sla_project_id
+        - sla
+        - related
+        - deliverables
+        - documents
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+          description: Bilingual, "ja / en"
+        kind:
+          type: string
+          enum:
+            - development
+            - maintenance
+        status:
+          type: string
+          enum:
+            - draft
+            - active
+            - completed
+        orderer:
+          type: string
+        vendor:
+          type: string
+        start:
+          type: string
+          format: date
+        end:
+          type: string
+          format: date
+        amount:
+          type: integer
+        oas_url:
+          type: string
+          format: uri
+          nullable: true
+          description: The OpenAPI document this contract refers to, as a plain URL
+        sla_project_id:
+          type: string
+          nullable: true
+          description: "Operations contracts: the project whose uptime the SLA clause covers"
+        sla:
+          allOf:
+            - $ref: "#/components/schemas/ContractSla"
+          nullable: true
+        related:
+          type: object
+          nullable: true
+          description: "How this contract relates to another one: it follows a development contract, or is a change order on top of a running one"
+          properties:
+            id:
+              type: string
+            relation:
+              type: string
+              enum:
+                - follows
+                - change_order
+        deliverables:
+          type: array
+          items:
+            $ref: "#/components/schemas/ContractDeliverable"
+        documents:
+          type: array
+          items:
+            $ref: "#/components/schemas/ContractDocument"
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+  responses:
+    Unauthorized:
+      description: Authentication required or invalid token
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          example:
+            error:
+              code: AUTH_ERROR
+              message: No authentication token provided
+    ValidationError:
+      description: The request body or a query parameter is invalid
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          example:
+            success: false
+            error:
+              code: VALIDATION_ERROR
+              message: url must point to a public host
+    NotFound:
+      description: No such monitor, or it belongs to someone else
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+          example:
+            success: false
+            error:
+              code: NOT_FOUND
+              message: Monitor not found
+    Forbidden:
+      description: The caller does not belong to the active organization (`FORBIDDEN`)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
+  parameters:
+    ActiveOrganization:
+      name: X-Active-Organization-Id
+      in: header
+      required: false
+      schema:
+        type: string
+        example: "7"
+      description: "Namespace the request acts in: an organization id, or `personal` (also the default when absent or malformed). Inside an organization every member shares the same monitors, reports and output settings. An organization the caller does not belong to is refused with 403 `FORBIDDEN`."