openapi: 3.1.0
info:
  title: Cairnquire Foundation API
  version: 0.1.0
servers:
  - url: http://localhost:8080
paths:
  /health:
    get:
      summary: Health check
      operationId: getHealth
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  database:
                    type: string
                  contentStore:
                    type: string
  /api/uploads:
    post:
      summary: Upload a single file
      description: Markdown, plain-text, and HTML files become rendered documents. Other supported file types remain attachments.
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                folder:
                  type: string
                  description: Optional relative destination folder for readable documents.
                duplicateAction:
                  type: string
                  enum: [overwrite, rename, reuse]
                  description: Explicit resolution after a 409 duplicate response. Use rename to keep both readable documents, overwrite to replace a readable document, or reuse to return an existing upload URL.
      responses:
        "200":
          description: Existing upload URL reused
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResponse"
        "201":
          description: File stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResponse"
        "409":
          description: A readable document name or attachment hash already exists. Ask the user how to continue and retry with duplicateAction.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadConflict"
  /attachments/{hash}:
    get:
      summary: Download an attachment by content hash
      operationId: getAttachment
      parameters:
        - in: path
          name: hash
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Attachment content
components:
  schemas:
    UploadResponse:
      type: object
      required: [hash, contentType, kind, url, attachmentUrl]
      properties:
        hash:
          type: string
        contentType:
          type: string
        kind:
          type: string
          enum: [document, attachment]
        url:
          type: string
          description: Canonical rendered-document or attachment URL.
        attachmentUrl:
          type: string
          deprecated: true
          description: Compatibility alias for url.
    UploadConflict:
      type: object
      required: [error, conflictType, existingHash, existingUrl]
      properties:
        error:
          type: string
        conflictType:
          type: string
          enum: [document, attachment]
        existingHash:
          type: string
        existingPath:
          type: string
        existingUrl:
          type: string