{"openapi":"3.1.0","info":{"title":"Employees API","description":"A practice REST API for learning how clients and servers talk. Full guide: https://employees-api.taila30d72.ts.net/","version":"1.0"},"paths":{"/api":{"get":{"tags":["General"],"summary":"Welcome: list every endpoint","operationId":"welcome_api_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/health":{"get":{"tags":["General"],"summary":"Is the API up? (no token needed)","operationId":"health_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/departments":{"get":{"tags":["Departments"],"summary":"List all departments","operationId":"list_departments_api_departments_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["Departments"],"summary":"Create a department","operationId":"create_department_api_departments_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentIn"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/departments/{department_id}":{"get":{"tags":["Departments"],"summary":"Get one department","operationId":"get_department_api_departments__department_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string","pattern":"^d\\d{3}$","description":"Department id, like d005","examples":["d005"],"title":"Department Id"},"description":"Department id, like d005"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Departments"],"summary":"Rename a department","operationId":"update_department_api_departments__department_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string","pattern":"^d\\d{3}$","description":"Department id, like d005","examples":["d005"],"title":"Department Id"},"description":"Department id, like d005"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Departments"],"summary":"Delete a department","operationId":"delete_department_api_departments__department_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string","pattern":"^d\\d{3}$","description":"Department id, like d005","examples":["d005"],"title":"Department Id"},"description":"Department id, like d005"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/departments/{department_id}/employees":{"get":{"tags":["Departments"],"summary":"Employees currently in a department","operationId":"department_employees_api_departments__department_id__employees_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string","pattern":"^d\\d{3}$","description":"Department id, like d005","examples":["d005"],"title":"Department Id"},"description":"Department id, like d005"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many results per page (1-100)","default":20,"title":"Limit"},"description":"How many results per page (1-100)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"How many results to skip","default":0,"title":"Offset"},"description":"How many results to skip"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/employees":{"get":{"tags":["Employees"],"summary":"List employees (with filters and pages)","operationId":"list_employees_api_employees_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many results per page (1-100)","default":20,"title":"Limit"},"description":"How many results per page (1-100)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"How many results to skip","default":0,"title":"Offset"},"description":"How many results to skip"},{"name":"first_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact first name, any capitalisation","examples":["Georgi"],"title":"First Name"},"description":"Exact first name, any capitalisation"},{"name":"last_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact last name, any capitalisation","examples":["Facello"],"title":"Last Name"},"description":"Exact last name, any capitalisation"},{"name":"gender","in":"query","required":false,"schema":{"anyOf":[{"enum":["M","F"],"type":"string"},{"type":"null"}],"description":"M or F","title":"Gender"},"description":"M or F"},{"name":"department_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^d\\d{3}$"},{"type":"null"}],"description":"Only employees currently in this department","title":"Department Id"},"description":"Only employees currently in this department"},{"name":"hired_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Hired on or after this date (YYYY-MM-DD)","title":"Hired After"},"description":"Hired on or after this date (YYYY-MM-DD)"},{"name":"hired_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Hired on or before this date (YYYY-MM-DD)","title":"Hired Before"},"description":"Hired on or before this date (YYYY-MM-DD)"},{"name":"sort","in":"query","required":false,"schema":{"enum":["id","-id","last_name","-last_name","hire_date","-hire_date","birth_date","-birth_date"],"type":"string","description":"Sort order. Add '-' for descending, e.g. -hire_date","default":"id","title":"Sort"},"description":"Sort order. Add '-' for descending, e.g. -hire_date"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Employees"],"summary":"Create an employee","operationId":"create_employee_api_employees_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/employees/{employee_id}":{"get":{"tags":["Employees"],"summary":"Get one employee, with current department, title and salary","operationId":"get_employee_api_employees__employee_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Employees"],"summary":"Replace an employee (send every field)","operationId":"replace_employee_api_employees__employee_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeFields"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Employees"],"summary":"Change some fields of an employee","operationId":"patch_employee_api_employees__employee_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeePatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Employees"],"summary":"Delete an employee (and their salaries, titles, departments)","operationId":"delete_employee_api_employees__employee_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/employees/{employee_id}/salaries":{"get":{"tags":["Salaries"],"summary":"An employee's salary history","operationId":"list_salaries_api_employees__employee_id__salaries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Salaries"],"summary":"Add a salary record","operationId":"add_salary_api_employees__employee_id__salaries_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalaryIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/employees/{employee_id}/salaries/{from_date}":{"patch":{"tags":["Salaries"],"summary":"Change a salary's amount or end date","operationId":"patch_salary_api_employees__employee_id__salaries__from_date__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"},{"name":"from_date","in":"path","required":true,"schema":{"type":"string","format":"date","description":"The salary's from_date (YYYY-MM-DD)","title":"From Date"},"description":"The salary's from_date (YYYY-MM-DD)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalaryPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Salaries"],"summary":"Delete a salary record","operationId":"delete_salary_api_employees__employee_id__salaries__from_date__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"},{"name":"from_date","in":"path","required":true,"schema":{"type":"string","format":"date","description":"The salary's from_date (YYYY-MM-DD)","title":"From Date"},"description":"The salary's from_date (YYYY-MM-DD)"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/employees/{employee_id}/titles":{"get":{"tags":["Titles"],"summary":"An employee's job titles over time","operationId":"list_titles_api_employees__employee_id__titles_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Titles"],"summary":"Add a job title","operationId":"add_title_api_employees__employee_id__titles_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/employees/{employee_id}/titles/{from_date}":{"delete":{"tags":["Titles"],"summary":"Delete a job title","operationId":"delete_title_api_employees__employee_id__titles__from_date__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Employee id, like 10001","examples":[10001],"title":"Employee Id"},"description":"Employee id, like 10001"},{"name":"from_date","in":"path","required":true,"schema":{"type":"string","format":"date","description":"The title's from_date (YYYY-MM-DD)","title":"From Date"},"description":"The title's from_date (YYYY-MM-DD)"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/stats/departments":{"get":{"tags":["Statistics"],"summary":"Headcount and average current salary per department","operationId":"stats_departments_api_stats_departments_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/stats/titles":{"get":{"tags":["Statistics"],"summary":"Headcount and average current salary per job title","operationId":"stats_titles_api_stats_titles_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/stats/hires-by-year":{"get":{"tags":["Statistics"],"summary":"How many people were hired each year","operationId":"stats_hires_api_stats_hires_by_year_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/admin/reset":{"post":{"tags":["Teacher"],"summary":"Reset the playground now (teacher token only)","operationId":"reset_now_api_admin_reset_post","responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"DepartmentIn":{"properties":{"id":{"type":"string","pattern":"^d\\d{3}$","title":"Id","description":"A new id: 'd' and three digits","examples":["d010"]},"name":{"type":"string","maxLength":40,"minLength":1,"title":"Name","description":"Must not be used by another department","examples":["Data Science"]}},"additionalProperties":false,"type":"object","required":["id","name"],"title":"DepartmentIn"},"DepartmentUpdate":{"properties":{"name":{"type":"string","maxLength":40,"minLength":1,"title":"Name","description":"Must not be used by another department","examples":["Data & Analytics"]}},"additionalProperties":false,"type":"object","required":["name"],"title":"DepartmentUpdate"},"EmployeeFields":{"properties":{"first_name":{"type":"string","maxLength":14,"minLength":1,"title":"First Name","examples":["Ada"]},"last_name":{"type":"string","maxLength":16,"minLength":1,"title":"Last Name","examples":["Lovelace"]},"gender":{"type":"string","enum":["M","F"],"title":"Gender","examples":["F"]},"birth_date":{"type":"string","format":"date","title":"Birth Date","examples":["1990-12-10"]},"hire_date":{"type":"string","format":"date","title":"Hire Date","examples":["2024-03-01"]}},"additionalProperties":false,"type":"object","required":["first_name","last_name","gender","birth_date","hire_date"],"title":"EmployeeFields"},"EmployeeIn":{"properties":{"first_name":{"type":"string","maxLength":14,"minLength":1,"title":"First Name","examples":["Ada"]},"last_name":{"type":"string","maxLength":16,"minLength":1,"title":"Last Name","examples":["Lovelace"]},"gender":{"type":"string","enum":["M","F"],"title":"Gender","examples":["F"]},"birth_date":{"type":"string","format":"date","title":"Birth Date","examples":["1990-12-10"]},"hire_date":{"type":"string","format":"date","title":"Hire Date","examples":["2024-03-01"]},"department_id":{"anyOf":[{"type":"string","pattern":"^d\\d{3}$"},{"type":"null"}],"title":"Department Id","description":"Optional: puts the new employee in this department","examples":["d005"]}},"additionalProperties":false,"type":"object","required":["first_name","last_name","gender","birth_date","hire_date"],"title":"EmployeeIn"},"EmployeePatch":{"properties":{"first_name":{"anyOf":[{"type":"string","maxLength":14,"minLength":1},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string","maxLength":16,"minLength":1},{"type":"null"}],"title":"Last Name"},"gender":{"anyOf":[{"type":"string","enum":["M","F"]},{"type":"null"}],"title":"Gender"},"birth_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Birth Date"},"hire_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Hire Date"}},"additionalProperties":false,"type":"object","title":"EmployeePatch"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SalaryIn":{"properties":{"amount":{"type":"integer","maximum":10000000.0,"exclusiveMinimum":0.0,"title":"Amount","examples":[65000]},"from_date":{"type":"string","format":"date","title":"From Date","examples":["2025-01-01"]},"to_date":{"type":"string","format":"date","title":"To Date","description":"Leave out for 'still current' (9999-01-01)","default":"9999-01-01","examples":["9999-01-01"]}},"additionalProperties":false,"type":"object","required":["amount","from_date"],"title":"SalaryIn"},"SalaryPatch":{"properties":{"amount":{"anyOf":[{"type":"integer","maximum":10000000.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"Amount","examples":[70000]},"to_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"To Date","examples":["2025-12-31"]}},"additionalProperties":false,"type":"object","title":"SalaryPatch"},"TitleIn":{"properties":{"title":{"type":"string","maxLength":50,"minLength":1,"title":"Title","examples":["Data Analyst"]},"from_date":{"type":"string","format":"date","title":"From Date","examples":["2025-01-01"]},"to_date":{"type":"string","format":"date","title":"To Date","description":"Leave out for 'still current' (9999-01-01)","default":"9999-01-01","examples":["9999-01-01"]}},"additionalProperties":false,"type":"object","required":["title","from_date"],"title":"TitleIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"Your class token. Send it as: Authorization: Bearer YOUR_TOKEN","scheme":"bearer"}}}}