{ "version": "1.0", "modules": [ { "name": "Time Logs", "prefix": "/time-logs", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Time Log", "description": "Creates a new time log entry for a job. Validates that the job and user exist, and that the user does not have overlapping time logs.", "request_body": { "schema_name": "TimelogCreate", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false }, { "name": "start_time", "type": "datetime", "required": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TimelogResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "start_time", "type": "datetime", "required": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Time Logs", "description": "Returns a paginated list of time logs. Supports filtering by job_id, user_id, and date range.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "job_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false }, { "name": "start_date", "type": "datetime", "required": false }, { "name": "end_date", "type": "datetime", "required": false } ], "response": { "schema_name": "TimelogListResponse", "fields": [ { "name": "items", "type": "list[TimelogResponse]", "required": true }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{timelog_id}", "summary": "Get Time Log", "description": "Returns a single time log by ID. Returns 404 if the time log does not exist.", "path_params": [ { "name": "timelog_id", "type": "str" } ], "response": { "schema_name": "TimelogResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "start_time", "type": "datetime", "required": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{timelog_id}", "summary": "Update Time Log", "description": "Updates an existing time log. Validates that end_time is after start_time and that the user does not have overlapping time logs. Returns 404 if the time log does not exist.", "path_params": [ { "name": "timelog_id", "type": "str" } ], "request_body": { "schema_name": "TimelogUpdate", "fields": [ { "name": "job_id", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "start_time", "type": "datetime", "required": false, "nullable": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TimelogResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "start_time", "type": "datetime", "required": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{timelog_id}", "summary": "Delete Time Log", "description": "Deletes a time log by ID. Returns 404 if the time log does not exist.", "path_params": [ { "name": "timelog_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/start", "summary": "Start Time Tracking", "description": "Starts a new time tracking session for a user on a specified job. Validates that the user does not already have an active timer running. Returns 409 if the user has an active time log.", "query_params": [ { "name": "user_id", "type": "str", "required": false, "default": null } ], "request_body": { "schema_name": "TimelogStartRequest", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TimelogResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "start_time", "type": "datetime", "required": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "POST", "path": "/{timelog_id}/stop", "summary": "Stop Time Tracking", "description": "Stops an active time tracking session. Calculates duration in minutes and updates the time log. Returns 400 if the time log has already been stopped. Returns 404 if the time log does not exist.", "path_params": [ { "name": "timelog_id", "type": "str" } ], "request_body": { "schema_name": "TimelogStopRequest", "fields": [ { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TimelogResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "start_time", "type": "datetime", "required": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Organization", "prefix": "/organization", "endpoints": [ { "method": "POST", "path": "/departments", "summary": "Create Department", "description": "Creates a new department record. Returns 409 if a department with the same name already exists.", "request_body": { "schema_name": "DepartmentCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "DepartmentResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/departments/{entity_id}", "summary": "Get Department By ID", "description": "Retrieves a single department by its unique identifier. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "DepartmentResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/departments", "summary": "List Departments", "description": "Returns a paginated list of departments. Supports optional search by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedDepartmentResponse", "fields": [ { "name": "items", "type": "List[DepartmentResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/departments/{entity_id}", "summary": "Update Department", "description": "Updates an existing department. Only provided fields are modified. Returns 404 if department not found, 409 if new name conflicts.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "DepartmentUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "DepartmentResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/departments/{entity_id}", "summary": "Delete Department", "description": "Deletes a department. Returns 404 if not found, 409 if department has associated users or jobs.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/teams", "summary": "Create Team", "description": "Creates a new team within a department. Returns 400 if department does not exist.", "request_body": { "schema_name": "TeamCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false } ] }, "response": { "schema_name": "TeamResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/teams/{entity_id}", "summary": "Get Team By ID", "description": "Retrieves a single team by its unique identifier. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "TeamResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/teams", "summary": "List Teams", "description": "Returns a paginated list of teams. Supports optional filters for department and search by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "department_id", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedTeamResponse", "fields": [ { "name": "items", "type": "List[TeamResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/teams/{entity_id}", "summary": "Update Team", "description": "Updates an existing team. Only provided fields are modified. Returns 404 if team not found, 400 if department does not exist.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "TeamUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TeamResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/teams/{entity_id}", "summary": "Delete Team", "description": "Deletes a team. Returns 404 if not found, 409 if team has active jobs or user assignments.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/teams/{entity_id}/details", "summary": "Get Team Details", "description": "Retrieves detailed team information including department and all user assignments with user details. Returns 404 if team not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "TeamDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "department", "type": "DepartmentSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "user_teams", "type": "List[UserteamDetail]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "user", "type": "UserSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "created_at", "type": "datetime", "required": true } ] }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/user-teams", "summary": "Assign User To Team", "description": "Creates a user-team assignment. Returns 400 if user or team does not exist, 409 if assignment already exists.", "request_body": { "schema_name": "UserteamCreate", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false } ] }, "response": { "schema_name": "UserteamResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/user-teams/{entity_id}", "summary": "Get User Team Assignment By ID", "description": "Retrieves a single user-team assignment by its unique identifier. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "UserteamResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/user-teams", "summary": "List User Team Assignments", "description": "Returns a paginated list of user-team assignments. Supports optional filters for user_id and team_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedUserteamResponse", "fields": [ { "name": "items", "type": "List[UserteamResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/user-teams/{entity_id}", "summary": "Update User Team Assignment", "description": "Updates an existing user-team assignment. Only provided fields are modified. Returns 404 if assignment not found, 400 if user or team does not exist.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "UserteamUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "team_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserteamResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/user-teams/{entity_id}", "summary": "Remove User From Team", "description": "Deletes a user-team assignment. Returns 404 if assignment not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Users", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User", "description": "Creates a new user account with email, password, role, and optional department assignment. Returns 409 if email already exists. Password must be minimum 8 characters including uppercase, lowercase, and number.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": false }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "Administrator", "Manager", "Team Member", "Viewer" ] }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "password", "type": "str", "required": false } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "Administrator", "Manager", "Team Member", "Viewer" ] }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filters for role, is_active status, department_id, and search by name or email.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "role", "type": "UserRole", "required": false }, { "name": "is_active", "type": "bool", "required": false }, { "name": "department_id", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedResponse[UserResponse]", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "GET", "path": "/{user_id}", "summary": "Get User By ID", "description": "Returns user details by ID. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "Administrator", "Manager", "Team Member", "Viewer" ] }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{user_id}/details", "summary": "Get User Details", "description": "Returns comprehensive user details including department and team memberships. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "Administrator", "Manager", "Team Member", "Viewer" ] }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "department", "type": "DepartmentSummary", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "user_teams", "type": "List[UserTeamSummary]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "team", "type": "TeamSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "department", "type": "DepartmentSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] } ] }, { "name": "created_at", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{user_id}", "summary": "Update User", "description": "Updates user information. All fields are optional. Returns 404 if user not found, 409 if new email already exists for another user.", "path_params": [ { "name": "user_id", "type": "str" } ], "query_params": [ { "name": "data", "type": "UserUpdate", "required": false, "default": null } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "Administrator", "Manager", "Team Member", "Viewer" ] }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{user_id}", "summary": "Delete User", "description": "Deletes user by ID. Returns 404 if user not found, 409 if user is referenced by jobs or other resources.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Job Configuration", "prefix": "/job-configuration", "endpoints": [ { "method": "POST", "path": "/job-types", "summary": "Create Job Type", "description": "Creates a new job type configuration. Returns 409 if a job type with the same name already exists.", "request_body": { "schema_name": "JobtypeCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "JobtypeResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/job-types/{entity_id}", "summary": "Get Job Type", "description": "Retrieves a single job type by ID. Returns 404 if the job type does not exist.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "JobtypeResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/job-types", "summary": "List Job Types", "description": "Returns a paginated list of job types. Supports filtering by active status and searching by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedResponse[JobtypeResponse]", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "PATCH", "path": "/job-types/{entity_id}", "summary": "Update Job Type", "description": "Updates an existing job type. Returns 404 if the job type does not exist, 409 if the updated name conflicts with another job type.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "JobtypeUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "JobtypeResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/job-types/{entity_id}", "summary": "Delete Job Type", "description": "Deletes a job type. Returns 404 if the job type does not exist, 409 if the job type is referenced by existing jobs.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/job-statuses", "summary": "Create Job Status", "description": "Creates a new job status configuration. Returns 409 if a job status with the same name already exists.", "request_body": { "schema_name": "JobstatusCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "JobstatusResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/job-statuses/{entity_id}", "summary": "Get Job Status", "description": "Retrieves a single job status by ID. Returns 404 if the job status does not exist.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "JobstatusResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/job-statuses", "summary": "List Job Statuses", "description": "Returns a paginated list of job statuses ordered by display_order. Supports filtering by active status and searching by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedResponse[JobstatusResponse]", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "PATCH", "path": "/job-statuses/{entity_id}", "summary": "Update Job Status", "description": "Updates an existing job status. Returns 404 if the job status does not exist, 409 if the updated name conflicts with another job status.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "JobstatusUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "JobstatusResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/job-statuses/{entity_id}", "summary": "Delete Job Status", "description": "Deletes a job status. Returns 404 if the job status does not exist, 409 if the job status is referenced by existing jobs.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/job-priorities", "summary": "Create Job Priority", "description": "Creates a new job priority configuration. Returns 409 if a job priority with the same name already exists.", "request_body": { "schema_name": "JobpriorityCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "level", "type": "int", "required": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "JobpriorityResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "level", "type": "int", "required": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/job-priorities/{entity_id}", "summary": "Get Job Priority", "description": "Retrieves a single job priority by ID. Returns 404 if the job priority does not exist.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "JobpriorityResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "level", "type": "int", "required": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/job-priorities", "summary": "List Job Priorities", "description": "Returns a paginated list of job priorities ordered by level. Supports filtering by active status and searching by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedResponse[JobpriorityResponse]", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "PATCH", "path": "/job-priorities/{entity_id}", "summary": "Update Job Priority", "description": "Updates an existing job priority. Returns 404 if the job priority does not exist, 409 if the updated name conflicts with another job priority.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "JobpriorityUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "level", "type": "int", "required": false, "nullable": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "JobpriorityResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "level", "type": "int", "required": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/job-priorities/{entity_id}", "summary": "Delete Job Priority", "description": "Deletes a job priority. Returns 404 if the job priority does not exist, 409 if the job priority is referenced by existing jobs.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/tags", "summary": "Create Tag", "description": "Creates a new tag for categorizing jobs. Returns 409 if a tag with the same name already exists.", "request_body": { "schema_name": "TagCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "color", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TagResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "usage_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/tags/{entity_id}", "summary": "Get Tag", "description": "Retrieves a single tag by ID. Returns 404 if the tag does not exist.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "TagResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "usage_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/tags", "summary": "List Tags", "description": "Returns a paginated list of tags ordered by usage count descending. Supports searching by name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedResponse[TagResponse]", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "PATCH", "path": "/tags/{entity_id}", "summary": "Update Tag", "description": "Updates an existing tag. Returns 404 if the tag does not exist, 409 if the updated name conflicts with another tag.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "TagUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "color", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TagResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "color", "type": "str", "required": false, "nullable": true }, { "name": "usage_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/tags/{entity_id}", "summary": "Delete Tag", "description": "Deletes a tag. Returns 404 if the tag does not exist, 409 if the tag is referenced by existing job tags.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Reports", "prefix": "/reports", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Report", "description": "Creates a new report record. Validates that the generated_by_user_id references an existing user. Returns 400 if user does not exist.", "request_body": { "schema_name": "ReportCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "str", "required": false }, { "name": "parameters", "type": "Dict[str, Any]", "required": false }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "export_format", "type": "str", "required": false, "nullable": true }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "generated_by_user_id", "type": "str", "required": false } ] }, "response": { "schema_name": "ReportResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "str", "required": false }, { "name": "parameters", "type": "Dict[str, Any]", "required": false }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "export_format", "type": "str", "required": false, "nullable": true }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Reports", "description": "Returns a paginated list of reports. Supports optional filters on report_type and generated_by_user_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "report_type", "type": "str", "required": false }, { "name": "generated_by_user_id", "type": "str", "required": false } ], "response": { "schema_name": "ReportListResponse", "fields": [ { "name": "items", "type": "List[ReportResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "str", "required": false }, { "name": "parameters", "type": "Dict[str, Any]", "required": false }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "export_format", "type": "str", "required": false, "nullable": true }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{report_id}", "summary": "Get Report", "description": "Retrieves a single report by ID. Returns 404 if the report does not exist.", "path_params": [ { "name": "report_id", "type": "str" } ], "response": { "schema_name": "ReportResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "str", "required": false }, { "name": "parameters", "type": "Dict[str, Any]", "required": false }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "export_format", "type": "str", "required": false, "nullable": true }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{report_id}/details", "summary": "Get Report Details", "description": "Retrieves a report with related user details (generated_by_user). Returns 404 if the report does not exist.", "path_params": [ { "name": "report_id", "type": "str" } ], "response": { "schema_name": "ReportDetailResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "str", "required": false }, { "name": "parameters", "type": "Dict[str, Any]", "required": false }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "export_format", "type": "str", "required": false, "nullable": true }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "generated_by_user", "type": "GeneratedByUserSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PATCH", "path": "/{report_id}", "summary": "Update Report", "description": "Updates a report with the provided fields. Only fields present in the request body are updated. Returns 404 if the report does not exist.", "path_params": [ { "name": "report_id", "type": "str" } ], "request_body": { "schema_name": "ReportUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "str", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "export_format", "type": "str", "required": false, "nullable": true }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReportResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "str", "required": false }, { "name": "parameters", "type": "Dict[str, Any]", "required": false }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "export_format", "type": "str", "required": false, "nullable": true }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{report_id}", "summary": "Delete Report", "description": "Deletes a report by ID. Returns 404 if the report does not exist. Returns 409 if the report is referenced by other records.", "path_params": [ { "name": "report_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Checklists", "prefix": "/checklists", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Checklist", "description": "Creates a new checklist for a job. Validates that the referenced job exists. Returns 404 if job not found.", "request_body": { "schema_name": "ChecklistCreate", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false } ] }, "response": { "schema_name": "ChecklistResponse", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Checklists", "description": "Returns a paginated list of checklists. Supports optional filtering by job_id. Ordered by display_order and creation date.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "job_id", "type": "str", "required": false } ], "response": { "schema_name": "ChecklistListResponse", "fields": [ { "name": "items", "type": "List[ChecklistResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{checklist_id}", "summary": "Get Checklist", "description": "Retrieves a single checklist by ID. Returns 404 if checklist not found.", "path_params": [ { "name": "checklist_id", "type": "str" } ], "response": { "schema_name": "ChecklistResponse", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{checklist_id}", "summary": "Update Checklist", "description": "Updates an existing checklist. Validates referenced job if job_id is updated. Returns 404 if checklist not found, 400 if job not found.", "path_params": [ { "name": "checklist_id", "type": "str" } ], "request_body": { "schema_name": "ChecklistUpdate", "fields": [ { "name": "job_id", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "ChecklistResponse", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{checklist_id}", "summary": "Delete Checklist", "description": "Deletes a checklist and cascades to all checklist items. Returns 404 if checklist not found, 409 if deletion would violate constraints.", "path_params": [ { "name": "checklist_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/items", "summary": "Create Checklist Item", "description": "Creates a new checklist item within a checklist. Validates that the referenced checklist and optional assigned user exist. Returns 404 if checklist not found, 400 if assigned user not found.", "request_body": { "schema_name": "ChecklistitemCreate", "fields": [ { "name": "checklist_id", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false }, { "name": "is_completed", "type": "bool", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ChecklistitemResponse", "fields": [ { "name": "checklist_id", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false }, { "name": "is_completed", "type": "bool", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/items", "summary": "List Checklist Items", "description": "Returns a paginated list of checklist items. Supports optional filtering by checklist_id, is_completed, and assigned_to_user_id. Ordered by display_order and creation date.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "checklist_id", "type": "str", "required": false }, { "name": "is_completed", "type": "bool", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false } ], "response": { "schema_name": "ChecklistitemListResponse", "fields": [ { "name": "items", "type": "List[ChecklistitemResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "checklist_id", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false }, { "name": "is_completed", "type": "bool", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/items/{checklist_item_id}", "summary": "Get Checklist Item", "description": "Retrieves a single checklist item by ID. Returns 404 if checklist item not found.", "path_params": [ { "name": "checklist_item_id", "type": "str" } ], "response": { "schema_name": "ChecklistitemResponse", "fields": [ { "name": "checklist_id", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false }, { "name": "is_completed", "type": "bool", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/items/{checklist_item_id}", "summary": "Update Checklist Item", "description": "Updates an existing checklist item. Validates referenced checklist and optional assigned user if updated. Returns 404 if checklist item not found, 400 if referenced entities not found.", "path_params": [ { "name": "checklist_item_id", "type": "str" } ], "request_body": { "schema_name": "ChecklistitemUpdate", "fields": [ { "name": "checklist_id", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_completed", "type": "bool", "required": false, "nullable": true }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ChecklistitemResponse", "fields": [ { "name": "checklist_id", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false }, { "name": "is_completed", "type": "bool", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/items/{checklist_item_id}", "summary": "Delete Checklist Item", "description": "Deletes a checklist item. Returns 404 if checklist item not found, 409 if deletion would violate constraints.", "path_params": [ { "name": "checklist_item_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/items/{checklist_item_id}/complete", "summary": "Complete Checklist Item", "description": "Marks a checklist item as completed and records the completion timestamp. Returns 404 if checklist item not found, 400 if already completed.", "path_params": [ { "name": "checklist_item_id", "type": "str" } ], "response": { "schema_name": "ChecklistitemResponse", "fields": [ { "name": "checklist_id", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false }, { "name": "is_completed", "type": "bool", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Jobs", "prefix": "/jobs", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Job", "description": "Creates a new job with title, description, type, priority, status, and assignment details. Validates all foreign key references. Returns 400 if any referenced entity does not exist.", "request_body": { "schema_name": "JobCreate", "fields": [ { "name": "title", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "str", "required": false }, { "name": "job_status_id", "type": "str", "required": false }, { "name": "job_priority_id", "type": "str", "required": false }, { "name": "department_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "str", "required": false, "nullable": true }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false } ] }, "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Jobs", "description": "Returns a paginated list of jobs. Supports filters for status, priority, assignee, department, and team. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "job_status_id", "type": "str", "required": false }, { "name": "job_priority_id", "type": "str", "required": false }, { "name": "assigned_to_user_id", "type": "str", "required": false }, { "name": "department_id", "type": "str", "required": false }, { "name": "team_id", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedJobResponse", "fields": [ { "name": "items", "type": "List[JobResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{job_id}", "summary": "Get Job", "description": "Returns a single job by ID. Returns 404 if job does not exist.", "path_params": [ { "name": "job_id", "type": "str" } ], "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{job_id}/details", "summary": "Get Job Details", "description": "Returns comprehensive job details including all related entities: type, status, priority, users, department, team, parent job, comments, attachments, history, time logs, tags, and checklists with items. All relationships are eagerly loaded. Returns 404 if job does not exist.", "path_params": [ { "name": "job_id", "type": "str" } ], "response": { "schema_name": "JobDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "job_type", "type": "JobTypeNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "job_status", "type": "JobStatusNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "job_priority", "type": "JobPriorityNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "created_by_user", "type": "UserNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "assigned_to_user", "type": "UserNested", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "department", "type": "DepartmentNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "team", "type": "TeamNested", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "parent_job", "type": "ParentJobNested", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true } ] }, { "name": "comments", "type": "List[CommentDetailNested]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "content", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "user", "type": "UserNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] }, { "name": "attachments", "type": "List[AttachmentDetailNested]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "file_name", "type": "str", "required": true }, { "name": "file_size", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "uploaded_by_user", "type": "UserNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] }, { "name": "job_history", "type": "List[JobhistoryDetailNested]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "action_type", "type": "str", "required": true }, { "name": "field_name", "type": "str", "required": false, "nullable": true }, { "name": "old_value", "type": "str", "required": false, "nullable": true }, { "name": "new_value", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "user", "type": "UserNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] }, { "name": "time_logs", "type": "List[TimelogDetailNested]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "start_time", "type": "datetime", "required": true }, { "name": "end_time", "type": "datetime", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "user", "type": "UserNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] }, { "name": "job_tags", "type": "List[JobtagDetailNested]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "tag", "type": "TagNested", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] } ] }, { "name": "checklists", "type": "List[ChecklistDetailNested]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "checklist_items", "type": "List[ChecklistitemDetailNested]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "is_completed", "type": "bool", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "assigned_to_user", "type": "UserNested", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PATCH", "path": "/{job_id}", "summary": "Update Job", "description": "Updates job fields. Only provided fields are updated. Validates all foreign key references. Returns 404 if job does not exist, 400 if any referenced entity does not exist.", "path_params": [ { "name": "job_id", "type": "str" } ], "request_body": { "schema_name": "JobUpdate", "fields": [ { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "str", "required": false, "nullable": true }, { "name": "job_status_id", "type": "str", "required": false, "nullable": true }, { "name": "job_priority_id", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "team_id", "type": "str", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "str", "required": false, "nullable": true }, { "name": "assigned_to_user_id", "type": "str", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true } ] }, "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{job_id}", "summary": "Delete Job", "description": "Deletes a job by ID. Cascades to all child records. Returns 404 if job does not exist, 409 if deletion is blocked by constraints.", "path_params": [ { "name": "job_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{job_id}/assign", "summary": "Assign Job To User", "description": "Assigns job to a user. Updates assigned_to_user_id, creates history entry. Returns 404 if job not found, 400 if user does not exist.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "current_user_id", "type": "str", "required": false, "default": null } ], "request_body": { "schema_name": "JobAssignRequest", "fields": [ { "name": "assigned_to_user_id", "type": "str", "required": false } ] }, "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/reassign", "summary": "Reassign Job To Different User", "description": "Reassigns job to a different user. Updates assigned_to_user_id, creates history entry, sends notifications to previous and new assignees. Returns 404 if job not found, 400 if new user does not exist.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "current_user_id", "type": "str", "required": false, "default": null } ], "request_body": { "schema_name": "JobReassignRequest", "fields": [ { "name": "assigned_to_user_id", "type": "str", "required": false } ] }, "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/status", "summary": "Update Job Status", "description": "Updates job status to a new value. Creates history entry recording status change. Validates status transition. Returns 404 if job not found, 400 if status does not exist.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "current_user_id", "type": "str", "required": false, "default": null } ], "request_body": { "schema_name": "JobStatusUpdateRequest", "fields": [ { "name": "job_status_id", "type": "str", "required": false } ] }, "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/complete", "summary": "Mark Job As Completed", "description": "Marks job as completed after validating all checklist items are complete. Updates status to Completed, records completion timestamp, creates history entry. Returns 400 if checklist items are incomplete, 404 if job not found.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "current_user_id", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/cancel", "summary": "Cancel Job", "description": "Cancels job by updating status to Cancelled. Creates history entry. Stops any active time tracking. Returns 404 if job not found.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "current_user_id", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/reopen", "summary": "Reopen Completed Job", "description": "Reopens a completed job by updating status to In Progress and clearing completion timestamp. Creates history entry. Only Managers or Admins can reopen. Returns 404 if job not found.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "current_user_id", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "JobResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "job_type_id", "type": "StrId", "required": true }, { "name": "job_status_id", "type": "StrId", "required": true }, { "name": "job_priority_id", "type": "StrId", "required": true }, { "name": "created_by_user_id", "type": "StrId", "required": true }, { "name": "assigned_to_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": true }, { "name": "team_id", "type": "StrId", "required": false, "nullable": true }, { "name": "parent_job_id", "type": "StrId", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "started_at", "type": "datetime", "required": false, "nullable": true }, { "name": "completed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_hours", "type": "Decimal", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/comments", "summary": "Add Comment To Job", "description": "Creates a new comment attached to job. Optionally mentions other users with @username. Returns 400 if job or user does not exist.", "request_body": { "schema_name": "CommentCreate", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "content", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false } ] }, "response": { "schema_name": "CommentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "content", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{job_id}/comments", "summary": "List Job Comments", "description": "Returns paginated list of comments for a specific job. Ordered by creation date descending.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "PaginatedCommentResponse", "fields": [ { "name": "items", "type": "List[CommentResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "content", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/attachments", "summary": "Upload Attachment To Job", "description": "Uploads a file attachment to job. Validates file type and size (max 10MB). Returns 400 if file size exceeds limit or if job/user does not exist.", "request_body": { "schema_name": "AttachmentCreate", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "file_name", "type": "str", "required": false }, { "name": "file_path", "type": "str", "required": false }, { "name": "file_type", "type": "str", "required": false, "nullable": true }, { "name": "file_size", "type": "int", "required": true }, { "name": "uploaded_by_user_id", "type": "str", "required": false } ] }, "response": { "schema_name": "AttachmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "uploaded_by_user_id", "type": "StrId", "required": true }, { "name": "file_name", "type": "str", "required": true }, { "name": "file_path", "type": "str", "required": true }, { "name": "file_type", "type": "str", "required": false, "nullable": true }, { "name": "file_size", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{job_id}/attachments", "summary": "List Job Attachments", "description": "Returns paginated list of attachments for a specific job. Ordered by creation date descending.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "PaginatedAttachmentResponse", "fields": [ { "name": "items", "type": "List[AttachmentResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "uploaded_by_user_id", "type": "StrId", "required": true }, { "name": "file_name", "type": "str", "required": true }, { "name": "file_path", "type": "str", "required": true }, { "name": "file_type", "type": "str", "required": false, "nullable": true }, { "name": "file_size", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{job_id}/history", "summary": "Get Job Audit History", "description": "Returns paginated audit trail of all changes and actions performed on job. Includes field changes, status transitions, assignments. Ordered by creation date descending.", "path_params": [ { "name": "job_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "PaginatedJobhistoryResponse", "fields": [ { "name": "items", "type": "List[JobhistoryResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "action_type", "type": "str", "required": true }, { "name": "field_name", "type": "str", "required": false, "nullable": true }, { "name": "old_value", "type": "str", "required": false, "nullable": true }, { "name": "new_value", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{job_id}/tags", "summary": "Add Tag To Job", "description": "Associates a tag with a job. Returns 409 if tag already associated with job, 400 if job or tag does not exist.", "request_body": { "schema_name": "JobtagCreate", "fields": [ { "name": "job_id", "type": "str", "required": false }, { "name": "tag_id", "type": "str", "required": false } ] }, "response": { "schema_name": "JobtagResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "tag_id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "DELETE", "path": "/tags/{jobtag_id}", "summary": "Remove Tag From Job", "description": "Removes tag association from job. Returns 404 if job tag relationship does not exist.", "path_params": [ { "name": "jobtag_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/comments/{comment_id}", "summary": "Get Comment", "description": "Returns a single comment by ID. Returns 404 if comment does not exist.", "path_params": [ { "name": "comment_id", "type": "str" } ], "response": { "schema_name": "CommentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "content", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PATCH", "path": "/comments/{comment_id}", "summary": "Update Comment", "description": "Updates comment content. Returns 404 if comment does not exist.", "path_params": [ { "name": "comment_id", "type": "str" } ], "request_body": { "schema_name": "CommentUpdate", "fields": [ { "name": "content", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CommentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "content", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/comments/{comment_id}", "summary": "Delete Comment", "description": "Deletes a comment by ID. Returns 404 if comment does not exist.", "path_params": [ { "name": "comment_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/attachments/{attachment_id}", "summary": "Get Attachment", "description": "Returns a single attachment by ID. Returns 404 if attachment does not exist.", "path_params": [ { "name": "attachment_id", "type": "str" } ], "response": { "schema_name": "AttachmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "uploaded_by_user_id", "type": "StrId", "required": true }, { "name": "file_name", "type": "str", "required": true }, { "name": "file_path", "type": "str", "required": true }, { "name": "file_type", "type": "str", "required": false, "nullable": true }, { "name": "file_size", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PATCH", "path": "/attachments/{attachment_id}", "summary": "Update Attachment", "description": "Updates attachment metadata. Returns 404 if attachment does not exist.", "path_params": [ { "name": "attachment_id", "type": "str" } ], "request_body": { "schema_name": "AttachmentUpdate", "fields": [ { "name": "file_name", "type": "str", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "file_type", "type": "str", "required": false, "nullable": true }, { "name": "file_size", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "AttachmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "uploaded_by_user_id", "type": "StrId", "required": true }, { "name": "file_name", "type": "str", "required": true }, { "name": "file_path", "type": "str", "required": true }, { "name": "file_type", "type": "str", "required": false, "nullable": true }, { "name": "file_size", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/attachments/{attachment_id}", "summary": "Delete Attachment", "description": "Deletes an attachment by ID. Returns 404 if attachment does not exist.", "path_params": [ { "name": "attachment_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/history/{history_id}", "summary": "Get Job History Entry", "description": "Returns a single job history entry by ID. Returns 404 if history entry does not exist.", "path_params": [ { "name": "history_id", "type": "str" } ], "response": { "schema_name": "JobhistoryResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "job_id", "type": "StrId", "required": true }, { "name": "user_id", "type": "StrId", "required": true }, { "name": "action_type", "type": "str", "required": true }, { "name": "field_name", "type": "str", "required": false, "nullable": true }, { "name": "old_value", "type": "str", "required": false, "nullable": true }, { "name": "new_value", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] } ], "enums": { "UserRole": [ "Administrator", "Manager", "Team Member", "Viewer" ] } }