openapi.yaml

openapi: 3.1.0
info:
  title: Obiente Support Intake API
  version: 1.0.0
  description: Product-neutral private support intake. All successful report submissions require explicit user confirmation in the calling client.
  license:
    name: GNU Affero General Public License v3.0
    identifier: AGPL-3.0-only
servers:
  - url: https://support.obiente.org
security: []
paths:
  /api/v1/products:
    get:
      summary: List supported Obiente products
      operationId: listProducts
      responses:
        "200":
          description: Registered products and their diagnostic constraints.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductResponse"
  /api/v1/reports:
    post:
      summary: Submit a private support report
      operationId: createReport
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [metadata]
              properties:
                metadata:
                  $ref: "#/components/schemas/ReportMetadata"
                diagnostics:
                  type: string
                  format: binary
                  maxLength: 4194304
      responses:
        "201":
          description: Private report receipt.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Receipt"
        "400": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "410": { $ref: "#/components/responses/Problem" }
  /api/v1/receipts:
    get:
      summary: Reconcile an uncertain report submission
      operationId: reconcileReceipt
      description: Reconcile an ambiguous submission outcome without creating another report.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Existing private report receipt.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Receipt"
        "404": { $ref: "#/components/responses/Problem" }
        "410": { $ref: "#/components/responses/Problem" }
    delete:
      summary: Cancel a private report submission
      operationId: cancelReportSubmission
      description: Atomically prevent a pending submission from creating a report and delete any report already created with the same idempotency key.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "204":
          description: The submission is terminally cancelled and no private report remains available.
        "400": { $ref: "#/components/responses/Problem" }
  /api/v1/reports/{capability}:
    parameters:
      - name: capability
        in: path
        required: true
        schema: { type: string, minLength: 43, maxLength: 43 }
    get:
      summary: Read a private report status through its capability
      operationId: getPrivateReportStatus
      responses:
        "200":
          description: Private report state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrivateStatus"
        "404": { $ref: "#/components/responses/Problem" }
    delete:
      summary: Delete a private report through its capability
      operationId: deletePrivateReport
      responses:
        "200":
          description: The private report was revoked and its diagnostic object removed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrivateStatus"
        "404": { $ref: "#/components/responses/Problem" }
  /api/v1/reports/{capability}/messages:
    post:
      summary: Reply to a private support conversation
      operationId: createPrivateReportMessage
      parameters:
        - name: capability
          in: path
          required: true
          schema: { type: string, minLength: 43, maxLength: 43 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MessageInput" }
      responses:
        "201":
          description: Message added to the private report.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PrivateStatus" }
        "400": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
  /api/v1/admin/login:
    post:
      summary: Sign in a support maintainer
      operationId: adminLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username: { type: string }
                password: { type: string, format: password }
      responses:
        "200":
          description: Authenticated maintainer session. The server also sets an HTTP-only session cookie.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdminSession" }
        "401": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
  /api/v1/admin/session:
    get:
      summary: Refresh the current maintainer session
      operationId: refreshAdminSession
      security: [{ AdminSessionCookie: [] }]
      responses:
        "200":
          description: Current session with a freshly rotated CSRF token.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdminSession" }
        "401": { $ref: "#/components/responses/Problem" }
  /api/v1/admin/logout:
    post:
      summary: Sign out the current maintainer
      operationId: adminLogout
      security: [{ AdminSessionCookie: [] }]
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      responses:
        "204": { description: Session revoked. }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
  /api/v1/admin/reports:
    get:
      summary: List private reports for moderation
      operationId: listAdminReports
      security: [{ AdminSessionCookie: [] }]
      parameters:
        - name: status
          in: query
          schema: { $ref: "#/components/schemas/ReportStatus" }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
        - name: offset
          in: query
          schema: { type: integer, minimum: 0, default: 0 }
      responses:
        "200":
          description: Private moderation queue.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdminReportResponse" }
        "401": { $ref: "#/components/responses/Problem" }
  /api/v1/admin/reports/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      summary: Read one private report for moderation
      operationId: getAdminReport
      security: [{ AdminSessionCookie: [] }]
      responses:
        "200":
          description: Decrypted private report for maintainer review.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdminReportDetail" }
        "401": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
    patch:
      summary: Change a private report status
      operationId: updateAdminReportStatus
      security: [{ AdminSessionCookie: [] }]
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { $ref: "#/components/schemas/ReportStatus" }
      responses:
        "200":
          description: Updated private report.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdminReportDetail" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
  /api/v1/admin/reports/{id}/diagnostics:
    get:
      summary: Download one private diagnostic archive
      operationId: downloadAdminDiagnostics
      security: [{ AdminSessionCookie: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Decrypted diagnostic ZIP for an explicit maintainer download.
          content:
            application/zip:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503":
          description: The report exists but its private diagnostic archive is unavailable.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Problem" }
              example:
                contractVersion: 1
                code: diagnostics_unavailable
                message: The report is available, but its diagnostic archive is unavailable.
  /api/v1/admin/reports/{id}/messages:
    post:
      summary: Ask a reporter for more information
      operationId: createAdminReportMessage
      security: [{ AdminSessionCookie: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/CSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MessageInput" }
      responses:
        "201":
          description: Encrypted maintainer message added and report marked as needing information.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdminReportDetail" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
components:
  securitySchemes:
    AdminSessionCookie:
      type: apiKey
      in: cookie
      name: obiente_admin_session
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: { type: string, pattern: "^[A-Za-z0-9_-]{32,128}$" }
    CSRFToken:
      name: X-CSRF-Token
      in: header
      required: true
      schema: { type: string, minLength: 43, maxLength: 43 }
  responses:
    Problem:
      description: A bounded, user-safe error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    ProductResponse:
      type: object
      required: [contractVersion, products]
      properties:
        contractVersion: { const: 1 }
        products:
          type: array
          items: { $ref: "#/components/schemas/Product" }
    Product:
      type: object
      required: [id, name, description, diagnosticContentTypes, diagnosticEntries, diagnosticMaxBytes, diagnosticMaxExpandedBytes, retentionDays]
      properties:
        id: { type: string }
        name: { type: string }
        description: { type: string }
        repository: { type: string }
        diagnosticContentTypes: { type: array, items: { type: string } }
        diagnosticEntries: { type: array, items: { type: string } }
        diagnosticMaxBytes: { type: integer, minimum: 0 }
        diagnosticMaxExpandedBytes: { type: integer, minimum: 0 }
        retentionDays: { type: integer, minimum: 1 }
    ReportMetadata:
      type: object
      required: [contractVersion, productId, requestType, title, description, source, release, privacyAccepted]
      properties:
        contractVersion: { const: 1 }
        productId: { type: string }
        requestType: { enum: [bug, feature, support] }
        title: { type: string, minLength: 4, maxLength: 160 }
        description: { type: string, minLength: 10, maxLength: 8000 }
        contact: { type: string, maxLength: 320 }
        source: { enum: [web, app] }
        privacyAccepted: { const: true }
        release:
          type: object
          required: [version, platform]
          properties:
            version: { type: string, maxLength: 80 }
            channel: { type: string, maxLength: 40 }
            platform: { type: string, maxLength: 60 }
            osVersion: { type: string, maxLength: 120 }
            architecture: { type: string, maxLength: 40 }
    Receipt:
      type: object
      required: [contractVersion, supportCode, status, statusUrl, deletionUrl, createdAt, retentionUntil]
      properties:
        contractVersion: { const: 1 }
        supportCode: { type: string }
        status: { type: string }
        statusUrl: { type: string, format: uri }
        deletionUrl: { type: string, format: uri }
        createdAt: { type: string, format: date-time }
        retentionUntil: { type: string, format: date-time }
    PrivateStatus:
      type: object
      required: [contractVersion, supportCode, productId, requestType, status, createdAt, updatedAt, retentionUntil, messages]
      properties:
        contractVersion: { const: 1 }
        supportCode: { type: string }
        productId: { type: string }
        requestType: { type: string }
        status: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        retentionUntil: { type: string, format: date-time }
        messages:
          type: array
          items: { $ref: "#/components/schemas/SupportMessage" }
    MessageInput:
      type: object
      required: [body]
      properties:
        body: { type: string, minLength: 1, maxLength: 8192 }
    SupportMessage:
      type: object
      required: [id, author, body, createdAt]
      properties:
        id: { type: string, format: uuid }
        author: { enum: [maintainer, reporter] }
        body: { type: string }
        createdAt: { type: string, format: date-time }
    ReportStatus:
      type: string
      enum: [new, needs_information, accepted, duplicate, resolved, rejected]
    AdminSession:
      type: object
      required: [contractVersion, username, csrfToken, expiresAt]
      properties:
        contractVersion: { const: 1 }
        username: { type: string }
        csrfToken: { type: string, minLength: 43, maxLength: 43 }
        expiresAt: { type: string, format: date-time }
    AdminReportSummary:
      type: object
      required: [id, supportCode, productId, requestType, status, source, title, hasDiagnostics, createdAt, updatedAt, retentionUntil]
      properties:
        id: { type: string, format: uuid }
        supportCode: { type: string }
        productId: { type: string }
        requestType: { enum: [bug, feature, support] }
        status: { $ref: "#/components/schemas/ReportStatus" }
        source: { enum: [web, app] }
        title: { type: string }
        hasDiagnostics: { type: boolean, description: Whether a diagnostic archive was attached to the report. }
        diagnosticsState:
          type: string
          enum: [none, available, unavailable, unknown]
          description: Current private object storage availability; unknown means the storage check failed.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        retentionUntil: { type: string, format: date-time }
    AdminReportDetail:
      allOf:
        - $ref: "#/components/schemas/AdminReportSummary"
        - type: object
          required: [description, release, messages]
          properties:
            description: { type: string }
            contact: { type: string }
            release:
              type: object
              required: [version, platform]
              properties:
                version: { type: string }
                channel: { type: string }
                platform: { type: string }
                osVersion: { type: string }
                architecture: { type: string }
            messages:
              type: array
              items: { $ref: "#/components/schemas/SupportMessage" }
    AdminReportResponse:
      type: object
      required: [contractVersion, reports, total, limit, offset]
      properties:
        contractVersion: { const: 1 }
        reports:
          type: array
          items: { $ref: "#/components/schemas/AdminReportSummary" }
        total: { type: integer, minimum: 0 }
        limit: { type: integer, minimum: 1 }
        offset: { type: integer, minimum: 0 }
    Problem:
      type: object
      required: [contractVersion, code, message]
      properties:
        contractVersion: { const: 1 }
        code: { type: string }
        message: { type: string }