{
  "openapi": "3.1.0",
  "info": {
    "title": "sist79-backend",
    "version": "1.0.0",
    "description": "Backend API built with Next.js, TypeScript, and MongoDB."
  },
  "servers": [
    {
      "url": "https://sist79-be.dfm-europe.com",
      "description": "Current environment"
    }
  ],
  "components": {
    "securitySchemes": {
      "hmacImport": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Signature",
        "description": "HMAC-SHA256 of the canonical import string"
      },
      "accessTokenCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "sist79_access_token",
        "description": "HttpOnly access-token cookie set by /api/auth/login or /api/auth/refresh"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "UserListSuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/User"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "page": {
                "type": "number"
              },
              "limit": {
                "type": "number"
              },
              "total": {
                "type": "number"
              },
              "totalPages": {
                "type": "number"
              }
            },
            "required": [
              "page",
              "limit",
              "total",
              "totalPages"
            ]
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "user"
            ]
          },
          "isActive": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "email",
          "role",
          "isActive",
          "createdAt",
          "updatedAt"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "UserSuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/User"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "CreateUserRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "example": "Jane Doe"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "jane@example.com"
          },
          "password": {
            "type": "string",
            "minLength": 8,
            "example": "password123"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "user"
            ],
            "example": "user"
          }
        },
        "required": [
          "name",
          "email",
          "password"
        ]
      },
      "UpdateUserRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "password": {
            "type": "string",
            "minLength": 8
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "user"
            ]
          },
          "isActive": {
            "type": "boolean"
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "example": "admin@example.com"
          },
          "password": {
            "type": "string",
            "minLength": 8,
            "example": "Admin12345"
          }
        },
        "required": [
          "email",
          "password"
        ]
      },
      "RefreshRequest": {
        "type": "object",
        "properties": {
          "refreshToken": {
            "type": "string",
            "minLength": 1,
            "example": "eyJhbGciOiJIUzI1NiJ9..."
          }
        },
        "required": [
          "refreshToken"
        ]
      },
      "AgendaImportFile": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "string",
            "enum": [
              "1.0",
              "1.1"
            ]
          },
          "source": {
            "type": "string",
            "minLength": 1
          },
          "scrapedAt": {
            "type": "string",
            "minLength": 1
          },
          "userContext": {
            "type": "object",
            "properties": {
              "sourceUserId": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 1
              },
              "login": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 1
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 1
              }
            }
          },
          "agendas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sourceExternalId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "code": {
                  "type": "string",
                  "minLength": 1
                },
                "label": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "PERSONAL",
                    "MULTI_RESOURCE"
                  ]
                },
                "status": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "site": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "timezone": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                }
              },
              "required": [
                "code"
              ]
            },
            "default": []
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sourceExternalId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "sourceResourceId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "externalId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "civility": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "firstName": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "lastName": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "fullName": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "professionalPhone": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "professionalEmail": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "functionType": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "status": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "agendaCode": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "siteCode": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "siteAssignments": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "siteCode": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      },
                      "siteLabel": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      },
                      "agendaCode": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      }
                    }
                  }
                }
              }
            },
            "default": []
          },
          "appointments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sourceAppointmentId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "agendaCode": {
                  "type": "string",
                  "minLength": 1
                },
                "date": {
                  "type": "string",
                  "minLength": 1
                },
                "localStartTime": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "localEndTime": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "period": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "status": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "timezone": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "minLength": 1
                },
                "category": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "color": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "subCategory": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "individual": {
                  "type": "object",
                  "properties": {
                    "externalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "fullName": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "birthDate": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "ageAtAppointment": {
                      "type": "number"
                    },
                    "gender": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "displayLine": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "member": {
                  "type": "object",
                  "properties": {
                    "externalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "displayLine": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "center": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "site": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "timezone": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "assignedResourceExternalIds": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "assignedResourceSourceExternalIds": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "assignedResources": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "externalId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      },
                      "sourceExternalId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      },
                      "fullName": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      },
                      "functionTypeCode": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      },
                      "siteLabel": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      },
                      "siteCode": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "minLength": 1
                      }
                    }
                  }
                },
                "performedByResource": {
                  "type": "object",
                  "properties": {
                    "externalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "sourceExternalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "fullName": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "functionTypeCode": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "siteLabel": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "siteCode": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "expectedByResource": {
                  "type": "object",
                  "properties": {
                    "externalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "sourceExternalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "fullName": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "functionTypeCode": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "siteLabel": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "siteCode": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    }
                  }
                },
                "queue": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "arrivedAtLocal": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "departedAtLocal": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "takenByResourceExternalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "takenByResourceSourceExternalId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "takenByResourceName": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "honored": {
                      "type": "boolean"
                    },
                    "cancelled": {
                      "type": "boolean"
                    },
                    "locked": {
                      "type": "boolean"
                    }
                  }
                },
                "flags": {
                  "type": "object",
                  "properties": {
                    "hasArrivalTime": {
                      "type": "boolean"
                    },
                    "hasDepartureTime": {
                      "type": "boolean"
                    },
                    "hasAlert": {
                      "type": "boolean"
                    },
                    "hasDocument": {
                      "type": "boolean"
                    },
                    "isWorkStopped": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "required": [
                "agendaCode",
                "date"
              ]
            },
            "default": []
          },
          "agendaPreferences": {
            "type": "object",
            "properties": {
              "scope": {
                "type": "object",
                "properties": {
                  "agendaCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1
                  },
                  "siteCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1
                  }
                }
              },
              "general": {
                "type": "object",
                "properties": {
                  "weeklyTimeScaleMinutes": {
                    "type": "number"
                  },
                  "refreshFrequencyMinutes": {
                    "type": "number"
                  },
                  "showMultipleResourcesOnSinglePage": {
                    "type": "boolean"
                  }
                }
              },
              "categoryColors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "categoryCode": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "categoryLabel": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "minLength": 1
                    },
                    "color": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "required": [
                    "color"
                  ]
                }
              },
              "viewOptions": {
                "type": "object",
                "properties": {
                  "detailLevels": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1
                        },
                        "label": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "minLength": 1
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "displayOrder": {
                          "type": "number"
                        }
                      }
                    }
                  },
                  "showReservations": {
                    "type": "boolean"
                  },
                  "showAppointmentsWithArrivalTime": {
                    "type": "boolean"
                  },
                  "showQueueAppointmentsWithDepartureTime": {
                    "type": "boolean"
                  },
                  "showHonoredAppointments": {
                    "type": "boolean"
                  },
                  "showCancelledAppointments": {
                    "type": "boolean"
                  },
                  "showLockedAppointments": {
                    "type": "boolean"
                  }
                }
              },
              "emailDefaults": {
                "type": "object",
                "properties": {
                  "convocation": {
                    "type": "object",
                    "properties": {
                      "defaultSubject": {
                        "type": "string"
                      },
                      "defaultBody": {
                        "type": "string"
                      }
                    }
                  },
                  "endOfVisitDocuments": {
                    "type": "object",
                    "properties": {
                      "defaultSubject": {
                        "type": "string"
                      },
                      "defaultBody": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "required": [
          "schemaVersion",
          "source",
          "scrapedAt"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/api/users": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "List users",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "required": false,
            "name": "limit",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated user list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserListSuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Create a user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserSuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Email already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{id}": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Get a user by id",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{24}$",
              "example": "507f1f77bcf86cd799439011"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "User found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserSuccessResponse"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Users"
        ],
        "summary": "Update a user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{24}$",
              "example": "507f1f77bcf86cd799439011"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserSuccessResponse"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Users"
        ],
        "summary": "Delete a user",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^[a-fA-F0-9]{24}$",
              "example": "507f1f77bcf86cd799439011"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "User deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Login (USER or SERVICE_ACCOUNT)",
        "description": "Use the UEGAR BOT service-account credentials here. The response also sets HttpOnly access and refresh cookies.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Login successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "user": {
                          "$ref": "#/components/schemas/User"
                        },
                        "accessToken": {
                          "type": "string"
                        },
                        "refreshToken": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "user",
                        "accessToken",
                        "refreshToken"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/refresh": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Refresh access token (body or refresh cookie)",
        "description": "The existing refresh token flow reloads current account status and scopes before issuing new tokens.",
        "security": [
          {
            "accessTokenCookie": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tokens refreshed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "accessToken": {
                          "type": "string"
                        },
                        "refreshToken": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "accessToken",
                        "refreshToken"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Invalid refresh token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/logout": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Logout and clear auth cookies",
        "security": [
          {
            "accessTokenCookie": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Logged out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "loggedOut": {
                          "type": "boolean",
                          "enum": [
                            true
                          ]
                        }
                      },
                      "required": [
                        "loggedOut"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/internal/imports": {
      "post": {
        "tags": [
          "Agenda Import"
        ],
        "summary": "Machine-to-machine Agenda file import",
        "security": [
          {
            "accessTokenCookie": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "agenda-bot",
              "description": "Optional client id for logging/rate limit"
            },
            "required": false,
            "description": "Optional client id for logging/rate limit",
            "name": "X-Client-Id",
            "in": "header"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgendaImportFile"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Import processed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "importId": {
                          "type": "string"
                        },
                        "partial": {
                          "type": "boolean"
                        },
                        "warningCount": {
                          "type": "number"
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "received": {
                              "type": "number"
                            },
                            "created": {
                              "type": "number"
                            },
                            "updated": {
                              "type": "number"
                            },
                            "unchanged": {
                              "type": "number"
                            },
                            "identityConflicts": {
                              "type": "number"
                            },
                            "invalid": {
                              "type": "number"
                            },
                            "failed": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "received",
                            "created",
                            "updated",
                            "unchanged",
                            "identityConflicts",
                            "invalid",
                            "failed"
                          ]
                        },
                        "recordErrors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "entityType": {
                                "type": "string",
                                "enum": [
                                  "agenda",
                                  "resource",
                                  "appointment",
                                  "preference"
                                ]
                              },
                              "action": {
                                "type": "string",
                                "enum": [
                                  "IDENTITY_CONFLICT",
                                  "INVALID"
                                ]
                              },
                              "importKey": {
                                "type": "string"
                              },
                              "matchedBy": {
                                "type": "string"
                              },
                              "reasonCode": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "entityType",
                              "action"
                            ]
                          }
                        }
                      },
                      "required": [
                        "importId",
                        "partial",
                        "warningCount",
                        "summary",
                        "recordErrors"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required or invalid access token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "A USER account or a service account without agenda:import cannot import",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": {
            "description": "API and database are healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "database": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "disconnected"
                          ]
                        },
                        "timestamp": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "database",
                        "timestamp"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Database unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "database": {
                          "type": "string",
                          "enum": [
                            "connected",
                            "disconnected"
                          ]
                        },
                        "timestamp": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "database",
                        "timestamp"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}