Introduction

Planning & Scheduling API

Overview

Weekly scheduling: Directory people/sites, HR contract hours/availability/leave, Training eligibility snapshots, coverage demand, and planning runs. See docs/V1_SCHEDULING.md. Use X-Maya-Location-Id for the active site.

Integration guide: Planning & Scheduling service docs

OpenAPI v0.1.0 · source openapi/planning.json

OpenAPI 3.0.0 · v0.1.0 · 33 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/health"

Unauthenticated liveness probe. Does not verify D1 connectivity or JWT configuration.

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/health"

Unauthenticated liveness probe. Alias of GET /health.

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Settings

Planning configuration per Directory location and workforce member. Master data and HR contract terms (hours, pay) are not edited here.

get/v1/settings/locations

List location planning settings

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/settings/locations"

Directory syncs locations via internal ingest. This list shows planning fields (coordinates, operating hours, travel region) keyed by Directory `locationId`.

Operation ID: listLocationSettings

Parameters

Name	In	Type	Description
limit	query	integer	Page size (1–200). Defaults to 50.
offset	query	integer	Number of rows to skip. Defaults to 0.

Responses

200
Location settings
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/settings/locations/{id}

Get location planning settings

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/settings/locations/example-id"

Returns one location's planning fields. 404 NOT_FOUND if it does not exist in this organisation.

Operation ID: getLocationSettings

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Location settings
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/settings/locations/{id}

Update location planning settings

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/planning/v1/settings/locations/example-id"

Updates planning-only fields. Name and address come from Directory ingest. `admin` only.

Operation ID: patchLocationSettings

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Request body(required)

application/jsonLocationSettingsPatch

Responses

200
Updated location settings
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/settings/workforce

List workforce planning settings

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/settings/workforce"

People are synced from Directory ingest (home site lives on the Directory person, not here). Contract hours and pay come from HR (`contract` on each item); PATCH updates preferences only.

Operation ID: listWorkforceSettings

Parameters

Name	In	Type	Description
limit	query	integer	Page size (1–200). Defaults to 50.
offset	query	integer	Number of rows to skip. Defaults to 0.

Responses

200
Workforce settings
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/settings/workforce/{id}

Get workforce planning settings

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/settings/workforce/example-id"

Returns one person's planning preferences and solver caps. 404 NOT_FOUND if missing.

Operation ID: getWorkforceSettings

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Workforce settings
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/settings/workforce/{id}

Update workforce planning settings

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/planning/v1/settings/workforce/example-id"

Updates planning preferences only (locations and roles). Home location is Directory; all hour and pay fields are HR — use HR APIs to change contracts. `admin` only.

Operation ID: patchWorkforceSettings

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Request body(required)

application/jsonWorkforceSettingsPatch

Responses

200
Updated workforce settings
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Coverage shifts

Workstations and cover required: time-boxed staffing demand (not HR assigned shifts). `roleId` is a Training role id.

get/v1/shifts

List shifts

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/shifts"

Returns shifts in the organisation, filtered to granted locations. Paginated.

Operation ID: listShifts

Parameters

Name	In	Type	Description
limit	query	integer	Page size (1–200). Defaults to 50.
offset	query	integer	Number of rows to skip. Defaults to 0.
locationId	query	string (uuid)	When set, only return rows for this location.

Responses

200
Shifts in scope
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/shifts

Create a coverage shift

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  
}' \
  "https://api.mayawealth.co.uk/planning/v1/shifts"

Creates staffing demand for a time window (not an HR assigned shift). Provide `requiredRoles` or `demandProfile`. `admin` only.

Operation ID: createShift

Request body(required)

application/jsonobject

Responses

201
Created shift plus demandIds
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/shifts/{id}

Get a shift

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/shifts/example-id"

Returns shift metadata, parsed `requiredRoles` or `demandProfile`, and `demandIds`. Use `GET /v1/demand/{id}` for expanded demand detail. 403 if the location is out of scope.

