API Reference
57 endpoints across 17 areas, generated from the OpenAPI 3.1 spec (v1.1.0). Authenticate with a Bearer API key (sk_live_* / sk_test_*). The machine spec is at /api/v1/openapi.json.
Getting started
- Create an API key in Settings → API keys (scoped, test or live).
- Send it as a Bearer token:
Authorization: Bearer sk_live_… - Every response carries a
X-Request-Id; errors follow a stable envelope (see the error-code reference). - Lists are cursor-paginated; AI endpoints are rate-limited to 10 req/min.
curl https://mellow-production.up.railway.app/api/v1/employees \ -H "Authorization: Bearer sk_live_…"
Absence
get/v1/absence/balancesList leave balances per employee
Responses: 200400401403429500
get/v1/absence/bank-holidaysList bank holidays for the organisation
Responses: 200400401403429500
get/v1/absence/calendarRetrieve the team absence calendar
Responses: 200400401403429500
Agents
get/v1/agentsList available AI agents
Responses: 200400401403429500
post/v1/agents/queryQuery a specific Mellow AI agent
Request body: JSON (required).
Responses: 200400401403429500
AI
post/v1/ai/queryAsk the Employee Assistant a question
Request body: JSON (required).
Responses: 200400401403429500
Compliance
get/v1/compliance/alertsList compliance alerts
Responses: 200400401403429500
get/v1/compliance/checksList compliance checks
Responses: 200400401403429500
get/v1/compliance/deadlinesList upcoming compliance deadlines
Responses: 200400401403429500
get/v1/compliance/policiesList company policies
Responses: 200400401403429500
get/v1/compliance/rtwList right-to-work checks
Responses: 200400401403429500
post/v1/compliance/rtwRecord a right-to-work check
Request body: JSON (required).
Responses: 201400401403429500
Contracts
post/v1/contracts/generateGenerate an employment contract
Request body: JSON (required).
Responses: 201400401403429500
Employees
get/v1/employeesList employees
Responses: 200400401403429500
post/v1/employeesCreate an employee
Request body: JSON (required).
Responses: 201400401403429500
get/v1/employees/{employeeId}Retrieve an employee
Parameters
employeeId(path, required, string)
Responses: 200400401403429500
patch/v1/employees/{employeeId}Update an employee
Parameters
employeeId(path, required, string)
Request body: JSON (required).
Responses: 200400401403429500
delete/v1/employees/{employeeId}Soft-delete an employee
Parameters
employeeId(path, required, string)
Responses: 200400401403429500
Leave
get/v1/employees/{employeeId}/leaveList an employee's leave requests
Parameters
employeeId(path, required, string)
Responses: 200400401403429500
get/v1/leaveList leave requests
Responses: 200400401403429500
post/v1/leaveCreate a leave request
Request body: JSON (required).
Responses: 201400401403429500
get/v1/leave/{leaveId}Retrieve a leave request
Parameters
leaveId(path, required, string)
Responses: 200400401403429500
patch/v1/leave/{leaveId}Update a leave request
Parameters
leaveId(path, required, string)
Request body: JSON (required).
Responses: 200400401403429500
delete/v1/leave/{leaveId}Cancel a leave request
Parameters
leaveId(path, required, string)
Responses: 200400401403429500
Onboarding
get/v1/onboardingList active onboardings
Responses: 200400401403429500
post/v1/onboarding/{onboardingId}/tasks/{taskId}/completeMark an onboarding task as complete
Parameters
onboardingId(path, required, string)taskId(path, required, string)
Request body: JSON (required).
Responses: 201400401403429500
post/v1/onboarding/startStart onboarding for a new starter
Request body: JSON (required).
Responses: 201400401403429500
get/v1/onboarding/templatesList onboarding templates
Responses: 200400401403429500
Organisation
get/v1/organisationRetrieve the calling organisation
Responses: 200400401403429500
get/v1/organisation/departmentsList departments
Responses: 200400401403429500
get/v1/organisation/locationsList organisation locations
Responses: 200400401403429500
Payroll
get/v1/pay-runsList pay runs
Responses: 200400401403429500
post/v1/pay-runsCreate a pay run
Request body: JSON (required).
Responses: 201400401403429500
get/v1/pay-runs/{payRunId}Retrieve a pay run
Parameters
payRunId(path, required, string)
Responses: 200400401403429500
post/v1/pay-runs/{payRunId}/approveApprove a pay run
Parameters
payRunId(path, required, string)
Responses: 200400401403429500
get/v1/pay-runs/{payRunId}/bacsGenerate the BACS Standard 18 file for a pay run (UK only)
Parameters
payRunId(path, required, string)
Responses: 200400401403429500
post/v1/pay-runs/{payRunId}/calculateTrigger calculation of a pay run
Parameters
payRunId(path, required, string)
Responses: 200400401403429500
get/v1/pay-runs/{payRunId}/payslipsList payslips for a pay run
Parameters
payRunId(path, required, string)
Responses: 200400401403429500
get/v1/pay-runs/{payRunId}/rti-statusRetrieve RTI submission status for a pay run (UK only)
Parameters
payRunId(path, required, string)
Responses: 200400401403429500
get/v1/pay-runs/{payRunId}/wpsGenerate the UAE WPS SIF file for a pay run (UAE only)
Parameters
payRunId(path, required, string)
Responses: 200400401403429500
Payslips
get/v1/employees/{employeeId}/payslipsList an employee's payslips
Parameters
employeeId(path, required, string)
Responses: 200400401403429500
get/v1/payslipsList payslips
Responses: 200400401403429500
Pensions
get/v1/pensionsList pension contributions
Responses: 200400401403429500
Performance
get/v1/performance/objectivesList performance objectives
Responses: 200400401403429500
get/v1/performance/reviewsList performance review cycles
Responses: 200400401403429500
Practice
get/v1/practiceRetrieve the practice for the authenticated key
Responses: 200400401403429500
get/v1/practice/clientsList the practice clients with stats
Responses: 200400401403429500
post/v1/practice/clientsAdd a client organisation to the practice
Request body: JSON (required).
Responses: 201400401403429500
get/v1/practice/complianceCompliance overview for every practice client
Responses: 200400401403429500
get/v1/practice/employeesList employees across all practice clients
Responses: 200400401403429500
get/v1/practice/payrollPayroll status for every practice client
Responses: 200400401403429500
Recruitment
get/v1/recruitment/applicationsList applications
Responses: 200400401403429500
get/v1/recruitment/vacanciesList vacancies
Responses: 200400401403429500
RTI
get/v1/rtiRetrieve RTI submission status
Responses: 200400401403429500
Time
post/v1/time/clock-inClock an employee in
Request body: JSON (required).
Responses: 201400401403429500
post/v1/time/clock-outClock an employee out
Request body: JSON (required).
Responses: 201400401403429500
get/v1/time/timesheetsList timesheets
Responses: 200400401403429500