grotti/docs/internal/openapi.yaml

openapi: 3.0.3
info:
  title: Grotti API
  version: "1"
  description: |
    JSON unter /api/v1. Auth: Session-Cookie oder Bearer grt_….
    Mutierende Session-Calls brauchen Header X-CSRF-Token.
    Siehe docs/internal/API.md.
servers:
  - url: /api/v1
paths:
  /version:
    get:
      summary: Server-Info
      security: []
      responses:
        "200":
          description: name, version, api, features
  /auth/login:
    post:
      summary: Session-Login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username: { type: string }
                password: { type: string }
      responses:
        "200":
          description: user + csrf
  /auth/token:
    post:
      summary: Passwort → API-Token (App)
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username: { type: string }
                password: { type: string }
                device_name: { type: string }
                role: { type: string, enum: [operator, admin] }
      responses:
        "201":
          description: token (einmalig) + user
  /drucker:
    get:
      summary: Druckerliste
      parameters:
        - name: live
          in: query
          schema: { type: integer, enum: [0, 1] }
      responses:
        "200":
          description: Array Drucker
  /drucker/{host}/{action}:
    post:
      summary: Pause / Fortsetzen / Abbrechen
      parameters:
        - name: host
          in: path
          required: true
          schema: { type: string }
        - name: action
          in: path
          required: true
          schema:
            type: string
            enum: [pause, fortsetzen, abbrechen, resume, cancel]
      responses:
        "200":
          description: OK
  /dateien:
    get:
      summary: Bibliothek
      parameters:
        - { name: family, in: query, schema: { type: string } }
        - { name: material, in: query, schema: { type: string } }
        - { name: project_id, in: query, schema: { type: integer } }
        - { name: host, in: query, schema: { type: string } }
        - { name: q, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer } }
        - { name: offset, in: query, schema: { type: integer } }
      responses:
        "200":
          description: Array Dateien; Header X-Total-Count
          headers:
            X-Total-Count:
              schema: { type: integer }
  /senden:
    post:
      summary: Druck starten oder einreihen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [file_id, confirm]
              properties:
                file_id: { type: integer }
                hosts: { type: array, items: { type: string } }
                confirm: { type: boolean }
                when_free: { type: boolean }
                ace_maps: { type: object }
                bed_leveling: { type: boolean }
      responses:
        "202":
          description: jobs
  /druck-queue:
    get:
      summary: Warteschlange
      parameters:
        - { name: host, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer } }
        - { name: offset, in: query, schema: { type: integer } }
      responses:
        "200":
          description: Array; X-Total-Count
    post:
      summary: Einreihen
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [file_id, confirm]
      responses:
        "200":
          description: Queue-Eintrag
  /projekte/{id}/einreihen:
    post:
      summary: Projektdateien einreihen
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [confirm]
              properties:
                confirm: { type: boolean }
                file_ids: { type: array, items: { type: integer } }
                menge: { type: integer }
      responses:
        "201":
          description: jobs
  /stream:
    get:
      summary: SSE Live-Events
      responses:
        "200":
          description: text/event-stream (drucker, queue, senden, ereignis, ping)
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: grt_
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
security:
  - bearerAuth: []
  - cookieAuth: []