Operation ID: getShift

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Shift with demandIds
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/shifts/{id}

Update a shift

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Dinner service (peak split)",
  "priority": "high",
  "demandProfile": [
    {
      "start": "2026-08-31T17:00:00.000Z",
      "end": "2026-08-31T19:00:00.000Z",
      "requiredRoles": [
        {
          "roleId": "0193f1a0-7c3b-71e8-92f1-99fd6edd4fd9",
          "count": 1,
          "station": "Grill"
        }
      ]
    },
    {
      "start": "2026-08-31T19:00:00.000Z",
      "end": "2026-08-31T21:00:00.000Z",
      "requiredRoles": [
        {
          "roleId": "0193f1a0-7c3b-71e8-92f1-99fd6edd4fe1",
          "count": 1,
          "station": "Till"
        }
      ]
    }
  ]
}' \
  "https://api.mayawealth.co.uk/planning/v1/shifts/example-id"

Partial update: send only fields to change. Omitted fields are left as-is; demand rows are rebuilt from the resulting shift definition. `admin` only.

Operation ID: patchShift

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Request body(required)

application/jsonobject

Responses

200
Updated shift plus new demandIds
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Demand

Staffing requirement rows the solver assigns (from coverage shifts or standalone create).

get/v1/demand

List demand

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/demand"

Returns demand rows in the organisation, filtered to granted locations. Paginated.

Operation ID: listDemand

Parameters

Name	In	Type	Description
limit	query	integer	Page size (1–200). Defaults to 50.
offset	query	integer	Number of rows to skip. Defaults to 0.
locationId	query	string (uuid)	When set, only return rows for this location.

Responses

200
Demand rows in scope
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/demand

Create standalone demand

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/planning/v1/demand"

Creates a staffing requirement that is not owned by a job or shift. `manager` may call this for granted locations. 403 FORBIDDEN if the location is out of scope.

Operation ID: createDemand

Request body(required)

application/jsonDemandCreate

Responses

201
Created demand
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/demand/{id}

Get demand

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/demand/example-id"

Returns one demand row with parsed JSON fields. 403 if the location is out of scope.

Operation ID: getDemand

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Demand
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

put/v1/demand/{id}

Update demand

Example request

curl -sS \
  -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Bruno cover slot (updated)",
  "priority": "high",
  "targetStaff": 2,
  "maxStaff": 3,
  "station": "Front of house"
}' \
  "https://api.mayawealth.co.uk/planning/v1/demand/example-id"

Updates a demand row and recomputes priority. `manager` may call this for granted locations. 403 if current or new location is out of scope.

Operation ID: updateDemand

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Request body(required)

application/jsonobject

Responses

200
Updated demand
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Eligibility

Eligibility snapshots from Training (or another compliance system). Planning never calls Training directly.

get/v1/eligibility/snapshots

List eligibility snapshots

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/eligibility/snapshots"

Returns the 20 most recent snapshots in the organisation, newest first.

Operation ID: listEligibilitySnapshots

Responses

200
Recent snapshots
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/eligibility/snapshots

Ingest an eligibility snapshot

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/planning/v1/eligibility/snapshots"

Stores a Training & Compliance eligibility matrix used as hard constraints by the solver. `workRequirementId` must match demand `eligibilityProfileId`. `admin` only.

Operation ID: ingestEligibilitySnapshot

Request body(required)

application/jsonEligibilityIngest

Responses

201
Created snapshot id and row count
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/eligibility/snapshots/{id}

Get an eligibility snapshot

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/eligibility/snapshots/example-id"

Returns a snapshot and its eligibility rows. 404 NOT_FOUND if missing.

Operation ID: getEligibilitySnapshot

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Snapshot with eligibility rows
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Planning

Generate, inspect, publish, rerun, and override schedules (rota).

get/v1/planning-runs

List planning runs

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs"

Returns the 50 most recent planning runs in the organisation, newest first.

Operation ID: listPlanningRuns

Responses

200
Planning runs
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/planning-runs

Generate a schedule

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs"

