openapi: 3.1.0
info:
  title: Cubicle API
  version: 1.0.0
  description: |
    REST-API fuer kuratierte deutsche Rechts-Quellen.

    **Inhalt**: 116.000+ Dokumente — Gesetze (BGB, StGB, AO, etc.), Urteile (BGH, BAG, BFH, BVerfG, OLG),
    BMF-Schreiben, Tarifvertraege. Taeglich aktualisiert.

    **DSGVO**: Server in Deutschland, AVV verfuegbar, BaFin-konform.

    **Authentifizierung**: Bearer-Token, Format `cub_<prefix>_<secret>`.

    **Rate-Limits**:
      - Standard: 10.000 Queries / Monat (99 EUR / Monat)
      - Enterprise (höhere Quotas, SLA): individuelles Angebot — enterprise@cubicle.legal
  contact:
    name: Cubicle Support
    email: support@cubicle.legal
    url: https://cubicle.legal/api
  license:
    name: Cubicle API Terms
    url: https://cubicle.legal/api/terms

servers:
  - url: https://api.cubicle.legal/v1/knowledge
    description: Production

security:
  - bearerAuth: []

paths:
  /branches:
    get:
      summary: Liste verfuegbarer Branchen
      description: |
        Gibt alle Branchen zurueck, in denen Inhalte indiziert sind, inkl. Anzahl indizierter Dokumente.
      operationId: listBranches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  branches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Branch'
              example:
                branches:
                  - slug: kanzlei
                    name: Kanzlei / Rechtsanwalt
                    description: Rechtsanwaelte, Notare und Kanzleien
                    doc_count: 93770
                  - slug: steuerberater
                    name: Steuerberater
                    description: Steuerberater, Wirtschaftspruefer
                    doc_count: 14418
        '401':
          $ref: '#/components/responses/Unauthorized'

  /search:
    post:
      summary: RAG-Suche in Branchen-Wissen
      description: |
        Volltext- und semantische Suche ueber alle Quellen einer Branche.
        Liefert relevanteste Treffer mit Snippet, Quelle, Score.
      operationId: searchKnowledge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example:
              query: Schonfristzahlung Mietrecht Kuendigung
              branch: kanzlei
              topK: 5
              filters:
                type: [law, decision]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /usage:
    get:
      summary: Verbrauchszahlen + Plan-Info
      description: |
        Aktuelle Monats-Verbrauchszahlen + Plan-Details fuer den authentifizierten Client.
      operationId: getUsage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cub_PREFIX_SECRET
      description: |
        API-Key im Header senden:
        ```
        Authorization: Bearer cub_AbCdEfGh_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
        ```

  schemas:
    Branch:
      type: object
      properties:
        slug:
          type: string
          description: Branch-Identifier
          example: kanzlei
        name:
          type: string
          description: Lesbarer Branchen-Name
          example: Kanzlei / Rechtsanwalt
        description:
          type: string
        doc_count:
          type: integer
          description: Anzahl indizierter Dokumente
          example: 93770

    SearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 2
          maxLength: 2000
          description: Suchbegriff in natuerlicher Sprache oder Paragraphen-Referenz
          example: "§ 535 BGB Mietverhaeltnis"
        branch:
          type: string
          enum: [kanzlei, steuerberater, wirtschaftspruefer, hotel, agentur]
          default: kanzlei
        topK:
          type: integer
          minimum: 1
          maximum: 50
          default: 5
        filters:
          type: object
          properties:
            type:
              type: array
              items:
                type: string
                enum: [law, decision, article, bmf]

    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        query_id:
          type: string
          format: uuid
        usage:
          type: object
          properties:
            month_queries:
              type: integer
            tier_limit:
              type: integer
            remaining:
              type: integer

    SearchResult:
      type: object
      properties:
        type:
          type: string
          enum: [law, decision, article, bmf, unknown]
        label:
          type: string
          example: "§ 535 Abs. 1 BGB"
        snippet:
          type: string
          maxLength: 600
        source:
          type: string
        sections:
          type: array
          items:
            type: string
        aktenzeichen:
          type: string
          nullable: true
        court:
          type: string
          nullable: true
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
          example: 0.67

    UsageResponse:
      type: object
      properties:
        client:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            plan:
              type: string
              enum: [standard, enterprise]
            plan_price_eur:
              type: number
        current_month:
          type: string
          pattern: '^\d{4}-\d{2}$'
        search:
          type: object
          properties:
            queries_used:
              type: integer
            tier_limit:
              type: integer
            remaining:
              type: integer
            reset_date:
              type: string
              format: date
        upgrade_url:
          type: string
          format: uri

    Error:
      type: object
      properties:
        error:
          type: string

  responses:
    Unauthorized:
      description: Fehlender oder ungueltiger API-Key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid API key
    BadRequest:
      description: Validierungs-Fehler
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Monatslimit erreicht
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Monthly limit of 1000 reached. Upgrade plan or wait until 2026-06-01."