Runs the solver over demand in the horizon (or listed demandIds) and eligible users. Returns assignments, unassigned demand, score, and metrics. 400 PLANNING_FAILED if the solver errors. `admin`, `area-manager`, and `manager` may call this.

Operation ID: createPlanningRun

Request body(required)

application/jsonPlanningRunCreate

Responses

201
Completed plan with assignments and unassigned demand
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/planning-runs/{id}

Get a planning run

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id"

Returns run status, score, metrics, and solver metadata. 404 NOT_FOUND if missing.

Operation ID: getPlanningRun

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Planning run
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/planning-runs/{id}/assignments

List run assignments

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/assignments"

Returns assignments for a run with parsed explanations. Filtered to granted locations for `manager`.

Operation ID: listPlanningRunAssignments

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Assignments
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/planning-runs/{id}/unassigned

List unassigned demand

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/unassigned"

Returns demand the solver could not cover, with parsed `reasons`.

Operation ID: listPlanningRunUnassigned

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Unassigned demand
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/planning-runs/{id}/explanations

List run explanations

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/explanations"

Returns why-assigned and why-not rows (eligibility codes, rest, hours, travel). Used to explain the schedule.

Operation ID: listPlanningRunExplanations

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Explanations with codes and details
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/planning-runs/{id}/snapshot

Get run solver snapshot

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/snapshot"

Returns the hashed solver input payload used for this run. 404 if the snapshot is missing.

Operation ID: getPlanningRunSnapshot

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Snapshot id, contentHash, and payload
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/planning-runs/{id}/rerun

Rerun a plan from its snapshot

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/rerun"

Re-solves using the stored snapshot payload (same demand/users). Creates a new run with mode `rerun`. `admin` only.

Operation ID: rerunPlanningRun

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

201
New completed run
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/planning-runs/{id}/replan

Replan from current data

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/replan"

Rebuilds solver input from live demand, availability, and eligibility, then solves. Creates a new run with mode `replan`. `admin` only.

Operation ID: replanPlanningRun

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

201
New completed run
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/planning-runs/{id}/publish

Publish a planning run

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/publish"

Marks a completed run as the live schedule. `manager` and `admin` may call this. 404 if the run is missing.

Operation ID: publishPlanningRun

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Responses

200
Published run id and status
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/planning-runs/{id}/overrides

Apply a manual assignment override

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/planning/v1/planning-runs/example-id/overrides"

Pins a user to a demand row on this run. 400 if the assignment is invalid (eligibility, overlap, hours). `admin` only.

Operation ID: createPlanningRunOverride

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id within the caller's organisation.

Request body(required)

application/jsonOverrideCreate

Responses

201
Override assignment
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Audit

Mutation audit log.

get/v1/audit

List audit events

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/audit"

Returns the 100 most recent mutation audit records for the organisation.

Operation ID: listAuditEvents

Responses

200
Audit log
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Timesheets

Timesheet periods from HR attendance and shifts. Directory `userId` on each row.

get/v1/timesheets

Timesheet view from HR attendance and shifts

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/planning/v1/timesheets"

Aggregates HR time entries and shifts into daily rows. `userId` is the Directory user id. Data is read from HR via service binding.

Operation ID: listTimesheets

Parameters

Name	In	Type	Description
limit	query	integer	Page size (1–200). Defaults to 50.
offset	query	integer	Number of rows to skip. Defaults to 0.
userId	query	string (uuid)	Directory user id.
startDate	query	string	—
endDate	query	string	—

Responses

200
Timesheet rows
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/timesheets/approve

Approve a timesheet period

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/planning/v1/timesheets/approve"

Records a timesheet review in HR for the given Directory `userId` and date range.

Operation ID: approveTimesheet

Request body(required)

application/jsonTimesheetReviewRequest

Responses

200
Review record
application/json
400
Malformed JSON or solver failure. `error.code` is typically VALIDATION_ERROR or PLANNING_FAILED.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body/params or an override that violates a hard constraint.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json