{ "openapi": "3.1.0", "info": { "title": "ShiftForest Sync API", "version": "2.34.0", "description": "Scoped workforce API. Independent integrations have immutable reviewed permissions and optional workplace restrictions, finite rotating keys and discovery through /organization and /capabilities. Creator-bound legacy keys retain only their supported older workflows. New attendance history, leave, credential and payroll reads require explicit independent-integration scopes or an active administrator session. General write receipts last 24 hours; existing-resource writes require If-Match. The shift payload feed remains available; /sync/checkpoint and /sync/changes add minimal invalidations across ten supported resources. Visibility changes require a replica reset. Resource pages exclude later insertions but existing records remain live. Payroll exports contain reviewed basic-hourly snapshots, not tax calculations or provider certification. Human sessions may select an active company membership with X-ShiftForest-Workspace. An omitted selector uses the active canonical primary membership or sole active membership; ambiguous or unauthorized choices fail closed. API keys reject this header because their workspace is fixed. Workforce IDs and permissions belong to the selected membership; Auth account IDs are not workforce IDs. Privacy case management, reviewed policy/holds and bounded personal exports require human sessions; no general HR erasure or external-copy recall is advertised. Approved entitlement accounts use hours or policy days, effective work patterns and captured charges. No statutory formula or automatic accrual is assumed. Calendar leave coverage is separate from entitlement deductions. Human-reviewed staffing evidence packs freeze redacted records with explicit historical gaps; they do not certify regulatory compliance. Custom-time leave uses integer local minutes and rejects ambiguous or nonexistent timezone-transition endpoints. Requesters may withdraw their own pending leave through a reviewed command; approved leave still requires manager cancellation. Native private workforce files use human sessions, immutable versions, quarantine scanning and authenticated attachment downloads. API keys cannot access private files. Uploads require commissioned storage/scanning and an owner-approved document retention policy; availability is exposed separately from API capability. Electronic signatures remain unsupported." }, "servers": [ { "url": "https://api.shiftforest.com/v2" } ], "security": [ { "Bearer": [] } ], "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "WorkerProfileChanges": { "type": "object", "additionalProperties": false, "required": [], "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "hourly_rate_minor": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "weekly_hours": { "type": "number", "exclusiveMinimum": 0, "maximum": 168, "multipleOf": 0.01 }, "default_role": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "locations": { "type": "array", "minItems": 1, "maxItems": 1000, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "employee_code": { "type": "string", "minLength": 1, "maxLength": 100 } }, "minProperties": 1 }, "WorkerProfile": { "type": "object", "additionalProperties": false, "required": [ "first_name", "last_name", "hourly_rate_minor", "weekly_hours", "default_role", "locations", "email" ], "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "hourly_rate_minor": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "weekly_hours": { "type": "number", "exclusiveMinimum": 0, "maximum": 168, "multipleOf": 0.01 }, "default_role": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "locations": { "type": "array", "minItems": 1, "maxItems": 1000, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "employee_code": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 } } }, "WorkerProfileReview": { "type": "object", "additionalProperties": false, "required": [ "request_id", "operation", "user", "version", "changes", "workplaces", "job_role", "review_token" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "operation": { "enum": [ "create", "profile" ] }, "user": { "type": [ "integer", "null" ], "minimum": 1 }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changes": { "oneOf": [ { "$ref": "#/components/schemas/WorkerProfile" }, { "$ref": "#/components/schemas/WorkerProfileChanges" } ] }, "workplaces": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "name": { "type": "string" }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } } }, "job_role": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "name": { "type": "string" }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "WorkerCreated": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "workforce_id", "login_enabled", "created" ], "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workforce_id": { "type": "string", "format": "uuid" }, "login_enabled": { "const": false }, "created": { "const": true } } }, "WorkerUpdated": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "updated" ], "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "updated": { "const": true } } }, "Shift": { "type": "object", "required": [ "id", "version", "external_ids", "start_time", "end_time", "start_time_unix", "end_time_unix", "deleted", "published", "open", "user", "location", "role", "shift_type", "rota_date" ], "properties": { "id": { "type": [ "integer", "null" ] }, "user": { "type": [ "integer", "null" ] }, "location": { "type": [ "integer", "null" ] }, "role": { "type": [ "integer", "null" ] }, "version": { "type": [ "integer", "null" ] }, "minutes_break": { "type": [ "integer", "null" ] }, "duration_minutes": { "type": [ "number", "null" ] }, "disturbed_minutes": { "type": [ "integer", "null" ] }, "deleted": { "type": "boolean" }, "published": { "type": "boolean" }, "open": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "claimed": { "type": "boolean" }, "shift_type": { "type": [ "string", "null" ] }, "shift_category": { "type": [ "string", "null" ] }, "type_source": { "type": [ "string", "null" ] }, "rota_date": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 }, "start_time": { "type": [ "string", "null" ], "format": "date-time" }, "start_time_unix": { "type": [ "number", "null" ] }, "end_time": { "type": [ "string", "null" ], "format": "date-time" }, "end_time_unix": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at_unix": { "type": [ "number", "null" ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at_unix": { "type": [ "number", "null" ] }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at_unix": { "type": [ "number", "null" ] }, "claimed_at": { "type": [ "string", "null" ], "format": "date-time" }, "claimed_at_unix": { "type": [ "number", "null" ] }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_at_unix": { "type": [ "number", "null" ] }, "type_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "type_reviewed_at_unix": { "type": [ "number", "null" ] }, "lifecycle_state": { "type": "string", "enum": [ "draft", "published", "acknowledged", "clocked_in", "clocked_out", "approved", "cancelled" ] }, "attendance_method": { "type": [ "string", "null" ], "enum": [ "qr", "nfc", "geofence", "manager", "legacy", null ] }, "clocked_in_at": { "type": [ "string", "null" ], "format": "date-time" }, "clocked_in_at_unix": { "type": [ "number", "null" ] }, "clocked_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "clocked_out_at_unix": { "type": [ "number", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "approved_at_unix": { "type": [ "number", "null" ] }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at_unix": { "type": [ "number", "null" ] }, "handover": { "type": "object", "properties": { "outgoing_shift_id": { "type": "integer" }, "required_minutes": { "type": "integer" }, "starts_at": { "type": "string", "format": "date-time" }, "starts_at_unix": { "type": "integer" }, "ends_at": { "type": "string", "format": "date-time" }, "ends_at_unix": { "type": "integer" } } } } }, "Change": { "type": "object", "required": [ "event_id", "sequence", "occurred_at", "occurred_at_unix", "change_type", "shift", "version" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "occurred_at_unix": { "type": "number" }, "change_type": { "type": "string" }, "shift": { "oneOf": [ { "$ref": "#/components/schemas/Shift" }, { "$ref": "#/components/schemas/ShiftAccessRemoval" } ] }, "version": { "type": "integer", "minimum": 1 } } }, "RotaValidation": { "type": "object", "properties": { "valid": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "timezone": { "type": "string" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "findings": { "type": "array", "items": { "type": "object", "required": [ "code", "severity", "message", "details" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "block", "warn" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "reviewed_shifts": { "type": "array", "maxItems": 1000, "items": { "type": "object", "required": [ "id", "version" ], "additionalProperties": false, "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 } } } }, "draft_count": { "type": "integer", "minimum": 0, "maximum": 1000 } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "AvailabilityInterval": { "type": "object", "additionalProperties": false, "required": [ "status", "start_time", "end_time" ], "properties": { "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "start_time": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\\.[0-9]{1,6})?)?$" }, "end_time": { "type": "string", "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\\.[0-9]{1,6})?)?|24:00)$" } } }, "AvailabilityDay": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "user", "date", "timezone", "intervals", "pattern_id" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "user": { "type": "integer", "minimum": 1 }, "date": { "type": "string", "format": "date" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone captured for this date; defaults to the company timezone on creation." }, "intervals": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/AvailabilityInterval" }, "description": "Complete replacement, sorted server-side. Non-overlapping local wall-clock ranges; midnight is 24:00. Split overnight ranges across dates. Both occurrences of repeated DST clock times apply; nonexistent boundary times are rejected." }, "pattern_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Member-created pattern identity, read-only. Editing this date detaches it from the pattern." } } }, "ShiftRequest": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "shift", "requested_by", "target_shift", "target_user", "kind", "status", "resolution", "message", "response_message", "created_at", "accepted_at", "reviewed_at", "reviewed_by", "reviewed_by_integration" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "shift": { "type": "integer", "minimum": 1 }, "requested_by": { "type": "integer", "minimum": 1 }, "target_shift": { "type": [ "integer", "null" ], "minimum": 1 }, "target_user": { "type": [ "integer", "null" ], "minimum": 1 }, "kind": { "enum": [ "drop", "swap" ] }, "status": { "enum": [ "pending", "accepted", "approved", "denied" ] }, "resolution": { "enum": [ null, "cancelled", "declined", "denied", "approved" ] }, "message": { "type": "string", "maxLength": 2000 }, "response_message": { "type": "string", "maxLength": 2000 }, "created_at": { "type": "string", "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "reviewed_by": { "type": [ "integer", "null" ], "minimum": 1 }, "reviewed_by_integration": { "type": [ "string", "null" ], "format": "uuid", "description": "Independent integration identity that approved or denied the request. Human reviewed_by is null for this action; no employee is impersonated." } } }, "RequestShiftSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "user", "location", "start_time", "end_time", "shift_type", "rota_date", "timezone" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "user": { "type": [ "integer", "null" ], "minimum": 1 }, "location": { "type": "integer", "minimum": 1 }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "shift_type": { "type": "string" }, "rota_date": { "type": [ "string", "null" ], "format": "date" }, "timezone": { "type": [ "string", "null" ] } } }, "RequestCreationContext": { "type": "object", "additionalProperties": false, "required": [ "source", "target", "review_token" ], "properties": { "source": { "$ref": "#/components/schemas/RequestShiftSummary" }, "target": { "anyOf": [ { "$ref": "#/components/schemas/RequestShiftSummary" }, { "type": "null" } ] }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "RequestReviewContext": { "type": "object", "additionalProperties": false, "required": [ "request", "source", "target", "review_token", "actions", "consent_current" ], "properties": { "source": { "$ref": "#/components/schemas/RequestShiftSummary" }, "target": { "anyOf": [ { "$ref": "#/components/schemas/RequestShiftSummary" }, { "type": "null" } ] }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "request": { "$ref": "#/components/schemas/ShiftRequest" }, "actions": { "type": "array", "items": { "enum": [ "accepted", "approved", "denied" ] }, "uniqueItems": true }, "consent_current": { "type": "boolean" } } }, "RotaPublication": { "type": "object", "additionalProperties": false, "required": [ "published", "count", "validation" ], "properties": { "published": { "type": "boolean" }, "count": { "type": "integer", "minimum": 0 }, "validation": { "$ref": "#/components/schemas/RotaValidation" } } }, "RotaReviewedValidation": { "allOf": [ { "$ref": "#/components/schemas/RotaValidation" }, { "type": "object", "required": [ "review_token", "reviewed_shifts", "draft_count" ], "properties": { "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "reviewed_shifts": { "type": "array", "maxItems": 1000, "items": { "type": "object", "required": [ "id", "version" ], "additionalProperties": false, "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 } } } }, "draft_count": { "type": "integer", "minimum": 0, "maximum": 1000 } } } ] }, "ShiftAccessRemoval": { "type": "object", "required": [ "id", "version", "deleted" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "deleted": { "const": true } }, "additionalProperties": false, "description": "Redacted removal from a workplace-scoped integration replica. The workforce shift may still exist at a workplace this integration cannot access. Remove it from active views and replace the saved payload with this minimal tombstone; no new workplace or employee details are disclosed." }, "AttendanceRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "user", "shift", "location", "clock_in", "clock_out", "break_seconds", "break_started_at", "approval_status", "voided", "attendance_method", "verification_status", "network_verified", "clock_out_verification" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "user": { "type": "integer", "minimum": 1 }, "shift": { "type": [ "integer", "null" ], "minimum": 1 }, "location": { "type": [ "integer", "null" ], "minimum": 1 }, "clock_in": { "type": "string", "format": "date-time" }, "clock_out": { "type": [ "string", "null" ], "format": "date-time" }, "break_seconds": { "type": "string", "pattern": "^[0-9]+$" }, "break_started_at": { "type": [ "string", "null" ], "format": "date-time" }, "approval_status": { "type": "string" }, "voided": { "type": "boolean" }, "attendance_method": { "type": [ "string", "null" ], "enum": [ "qr", "nfc", "geofence", "manager", "legacy", null ] }, "verification_status": { "type": "string" }, "network_verified": { "type": "boolean" }, "clock_out_verification": { "type": [ "string", "null" ], "enum": [ "qr_wifi", "manual", "legacy", null ] } } }, "LeaveRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "user", "from_date", "to_date", "type", "status", "created_at", "start_minute", "end_minute", "timezone", "absence_start", "absence_end" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "user": { "type": "integer", "minimum": 1 }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "type": { "type": "string", "enum": [ "holiday", "sickness", "toil", "additional" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "denied" ] }, "created_at": { "type": "string", "format": "date-time" }, "start_minute": { "type": "integer", "minimum": 0, "maximum": 1439, "description": "Local minute on the boundary date; end1440 is the next midnight. Repeated or nonexistent local times are rejected." }, "end_minute": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "Local minute on the boundary date; end1440 is the next midnight. Repeated or nonexistent local times are rejected." }, "timezone": { "type": "string" }, "absence_start": { "type": "string", "format": "date-time" }, "absence_end": { "type": "string", "format": "date-time" }, "withdrawn_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Non-null means the requester withdrew their pending request. Status remains denied for backwards compatibility. May be absent on older command receipts." } } }, "CredentialRecord": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "user", "kind", "status", "expires_on", "deadline", "verified_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "user": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "enum": [ "dbs", "level3", "first_aid", "medication", "driving", "restraint" ] }, "status": { "type": "string", "enum": [ "valid", "in_progress", "expired", "missing" ] }, "expires_on": { "type": [ "string", "null" ], "format": "date" }, "deadline": { "type": [ "string", "null" ], "format": "date" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PayrollExport": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "from_date", "to_date", "currency", "created_at", "total_minor", "line_count", "policy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "const": 1 }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "total_minor": { "type": "string", "pattern": "^-?[0-9]+$" }, "line_count": { "type": "integer", "minimum": 0 }, "policy": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "timezone", "breaks_paid", "round_minutes", "rate_boundary", "rounding", "coverage" ], "properties": { "timezone": { "type": "string" }, "breaks_paid": { "type": "boolean" }, "round_minutes": { "type": "integer", "minimum": 0 }, "rate_boundary": { "type": "string" }, "rounding": { "type": "string" }, "coverage": { "type": "string" } } }, { "$ref": "#/components/schemas/PayrollComponentPolicy" } ] } } }, "PayrollExportLine": { "type": "object", "additionalProperties": false, "required": [ "index", "user", "attendance", "employee_code", "date", "pay_code", "minutes", "rate_minor", "amount_minor", "currency", "clock_in", "clock_out" ], "properties": { "index": { "type": "integer", "minimum": 1 }, "user": { "type": [ "integer", "null" ], "minimum": 1 }, "attendance": { "type": [ "integer", "null" ], "minimum": 1 }, "employee_code": { "type": "string" }, "date": { "type": "string", "format": "date" }, "pay_code": { "type": "string" }, "minutes": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "rate_minor": { "type": "integer", "minimum": 0 }, "amount_minor": { "type": "string", "pattern": "^-?[0-9]+$" }, "currency": { "type": "string" }, "clock_in": { "type": "string", "format": "date-time" }, "clock_out": { "type": "string", "format": "date-time" }, "unit": { "type": "string", "enum": [ "hour", "shift" ] }, "multiplier_bps": { "type": "integer", "minimum": 10000, "maximum": 50000 }, "duration_us": { "type": "string", "pattern": "^[0-9]+$" }, "workplace": { "oneOf": [ { "type": "null" }, { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } ] }, "policy_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "policy_revision": { "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] } } }, "ResourceChange": { "type": "object", "additionalProperties": false, "required": [ "sequence", "resource", "id", "action", "occurred_at" ], "properties": { "sequence": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "resource": { "type": "string", "enum": [ "shifts", "users", "locations", "roles", "availability", "shift-requests", "attendance", "leave", "credentials", "payroll-exports" ] }, "id": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "format": "uuid" } ] }, "action": { "type": "string", "enum": [ "refresh", "remove" ] }, "occurred_at": { "type": "string", "format": "date-time" } } }, "RecoveryShift": { "type": "object", "additionalProperties": false, "required": [ "id", "user_id", "location_id", "start_time", "end_time", "shift_type", "type_source", "row_revision", "rota_date", "rota_timezone", "cancelled_at" ], "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "user_id": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9007199254740991 }, "location_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "shift_type": { "type": "string" }, "type_source": { "type": "string" }, "row_revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "rota_date": { "type": "string", "format": "date" }, "rota_timezone": { "type": "string" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "RecoveryCandidate": { "type": "object", "additionalProperties": false, "required": [ "worker_id", "worker_name", "worker_kind", "eligible", "reasons", "review_token", "remaining_findings" ], "properties": { "worker_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "worker_name": { "type": "string" }, "worker_kind": { "enum": [ "employee", "bank", "agency" ] }, "eligible": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "remaining_findings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "severity", "message" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": "string" } } } } } }, "RecoveryCandidates": { "type": "object", "additionalProperties": false, "required": [ "shift", "items", "next_cursor", "active_campaign" ], "properties": { "shift": { "$ref": "#/components/schemas/RecoveryShift" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecoveryCandidate" } }, "next_cursor": { "type": [ "string", "null" ] }, "active_campaign": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] } } }, "RecoveryPreparation": { "type": "object", "additionalProperties": false, "required": [ "shift", "stage", "recipients", "expires_at" ], "properties": { "shift": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "stage": { "enum": [ "internal", "bank", "agency" ] }, "recipients": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "expires_at": { "type": "string", "format": "date-time" } } }, "RecoveryLaunchReview": { "type": "object", "additionalProperties": false, "required": [ "shift", "stage", "recipients", "expires_at", "can_launch", "review_token" ], "properties": { "shift": { "$ref": "#/components/schemas/RecoveryShift" }, "stage": { "enum": [ "internal", "bank", "agency" ] }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecoveryCandidate" } }, "expires_at": { "type": "string", "format": "date-time" }, "can_launch": { "type": "boolean" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "RecoveryOffer": { "type": "object", "additionalProperties": false, "required": [ "id", "campaign_id", "offer_status", "campaign_status", "expires_at", "stage", "shift", "workplace_name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "offer_status": { "enum": [ "pending", "accepted", "declined", "closed" ] }, "campaign_status": { "enum": [ "open", "filled", "cancelled", "expired" ] }, "expires_at": { "type": "string", "format": "date-time" }, "stage": { "enum": [ "internal", "bank", "agency" ] }, "shift": { "$ref": "#/components/schemas/RecoveryShift" }, "workplace_name": { "type": "string" } } }, "RecoveryOfferReview": { "type": "object", "additionalProperties": false, "required": [ "id", "campaign_id", "offer_status", "campaign_status", "expires_at", "stage", "shift", "workplace_name", "actions", "unavailable_reasons", "review_token" ], "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "offer_status": { "enum": [ "pending", "accepted", "declined", "closed" ] }, "campaign_status": { "enum": [ "open", "filled", "cancelled", "expired" ] }, "expires_at": { "type": "string", "format": "date-time" }, "stage": { "enum": [ "internal", "bank", "agency" ] }, "shift": { "$ref": "#/components/schemas/RecoveryShift" }, "workplace_name": { "type": "string" }, "actions": { "type": "array", "items": { "enum": [ "accept", "decline" ] } }, "unavailable_reasons": { "type": "array", "items": { "type": "string" } }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "RecoveryOffers": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecoveryOffer" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "RecoveryCampaign": { "type": "object", "additionalProperties": false, "required": [ "id", "shift", "stage", "status", "revision", "expires_at", "created_at", "winner_id", "reason", "review_token", "offers" ], "properties": { "id": { "type": "string", "format": "uuid" }, "shift": { "$ref": "#/components/schemas/RecoveryShift" }, "stage": { "enum": [ "internal", "bank", "agency" ] }, "status": { "enum": [ "open", "filled", "cancelled", "expired" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "winner_id": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9007199254740991 }, "reason": { "type": "string" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "offers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "worker_id", "worker_name", "status", "responded_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "worker_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "worker_name": { "type": "string" }, "status": { "enum": [ "pending", "accepted", "declined", "closed" ] }, "responded_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "RecoveryStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "shift_id", "location_id", "stage", "status", "expires_at", "created_at", "completed_at", "winner_id", "offer_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "shift_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "location_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "stage": { "enum": [ "internal", "bank", "agency" ] }, "status": { "enum": [ "open", "filled", "cancelled", "expired" ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "winner_id": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9007199254740991 }, "offer_count": { "type": "integer", "minimum": 1, "maximum": 20 } } }, "RecoveryStatusPage": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecoveryStatus" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "RecoveryLaunched": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "offer_count", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "open" }, "offer_count": { "type": "integer", "minimum": 1, "maximum": 20 }, "expires_at": { "type": "string", "format": "date-time" } } }, "RecoveryResponded": { "type": "object", "additionalProperties": false, "required": [ "id", "campaign_id", "action", "shift_id", "completed_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "accept", "decline" ] }, "shift_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "completed_at": { "type": "string", "format": "date-time" } } }, "RecoveryCancelled": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "completed_at", "reason" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "cancelled" }, "completed_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } } }, "RecoveryLaunchCommand": { "type": "object", "additionalProperties": false, "required": [ "shift", "stage", "recipients", "expires_at", "request_id", "review_token", "reason" ], "properties": { "shift": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "stage": { "enum": [ "internal", "bank", "agency" ] }, "recipients": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "expires_at": { "type": "string", "format": "date-time" }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } } }, "RecoveryResponseCommand": { "type": "object", "additionalProperties": false, "required": [ "request_id", "review_token" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "RecoveryCancelCommand": { "type": "object", "additionalProperties": false, "required": [ "request_id", "review_token", "reason" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } } }, "SimulationSummary": { "type": "object", "additionalProperties": false, "required": [ "blocking", "warnings", "total", "by_rule", "findings", "findings_truncated" ], "properties": { "blocking": { "type": "integer", "minimum": 0 }, "warnings": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "by_rule": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "severity", "count" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } } } }, "findings": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "code", "severity", "message" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": "string" } } } }, "findings_truncated": { "type": "boolean" } } }, "StaffingSimulation": { "type": "object", "additionalProperties": false, "required": [ "version", "read_only", "shift", "evaluated_at", "snapshot_token", "policy_confirmed", "checks_enabled", "rules", "active_campaign", "assumptions", "baseline", "alternatives" ], "properties": { "version": { "enum": [ 1 ] }, "read_only": { "enum": [ true ] }, "shift": { "$ref": "#/components/schemas/RecoveryShift" }, "evaluated_at": { "type": "string", "format": "date-time" }, "snapshot_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "policy_confirmed": { "type": "boolean" }, "checks_enabled": { "type": "boolean" }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "severity" ], "properties": { "code": { "type": "string" }, "severity": { "type": "string" } } } }, "active_campaign": { "type": [ "string", "null" ], "format": "uuid" }, "assumptions": { "type": "array", "items": { "type": "string" } }, "baseline": { "$ref": "#/components/schemas/SimulationSummary" }, "alternatives": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "additionalProperties": false, "required": [ "worker_id", "worker_name", "worker_kind", "eligible", "reasons", "evaluated", "proposed", "improved_blocking_findings", "worsened_blocking_findings" ], "properties": { "worker_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "worker_name": { "type": "string" }, "worker_kind": { "enum": [ "employee", "bank", "agency" ] }, "eligible": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "evaluated": { "type": "boolean" }, "proposed": { "anyOf": [ { "$ref": "#/components/schemas/SimulationSummary" }, { "type": "null" } ] }, "improved_blocking_findings": { "type": [ "integer", "null" ], "minimum": 0 }, "worsened_blocking_findings": { "type": [ "integer", "null" ], "minimum": 0 } } } } } }, "PrivacyCase": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "enum": [ "subject", "administrator" ] }, "kind": { "enum": [ "access", "correction", "erasure", "restriction", "objection", "portability" ] }, "status": { "enum": [ "open", "in_review", "awaiting_subject", "fulfilled", "partially_fulfilled", "denied", "withdrawn" ] }, "revision": { "type": "integer", "minimum": 1 }, "subject_id": { "type": "integer", "minimum": 1 }, "subject_name": { "type": "string" }, "is_mine": { "type": "boolean" }, "assigned": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "closed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "source", "kind", "status", "revision", "subject_id", "subject_name", "is_mine", "assigned", "created_at", "updated_at", "closed_at", "due_at" ], "additionalProperties": false }, "PrivacyCases": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyCase" } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192 }, { "type": "null" } ] }, "automatic_erasure_enabled": { "const": false } }, "required": [ "items", "next_cursor", "automatic_erasure_enabled" ], "additionalProperties": false }, "PrivacyEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9]+$" }, "action": { "type": "string" }, "message": { "type": "string" }, "by_subject": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" }, "completion_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "action", "message", "by_subject", "occurred_at", "completion_reference" ], "additionalProperties": false }, "PrivacyCaseDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "enum": [ "subject", "administrator" ] }, "kind": { "enum": [ "access", "correction", "erasure", "restriction", "objection", "portability" ] }, "status": { "enum": [ "open", "in_review", "awaiting_subject", "fulfilled", "partially_fulfilled", "denied", "withdrawn" ] }, "revision": { "type": "integer", "minimum": 1 }, "subject_id": { "type": "integer", "minimum": 1 }, "subject_name": { "type": "string" }, "is_mine": { "type": "boolean" }, "assigned": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "closed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "message": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyEvent" } }, "next_event_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192 }, { "type": "null" } ] }, "fulfilment_source": { "enum": [ "administrator_recorded", null ] } }, "required": [ "id", "source", "kind", "status", "revision", "subject_id", "subject_name", "is_mine", "assigned", "created_at", "updated_at", "closed_at", "due_at", "message", "events", "next_event_cursor", "fulfilment_source" ], "additionalProperties": false }, "PrivacyCaseReview": { "type": "object", "properties": { "case": { "$ref": "#/components/schemas/PrivacyCase" }, "action": { "enum": [ "reply", "withdraw", "in_review", "awaiting_subject", "fulfilled", "partially_fulfilled", "denied" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "due_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completion_reference": { "anyOf": [ { "type": "string", "minLength": 10, "maxLength": 1000 }, { "type": "null" } ] }, "automatic_data_change": { "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "case", "action", "message", "due_at", "completion_reference", "automatic_data_change", "review_token" ], "additionalProperties": false }, "PrivacySubject": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "email": { "type": "string" }, "employee_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "login_enabled": { "type": "boolean" } }, "required": [ "id", "name", "email", "employee_code", "login_enabled" ], "additionalProperties": false }, "PrivacySubjects": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacySubject" } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192 }, { "type": "null" } ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "PrivacyIntakeReview": { "type": "object", "properties": { "subject_id": { "type": "integer", "minimum": 1 }, "subject_name": { "type": "string" }, "kind": { "enum": [ "access", "correction", "erasure", "restriction", "objection", "portability" ] }, "message": { "type": "string" }, "identity_reference": { "type": "string" }, "source": { "const": "administrator" }, "changes_identity": { "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "subject_id", "subject_name", "kind", "message", "identity_reference", "source", "changes_identity", "review_token" ], "additionalProperties": false }, "PrivacyPolicyInput": { "type": "object", "properties": { "category": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "anchor": { "enum": [ "event_at", "offboarded_at", "export_created_at" ] }, "policy_reference": { "type": "string", "minLength": 10, "maxLength": 1000 }, "rationale": { "type": "string", "minLength": 10, "maxLength": 2000 } }, "required": [ "category", "retention_days", "anchor", "policy_reference", "rationale" ], "additionalProperties": false }, "PrivacyPolicyCurrent": { "type": "object", "properties": { "category": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "anchor": { "enum": [ "event_at", "offboarded_at", "export_created_at" ] }, "policy_reference": { "type": "string", "minLength": 10, "maxLength": 1000 }, "rationale": { "type": "string", "minLength": 10, "maxLength": 2000 }, "revision": { "type": "integer", "minimum": 1 }, "approved_at": { "type": "string", "format": "date-time" } }, "required": [ "category", "retention_days", "anchor", "policy_reference", "rationale", "revision", "approved_at" ], "additionalProperties": false }, "PrivacyPolicy": { "type": "object", "properties": { "category": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "anchor": { "enum": [ "event_at", "offboarded_at", "export_created_at" ] }, "policy_reference": { "type": "string", "minLength": 10, "maxLength": 1000 }, "rationale": { "type": "string", "minLength": 10, "maxLength": 2000 }, "revision": { "type": "integer", "minimum": 1 }, "approved_at": { "type": "string", "format": "date-time" }, "approved_by": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] } }, "required": [ "category", "retention_days", "anchor", "policy_reference", "rationale", "revision", "approved_at", "approved_by" ], "additionalProperties": false }, "PrivacyPolicyReview": { "type": "object", "properties": { "current": { "anyOf": [ { "$ref": "#/components/schemas/PrivacyPolicyCurrent" }, { "type": "null" } ] }, "proposed": { "$ref": "#/components/schemas/PrivacyPolicyInput" }, "automatic_erasure_enabled": { "type": "boolean" }, "owner_approval_required": { "const": true }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "current", "proposed", "automatic_erasure_enabled", "owner_approval_required", "review_token" ], "additionalProperties": false }, "PrivacyPolicyApproved": { "type": "object", "properties": { "category": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "revision": { "type": "integer", "minimum": 1 }, "automatic_erasure_enabled": { "type": "boolean" } }, "required": [ "category", "revision", "automatic_erasure_enabled" ], "additionalProperties": false }, "PrivacyHoldStored": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject_id": { "type": "integer", "minimum": 1 }, "categories": { "type": "array", "items": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "minItems": 1, "maxItems": 12, "uniqueItems": true }, "reason": { "type": "string" }, "created_by": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 1 }, "released_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "released_by": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "release_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "subject_id", "categories", "reason", "created_by", "created_at", "revision", "released_at", "released_by", "release_reason" ], "additionalProperties": false }, "PrivacyHold": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject_id": { "type": "integer", "minimum": 1 }, "categories": { "type": "array", "items": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "minItems": 1, "maxItems": 12, "uniqueItems": true }, "reason": { "type": "string" }, "created_by": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 1 }, "released_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "released_by": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "release_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subject_name": { "type": "string" } }, "required": [ "id", "subject_id", "categories", "reason", "created_by", "created_at", "revision", "released_at", "released_by", "release_reason", "subject_name" ], "additionalProperties": false }, "PrivacyHoldReview": { "type": "object", "properties": { "action": { "enum": [ "place", "release" ] }, "hold_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": "integer", "minimum": 1 }, "subject_name": { "type": "string" }, "categories": { "type": "array", "items": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "minItems": 1, "maxItems": 12, "uniqueItems": true }, "reason": { "type": "string" }, "current": { "anyOf": [ { "$ref": "#/components/schemas/PrivacyHoldStored" }, { "type": "null" } ] }, "automatic_expiry": { "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "action", "hold_id", "subject_id", "subject_name", "categories", "reason", "current", "automatic_expiry", "review_token" ], "additionalProperties": false }, "PrivacyHoldChanged": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "active": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "active", "revision" ], "additionalProperties": false }, "PrivacyGovernance": { "type": "object", "properties": { "categories": { "type": "array", "items": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyPolicy" } }, "holds": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyHold" } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192 }, { "type": "null" } ] }, "can_approve_policy": { "type": "boolean" }, "automatic_erasure_enabled": { "type": "boolean" }, "export_purge_enabled": { "type": "boolean" } }, "required": [ "categories", "policies", "holds", "next_cursor", "can_approve_policy", "automatic_erasure_enabled", "export_purge_enabled" ], "additionalProperties": false }, "PrivacyExportPolicy": { "type": "object", "properties": { "category": { "const": "exports" }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "anchor": { "const": "export_created_at" }, "policy_reference": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "approved_at": { "type": "string", "format": "date-time" } }, "required": [ "category", "retention_days", "anchor", "policy_reference", "revision", "approved_at" ], "additionalProperties": false }, "PrivacyExportReview": { "type": "object", "properties": { "case_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": "integer", "minimum": 1 }, "subject_name": { "type": "string" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "omissions": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "array", "items": { "type": "string" } }, "retention_policy": { "$ref": "#/components/schemas/PrivacyExportPolicy" }, "closes_request": { "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "case_id", "subject_id", "subject_name", "from_date", "to_date", "timezone", "expires_at", "counts", "omissions", "coverage", "retention_policy", "closes_request", "review_token" ], "additionalProperties": false }, "PrivacyExportCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "expires_at": { "type": "string", "format": "date-time" }, "closes_request": { "const": false } }, "required": [ "id", "case_id", "sha256", "bytes", "expires_at", "closes_request" ], "additionalProperties": false }, "PrivacyExport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "revision": { "type": "integer", "minimum": 1 }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "purged_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "available": { "type": "boolean" }, "retention_policy": { "$ref": "#/components/schemas/PrivacyExportPolicy" } }, "required": [ "id", "case_id", "from_date", "to_date", "created_at", "expires_at", "sha256", "bytes", "counts", "revision", "revoked_at", "purged_at", "available", "retention_policy" ], "additionalProperties": false }, "PrivacyExports": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyExport" } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192 }, { "type": "null" } ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "PrivacyExportDownload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "canonical_json": { "type": "string", "maxLength": 8388608 }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "organization_id", "sha256", "bytes", "canonical_json", "expires_at" ], "additionalProperties": false }, "PrivacyExportRevoked": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "const": true }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "revoked", "revision" ], "additionalProperties": false }, "LeaveWorkInterval": { "type": "object", "properties": { "from": { "type": "integer", "minimum": 0, "maximum": 1439 }, "to": { "type": "integer", "minimum": 1, "maximum": 1440 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 24 } }, "required": [ "from", "to", "quantity" ], "additionalProperties": false }, "LeaveWorkPattern": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "week": { "type": "array", "minItems": 7, "maxItems": 7, "items": { "type": "array", "maxItems": 4, "items": { "$ref": "#/components/schemas/LeaveWorkInterval" } } } }, "required": [ "from", "week" ], "additionalProperties": false }, "LeaveEntitlementPolicy": { "type": "object", "properties": { "subject_id": { "type": "integer", "minimum": 1 }, "kind": { "enum": [ "holiday", "toil" ] }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "unit": { "enum": [ "hours", "days" ] }, "opening": { "type": "number", "minimum": 0, "maximum": 100000 }, "allow_negative": { "type": "boolean" }, "policy_reference": { "type": "string", "minLength": 10, "maxLength": 500 }, "patterns": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/LeaveWorkPattern" } } }, "required": [ "subject_id", "kind", "from", "to", "unit", "opening", "allow_negative", "policy_reference", "patterns" ], "additionalProperties": false }, "LeaveAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject_id": { "type": "integer", "minimum": 1 }, "kind": { "enum": [ "holiday", "toil" ] }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "unit": { "enum": [ "hours", "days" ] }, "balance": { "type": "number" }, "allow_negative": { "type": "boolean" }, "patterns": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/LeaveWorkPattern" } }, "created_at": { "type": "string", "format": "date-time" }, "latest_entry": { "type": "string", "pattern": "^[0-9]+$" }, "policy_version": { "type": "string", "pattern": "^[0-9]+$", "description": "Current pattern version; 0 is original. Absent on preserved command receipts issued before v2.11." } }, "required": [ "id", "subject_id", "kind", "from", "to", "unit", "balance", "allow_negative", "patterns", "created_at", "latest_entry" ], "additionalProperties": false }, "LeaveBalances": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveAccount" } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192 }, { "type": "null" } ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "LeaveDailyCharge": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "quantity": { "type": "number" }, "pattern_from": { "type": "string", "format": "date" } }, "required": [ "date", "quantity", "pattern_from" ], "additionalProperties": false }, "LeaveCalculation": { "type": "object", "properties": { "quantity": { "type": "number" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveDailyCharge" } } }, "required": [ "quantity", "days" ], "additionalProperties": false }, "LeaveEntry": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9]+$" }, "entry_kind": { "enum": [ "opening", "leave_taken", "leave_reversal", "accrual", "accrual_correction", "adjustment", "proration", "carryover_in", "carryover_out", "expiry", "toil_earned", "leave_correction" ] }, "quantity": { "type": "number" }, "leave_id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "request_revision": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "reverses": { "anyOf": [ { "type": "string", "pattern": "^[0-9]+$" }, { "type": "null" } ] }, "breakdown": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/LeaveDailyCharge" } }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "policy_version": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Captured pattern version for leave charges, corrections and reversals; 0 is the original policy; null for unrelated balance entries. For corrections, breakdown describes the revised daily leave charge." }, "accrual_rule_id": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "Introduced in v2.31; absent in responses from earlier deployments." }, "accrual_calculation": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LeaveAccrualCalculation" } ], "description": "Introduced in v2.31; absent in responses from earlier deployments." } }, "required": [ "id", "entry_kind", "quantity", "leave_id", "request_revision", "reverses", "breakdown", "created_at", "policy_version" ], "additionalProperties": false }, "LeaveLedger": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveEntry" } }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192 }, { "type": "null" } ] } }, "required": [ "account", "items", "next_cursor" ], "additionalProperties": false }, "LeavePolicyReview": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/LeaveEntitlementPolicy" }, "existing_approved_charges": { "type": "array", "items": { "type": "object", "properties": { "leave_id": { "type": "integer", "minimum": 1 }, "revision": { "type": "integer", "minimum": 1 }, "quantity": { "type": "number" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveDailyCharge" } } }, "required": [ "leave_id", "revision", "quantity", "days" ], "additionalProperties": false } }, "approved_quantity": { "type": "number" }, "balance_after": { "type": "number" }, "automatic_accrual": { "const": false }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "policy", "existing_approved_charges", "approved_quantity", "balance_after", "automatic_accrual", "review_token" ], "additionalProperties": false }, "LeaveAdjustmentReview": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "kind": { "enum": [ "accrual", "accrual_correction", "adjustment", "proration", "carryover_out", "expiry", "toil_earned" ] }, "quantity": { "type": "number" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "balance_after": { "type": "number" }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/LeaveAccount" }, { "type": "null" } ] }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "account", "kind", "quantity", "reason", "reference", "balance_after", "destination", "review_token" ], "additionalProperties": false }, "LeaveAdjustmentResult": { "type": "object", "properties": { "entry_id": { "type": "string", "pattern": "^[0-9]+$" }, "account": { "$ref": "#/components/schemas/LeaveAccount" } }, "required": [ "entry_id", "account" ], "additionalProperties": false }, "LeaveImpact": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "quantity": { "type": "number" }, "calculation": { "anyOf": [ { "$ref": "#/components/schemas/LeaveCalculation" }, { "type": "null" } ] } }, "required": [ "account", "quantity", "calculation" ], "additionalProperties": false }, "LeaveDecisionResult": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/LeaveRecord" }, "decision": { "enum": [ "approved", "denied" ] }, "reason": { "type": "string" }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveImpact" } } }, "required": [ "request", "decision", "reason", "entitlements" ], "additionalProperties": false }, "LeaveDecisionReview": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/LeaveRecord" }, "decision": { "enum": [ "approved", "denied" ] }, "reason": { "type": "string" }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveImpact" } }, "unconfigured_entitlement": { "type": "boolean" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "request", "decision", "reason", "entitlements", "unconfigured_entitlement", "review_token" ], "additionalProperties": false }, "LeavePolicyVersion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9]+$" }, "patterns": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/LeaveWorkPattern" } }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "patterns", "created_at" ], "additionalProperties": false }, "LeavePolicyHistory": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "original": { "$ref": "#/components/schemas/LeavePolicyVersion" }, "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/LeavePolicyVersion" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "account", "original", "items", "next_cursor" ], "additionalProperties": false }, "LeavePolicyAmendmentReview": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "patterns": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/LeaveWorkPattern" } }, "policy_reference": { "type": "string", "minLength": 10, "maxLength": 500 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "approved_leave_changes": { "type": "array", "maxItems": 366, "items": { "type": "object", "properties": { "leave_id": { "type": "integer", "minimum": 1 }, "revision": { "type": "integer", "minimum": 1 }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "start_minute": { "type": "integer", "minimum": 0, "maximum": 1439, "description": "Local minute on the boundary date; end1440 is the next midnight. Repeated or nonexistent local times are rejected." }, "end_minute": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "Local minute on the boundary date; end1440 is the next midnight. Repeated or nonexistent local times are rejected." }, "previous_quantity": { "type": "number" }, "new_quantity": { "type": "number" }, "quantity": { "type": "number" }, "days": { "type": "array", "maxItems": 366, "items": { "$ref": "#/components/schemas/LeaveDailyCharge" } } }, "required": [ "leave_id", "revision", "from", "to", "start_minute", "end_minute", "previous_quantity", "new_quantity", "quantity", "days" ], "additionalProperties": false } }, "balance_change": { "type": "number" }, "balance_after": { "type": "number" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "account", "patterns", "policy_reference", "reason", "approved_leave_changes", "balance_change", "balance_after", "review_token" ], "additionalProperties": false }, "LeavePolicyAmendmentResult": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "policy_version": { "type": "string", "pattern": "^[0-9]+$" }, "balance_change": { "type": "number" } }, "required": [ "account", "policy_version", "balance_change" ], "additionalProperties": false }, "StaffingPolicyRules": { "type": "object", "properties": { "minimum_staffing": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] } }, "required": [ "enabled", "severity" ], "additionalProperties": false }, "night_cover": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] } }, "required": [ "enabled", "severity" ], "additionalProperties": false }, "skills": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] } }, "required": [ "enabled", "severity" ], "additionalProperties": false }, "lone_working": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] } }, "required": [ "enabled", "severity" ], "additionalProperties": false }, "credentials": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] }, "warning_days": { "type": "integer", "minimum": 0 }, "required": { "type": "array", "items": { "enum": [ "dbs", "level3", "first_aid", "medication", "driving", "restraint" ] } } }, "required": [ "enabled", "severity", "warning_days", "required" ], "additionalProperties": false }, "daily_rest": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] }, "hours": { "type": "number" } }, "required": [ "enabled", "severity", "hours" ], "additionalProperties": false }, "weekly_hours": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] }, "hours": { "type": "number" }, "reference_weeks": { "type": "integer", "minimum": 0 } }, "required": [ "enabled", "severity", "hours", "reference_weeks" ], "additionalProperties": false }, "breaks": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] }, "after_hours": { "type": "number" }, "minutes": { "type": "integer", "minimum": 0 } }, "required": [ "enabled", "severity", "after_hours", "minutes" ], "additionalProperties": false }, "handover": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "severity": { "enum": [ "block", "warn" ] } }, "required": [ "enabled", "severity" ], "additionalProperties": false } }, "required": [ "minimum_staffing", "night_cover", "skills", "lone_working", "credentials", "daily_rest", "weekly_hours", "breaks", "handover" ], "additionalProperties": false }, "StaffingPolicySetting": { "type": "object", "properties": { "rules": { "$ref": "#/components/schemas/StaffingPolicyRules" }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } }, "required": [ "rules", "confirmed_at", "revision" ], "additionalProperties": false }, "StaffingPeriodSetting": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "start_local": { "type": "string" }, "end_local": { "type": "string" }, "end_day_offset": { "enum": [ 0, 1 ] }, "minimum_staff": { "type": "integer", "minimum": 0 }, "waking_night": { "type": "integer", "minimum": 0 }, "sleep_in": { "type": "integer", "minimum": 0 }, "medication": { "type": "integer", "minimum": 0 }, "drivers": { "type": "integer", "minimum": 0 }, "shift_leads": { "type": "integer", "minimum": 0 }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } }, "required": [ "period", "start_local", "end_local", "end_day_offset", "minimum_staff", "waking_night", "sleep_in", "medication", "drivers", "shift_leads", "confirmed_at", "revision" ], "additionalProperties": false }, "StaffingOverrideSetting": { "type": "object", "properties": { "period": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "date": { "type": "string", "format": "date" }, "minimum_staff": { "type": "integer", "minimum": 0 }, "waking_night": { "type": "integer", "minimum": 0 }, "sleep_in": { "type": "integer", "minimum": 0 }, "medication": { "type": "integer", "minimum": 0 }, "drivers": { "type": "integer", "minimum": 0 }, "shift_leads": { "type": "integer", "minimum": 0 }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } }, "required": [ "period", "date", "minimum_staff", "waking_night", "sleep_in", "medication", "drivers", "shift_leads", "revision" ], "additionalProperties": false }, "StaffingCredentialSetting": { "type": "object", "properties": { "worker": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "kind": { "enum": [ "dbs", "level3", "first_aid", "medication", "driving", "restraint" ] }, "status": { "enum": [ "valid", "in_progress", "expired", "missing" ] }, "expires_on": { "type": [ "string", "null" ], "format": "date" }, "deadline": { "type": [ "string", "null" ], "format": "date" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" } }, "required": [ "worker", "kind", "status", "expires_on", "deadline", "verified_at", "revision" ], "additionalProperties": false }, "StaffingCurrentRequirement": { "oneOf": [ { "type": "object", "properties": { "resource": { "const": "rota_check_policies" }, "value": { "$ref": "#/components/schemas/StaffingPolicySetting" } }, "required": [ "resource", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "rota_coverage_periods" }, "value": { "$ref": "#/components/schemas/StaffingPeriodSetting" } }, "required": [ "resource", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "rota_coverage_overrides" }, "value": { "$ref": "#/components/schemas/StaffingOverrideSetting" } }, "required": [ "resource", "value" ], "additionalProperties": false } ] }, "StaffingRequirementEvent": { "oneOf": [ { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9]+$" }, "resource": { "const": "rota_check_policies" }, "operation": { "enum": [ "INSERT", "UPDATE", "DELETE" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "period_baseline": { "type": "boolean" }, "value": { "$ref": "#/components/schemas/StaffingPolicySetting" } }, "required": [ "event_id", "resource", "operation", "recorded_at", "period_baseline", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9]+$" }, "resource": { "const": "rota_coverage_periods" }, "operation": { "enum": [ "INSERT", "UPDATE", "DELETE" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "period_baseline": { "type": "boolean" }, "value": { "$ref": "#/components/schemas/StaffingPeriodSetting" } }, "required": [ "event_id", "resource", "operation", "recorded_at", "period_baseline", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9]+$" }, "resource": { "const": "rota_coverage_overrides" }, "operation": { "enum": [ "INSERT", "UPDATE", "DELETE" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "period_baseline": { "type": "boolean" }, "value": { "$ref": "#/components/schemas/StaffingOverrideSetting" } }, "required": [ "event_id", "resource", "operation", "recorded_at", "period_baseline", "value" ], "additionalProperties": false } ] }, "StaffingScheduleEvidence": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "worker": { "type": [ "string", "null" ], "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer", "minimum": 0 }, "shift_type": { "type": [ "string", "null" ] }, "shift_lead": { "type": "boolean" }, "published": { "type": "boolean" }, "state": { "enum": [ "draft", "published", "acknowledged", "clocked_in", "clocked_out", "approved", "cancelled" ] }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "id", "worker", "start", "end", "break_minutes", "shift_type", "shift_lead", "published", "state", "cancelled_at", "revision" ], "additionalProperties": false }, "StaffingAttendanceEvidence": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "worker": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "shift": { "type": [ "string", "null" ], "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": [ "string", "null" ], "format": "date-time" }, "break_seconds": { "type": "number", "minimum": 0 }, "approval_status": { "enum": [ "pending", "approved" ] }, "voided_at": { "type": [ "string", "null" ], "format": "date-time" }, "attendance_method": { "type": [ "string", "null" ] }, "departure_method": { "type": [ "string", "null" ] }, "revision": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "id", "worker", "shift", "start", "end", "break_seconds", "approval_status", "voided_at", "attendance_method", "departure_method", "revision" ], "additionalProperties": false }, "StaffingLifecycleEvidence": { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9]+$" }, "shift": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "worker": { "type": [ "string", "null" ], "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "actor": { "type": [ "string", "null" ], "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "actor_kind": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "from_state": { "type": [ "string", "null" ] }, "to_state": { "type": "string" }, "method": { "type": [ "string", "null" ] } }, "required": [ "event_id", "shift", "worker", "actor", "actor_kind", "occurred_at", "from_state", "to_state", "method" ], "additionalProperties": false }, "StaffingShiftException": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "shift": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "kind": { "enum": [ "late_clock_in", "no_show", "early_leave", "forgotten_clock_out" ] }, "created_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ], "pattern": "^[a-z-]+-[0-9a-f]{24}$" } }, "required": [ "id", "shift", "kind", "created_at", "resolved_at", "resolved_by" ], "additionalProperties": false }, "StaffingAttendanceException": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "attendance": { "type": [ "string", "null" ], "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "worker": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "claimed_at": { "type": "string", "format": "date-time" }, "status": { "enum": [ "pending", "resolved", "rejected" ] }, "created_at": { "type": "string", "format": "date-time" }, "reviewed_by": { "type": [ "string", "null" ], "pattern": "^[a-z-]+-[0-9a-f]{24}$" } }, "required": [ "id", "attendance", "worker", "claimed_at", "status", "created_at", "reviewed_by" ], "additionalProperties": false }, "StaffingCredentialEvidence": { "type": "object", "properties": { "shift": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "worker": { "type": "string", "pattern": "^[a-z-]+-[0-9a-f]{24}$" }, "as_of": { "type": "string", "format": "date-time" }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": [ "dbs", "level3", "first_aid", "medication", "driving", "restraint" ] }, "evidence_status": { "enum": [ "unknown", "removed", "not_valid", "unverified", "expired_during_or_before_shift", "recorded_valid" ] }, "event_id": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time" }, "record": { "anyOf": [ { "$ref": "#/components/schemas/StaffingCredentialSetting" }, { "type": "null" } ] } }, "required": [ "kind", "evidence_status", "event_id", "recorded_at", "record" ], "additionalProperties": false }, "maxItems": 6 } }, "required": [ "shift", "worker", "as_of", "credentials" ], "additionalProperties": false }, "StaffingPersonCount": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "planned_people": { "type": "integer", "minimum": 0 }, "recorded_attending_people": { "type": "integer", "minimum": 0 } }, "required": [ "from", "to", "planned_people", "recorded_attending_people" ], "additionalProperties": false }, "StaffingEvidenceRecords": { "type": "object", "properties": { "schedule_at_capture": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingScheduleEvidence" }, "maxItems": 1000 }, "attendance_at_capture": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingAttendanceEvidence" }, "maxItems": 1000 }, "recorded_lifecycle": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingLifecycleEvidence" }, "maxItems": 1000 }, "shift_exceptions_at_capture": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingShiftException" }, "maxItems": 1000 }, "attendance_exceptions_at_capture": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingAttendanceException" }, "maxItems": 1000 }, "requirements_at_capture": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingCurrentRequirement" }, "maxItems": 1000 }, "recorded_requirement_versions": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingRequirementEvent" }, "maxItems": 1000 }, "credential_evidence_at_shift_start": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingCredentialEvidence" }, "maxItems": 1000 }, "recorded_credential_changes": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingCredentialEvent" }, "maxItems": 1000 }, "person_count_timeline": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingPersonCount" }, "maxItems": 2000 } }, "required": [ "schedule_at_capture", "attendance_at_capture", "recorded_lifecycle", "shift_exceptions_at_capture", "attendance_exceptions_at_capture", "requirements_at_capture", "recorded_requirement_versions", "credential_evidence_at_shift_start", "recorded_credential_changes", "person_count_timeline" ], "additionalProperties": false }, "StaffingPackPreview": { "type": "object", "properties": { "format": { "const": "shiftforest-staffing-evidence" }, "version": { "const": 1 }, "organization_id": { "type": "string", "format": "uuid" }, "workplace": { "type": "integer", "minimum": 1 }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "timezone": { "type": "string" } }, "required": [ "from", "to", "timezone" ], "additionalProperties": false }, "records": { "$ref": "#/components/schemas/StaffingEvidenceRecords" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "format", "version", "organization_id", "workplace", "period", "records", "limitations" ], "additionalProperties": false }, "StaffingPackPayload": { "type": "object", "properties": { "format": { "const": "shiftforest-staffing-evidence" }, "version": { "const": 1 }, "organization_id": { "type": "string", "format": "uuid" }, "workplace": { "type": "integer", "minimum": 1 }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "timezone": { "type": "string" } }, "required": [ "from", "to", "timezone" ], "additionalProperties": false }, "records": { "$ref": "#/components/schemas/StaffingEvidenceRecords" }, "limitations": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid" }, "captured_at": { "type": "string", "format": "date-time" } }, "required": [ "format", "version", "organization_id", "workplace", "period", "records", "limitations", "id", "captured_at" ], "additionalProperties": false }, "StaffingPackSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "location_id": { "type": "integer", "minimum": 1 }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "revision": { "type": "string", "pattern": "^[0-9]+$" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "purged_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "location_id", "from", "to", "created_at", "expires_at", "sha256", "bytes", "counts", "revision", "revoked_at", "purged_at" ], "additionalProperties": false }, "StaffingPackPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/StaffingPackSummary" }, "maxItems": 50 }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "StaffingPackReview": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "location_id": { "type": "integer", "minimum": 1 }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date-time" }, "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "preview": { "$ref": "#/components/schemas/StaffingPackPreview" }, "retention_policy": { "type": "object", "properties": { "category": { "const": "exports" }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "anchor": { "const": "export_created_at" }, "revision": { "type": "integer", "minimum": 1 }, "approved_at": { "type": "string", "format": "date-time" } }, "required": [ "category", "retention_days", "anchor", "revision", "approved_at" ], "additionalProperties": false }, "access": { "type": "string" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "id", "location_id", "from", "to", "expires_at", "counts", "preview", "retention_policy", "access", "review_token" ], "additionalProperties": false }, "StaffingPackDownload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "filename": { "type": "string", "pattern": "^shiftforest-staffing-[0-9a-f-]{36}\\.json$" }, "content_type": { "const": "application/json" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 8388608 }, "canonical_json": { "type": "string", "description": "Exact UTF-8 bytes encode StaffingPackPayload. Verify id, organization_id, length and SHA-256 before saving. See #/components/schemas/StaffingPackPayload." } }, "required": [ "id", "organization_id", "expires_at", "filename", "content_type", "sha256", "bytes", "canonical_json" ], "additionalProperties": false }, "StaffingPackRevoked": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[0-9]+$" }, "revoked_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "revision", "revoked_at" ], "additionalProperties": false }, "ReviewStaffingPackBody": { "type": "object", "properties": { "pack_id": { "type": "string", "format": "uuid" }, "workplace": { "type": "integer", "minimum": 1 }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "pack_id", "workplace", "from", "to", "expires_at" ], "additionalProperties": false }, "CreateStaffingPackBody": { "type": "object", "properties": { "pack_id": { "type": "string", "format": "uuid" }, "workplace": { "type": "integer", "minimum": 1 }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date-time" }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "confirmed": { "const": true } }, "required": [ "pack_id", "workplace", "from", "to", "expires_at", "request_id", "review_token", "confirmed" ], "additionalProperties": false }, "RevokeStaffingPackBody": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]{0,17}$" } }, "required": [ "request_id", "revision" ], "additionalProperties": false }, "StaffingCredentialEvent": { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9]+$" }, "recorded_at": { "type": "string", "format": "date-time" }, "operation": { "enum": [ "INSERT", "UPDATE", "DELETE" ] }, "record": { "$ref": "#/components/schemas/StaffingCredentialSetting" } }, "required": [ "event_id", "recorded_at", "operation", "record" ], "additionalProperties": false }, "LeaveWithdrawalResult": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/LeaveRecord" }, "action": { "const": "withdraw" }, "reason": { "type": "string" }, "balance_change": { "const": 0 } }, "required": [ "request", "action", "reason", "balance_change" ], "additionalProperties": false }, "LeaveWithdrawalReview": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/LeaveRecord" }, "action": { "const": "withdraw" }, "reason": { "type": "string" }, "balance_change": { "const": 0 }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "request", "action", "reason", "balance_change", "review_token" ], "additionalProperties": false }, "PrivateFile": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "source": { "type": "string", "enum": [ "employee", "management" ] }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "last_version": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "retired_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "current_version": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "id", "subject", "title", "source", "revision", "last_version", "created_at", "retired_at", "current_version" ] }, "PrivateFileDescriptor": { "type": "object", "additionalProperties": false, "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^[^\\x00-\\x1f\\x7f-\\x9f/\\\\]+$" }, "media_type": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "bytes": { "type": "integer", "minimum": 1, "maximum": 4194304 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "requires_acknowledgement": { "type": "boolean" } }, "required": [ "filename", "media_type", "bytes", "sha256", "requires_acknowledgement" ] }, "PrivateFileVersion": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "number": { "type": "integer", "minimum": 1 }, "filename": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^[^\\x00-\\x1f\\x7f-\\x9f/\\\\]+$" }, "media_type": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "bytes": { "type": "integer", "minimum": 1, "maximum": 4194304 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "requires_acknowledgement": { "type": "boolean" }, "state": { "type": "string", "enum": [ "reserved", "pending_scan", "scanning", "available", "blocked", "scan_failed", "expired", "purged" ] }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "created_at": { "type": "string", "format": "date-time" }, "upload_expires_at": { "type": "string", "format": "date-time" }, "retention_until": { "type": "string", "format": "date-time" }, "scanned_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scan_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acknowledged_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "document_id", "number", "filename", "media_type", "bytes", "sha256", "requires_acknowledgement", "state", "revision", "created_at", "upload_expires_at", "retention_until", "scanned_at", "scan_reason", "acknowledged_at" ] }, "PrivateFilePage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PrivateFile" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ingestion_enabled": { "type": "boolean" }, "downloads_enabled": { "type": "boolean" }, "policy_ready": { "type": "boolean" } }, "required": [ "items", "next_cursor", "ingestion_enabled", "downloads_enabled", "policy_ready" ] }, "PrivateFileHistory": { "type": "object", "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/PrivateFile" }, "versions": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PrivateFileVersion" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "document", "versions", "next_cursor" ] }, "PrivateFileReservation": { "type": "object", "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/PrivateFile" }, "version": { "$ref": "#/components/schemas/PrivateFileVersion" } }, "required": [ "document", "version" ] }, "ReservePrivateFileBody": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "subject": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "file": { "$ref": "#/components/schemas/PrivateFileDescriptor" } }, "required": [ "request_id", "document_id", "version_id", "subject", "title", "revision", "file" ] }, "CompletePrivateFileBody": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "required": [ "request_id", "revision" ] }, "AcknowledgePrivateFileBody": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "request_id", "sha256" ] }, "RetirePrivateFileBody": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "confirmed": { "type": "boolean", "const": true } }, "required": [ "request_id", "revision", "reason", "confirmed" ] }, "PrivateFileUploadCredential": { "type": "object", "additionalProperties": false, "properties": { "upload_url": { "type": "string", "format": "uri" }, "method": { "type": "string", "const": "PUT" }, "headers": { "type": "object", "additionalProperties": false, "properties": { "Content-Type": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "x-upsert": { "type": "string", "const": "false" } }, "required": [ "Content-Type", "x-upsert" ] }, "upload_expires_at": { "type": "string", "format": "date-time" }, "provider_credential_lifetime_seconds": { "type": "integer", "const": 7200 } }, "required": [ "upload_url", "method", "headers", "upload_expires_at", "provider_credential_lifetime_seconds" ] }, "AttendanceSummaryMetrics": { "type": "object", "additionalProperties": false, "required": [ "sessions", "workers", "closed_sessions", "open_sessions", "approved_closed_sessions", "pending_closed_sessions", "gross_seconds", "break_seconds", "net_seconds" ], "properties": { "sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "workers": { "type": "integer", "minimum": 0, "maximum": 100000 }, "closed_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "open_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "approved_closed_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "pending_closed_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "gross_seconds": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "break_seconds": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "net_seconds": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "AttendanceSummaryDay": { "type": "object", "additionalProperties": false, "required": [ "date", "sessions", "workers", "closed_sessions", "open_sessions", "approved_closed_sessions", "pending_closed_sessions", "gross_seconds", "break_seconds", "net_seconds" ], "properties": { "date": { "type": "string", "format": "date" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "workers": { "type": "integer", "minimum": 0, "maximum": 100000 }, "closed_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "open_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "approved_closed_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "pending_closed_sessions": { "type": "integer", "minimum": 0, "maximum": 100000 }, "gross_seconds": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "break_seconds": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "net_seconds": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" } } }, "AttendanceSummary": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "timezone", "calculated_at", "attribution", "time_basis", "voided_included", "payroll_calculation", "maximum_records", "totals", "days" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "calculated_at": { "type": "string", "format": "date-time" }, "attribution": { "const": "clock_in_local_date" }, "time_basis": { "const": "closed_recorded_seconds_unrounded" }, "voided_included": { "const": false }, "payroll_calculation": { "const": false }, "maximum_records": { "const": 100000 }, "totals": { "$ref": "#/components/schemas/AttendanceSummaryMetrics" }, "days": { "type": "array", "maxItems": 96, "items": { "$ref": "#/components/schemas/AttendanceSummaryDay" } } } }, "DashboardAttention": { "type": "object", "additionalProperties": false, "required": [ "company_id", "member_id", "calculated_at", "timezone", "today", "week_from", "week_to", "rota_week", "month_from", "month_to_exclusive", "scope", "maximum_records_per_section", "pending_leave", "draft_shifts", "unapproved_clocks" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "calculated_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "today": { "type": "string", "format": "date" }, "week_from": { "type": "string", "format": "date" }, "week_to": { "type": "string", "format": "date" }, "rota_week": { "type": "string", "format": "date" }, "month_from": { "type": "string", "format": "date" }, "month_to_exclusive": { "type": "string", "format": "date" }, "scope": { "enum": [ "workspace", "managed_workplaces" ] }, "maximum_records_per_section": { "const": 100000 }, "pending_leave": { "type": "integer", "minimum": 0, "maximum": 100000 }, "draft_shifts": { "type": "integer", "minimum": 0, "maximum": 100000 }, "unapproved_clocks": { "type": "integer", "minimum": 0, "maximum": 100000 } } }, "PushDevice": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "revision", "status", "created_at", "updated_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "revision": { "type": "integer", "minimum": 1 }, "status": { "enum": [ "active", "revoked", "expired" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "PushDevices": { "type": "object", "additionalProperties": false, "required": [ "configured", "application_server_key", "devices" ], "properties": { "configured": { "type": "boolean" }, "application_server_key": { "type": [ "string", "null" ] }, "devices": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PushDevice" } } } }, "PushEnrollment": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "p256dh", "authentication", "application_key", "label", "consent" ], "properties": { "endpoint": { "type": "string", "format": "uri", "maxLength": 4096 }, "p256dh": { "type": "string" }, "authentication": { "type": "string" }, "application_key": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "consent": { "const": true } } }, "DirectoryUser": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "photo": { "type": [ "string", "null" ] }, "payroll_id": { "type": [ "string", "null" ] }, "employee_code": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "salary_type": { "type": [ "string", "null" ] }, "holiday_allowance_unit": { "type": [ "string", "null" ] }, "leave_rates_type": { "type": [ "string", "null" ] }, "leave_rates_unit": { "type": [ "string", "null" ] }, "level": { "type": [ "string", "null" ], "enum": [ "admin", "manager", "employee", null ], "description": "Workspace access level, not the job role." }, "deleted": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "roles": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "locations_manager": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "locations_cover": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "default_role": { "type": [ "integer", "null" ], "minimum": 1 }, "group": { "type": [ "integer", "null" ], "minimum": 1 }, "salary": { "type": [ "number", "null" ], "description": "Legacy compensation value. Scoped integrations require pay:read; omitted means unavailable, not zero. Use reviewed profile/payroll workflows for authoritative pay changes." }, "weekly_hours": { "type": [ "number", "null" ] }, "holiday_allowance": { "type": [ "number", "null" ] }, "overtime_rate": { "type": [ "number", "null" ] }, "dob": { "type": [ "string", "number", "null" ], "description": "Retained legacy date metadata; do not assume one normalized date representation." }, "start_date": { "type": [ "string", "number", "null" ], "description": "Retained legacy date metadata; do not assume one normalized date representation." }, "final_working_date": { "type": [ "string", "number", "null" ], "description": "Retained legacy date metadata; do not assume one normalized date representation." }, "preferences": { "type": "object", "additionalProperties": true }, "role_rates": { "type": "object", "additionalProperties": true }, "leave_rates": { "type": "object", "additionalProperties": true }, "permissions": { "type": "array", "items": {} }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at_unix": { "type": [ "number", "null" ], "description": "Unix seconds; legacy compatibility field." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at_unix": { "type": [ "number", "null" ], "description": "Unix seconds; legacy compatibility field." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at_unix": { "type": [ "number", "null" ], "description": "Unix seconds; legacy compatibility field." } }, "required": [ "id", "version", "external_ids" ], "description": "Worker catalogue read. Identity and legacy metadata are explicit; optional fields depend on credential scope and retained source data. Scoped readers omit pay fields without pay:read and exclude unauthorized workplace memberships. Absence is not a zero or permission to infer private values. Existing metadata is not a complete effective-dated employment contract." }, "TeamSummary": { "type": "object", "required": [ "company_id", "member_id", "week_from", "week_to", "search", "timezone", "location_id", "members", "managers", "admins", "scope", "maximum_records_per_section", "scheduled_hours", "over_weekly_limit" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "week_from": { "type": "string", "format": "date" }, "week_to": { "type": "string", "format": "date" }, "search": { "type": "string" }, "timezone": { "type": "string" }, "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "members": { "type": "integer", "minimum": 0, "maximum": 100000 }, "managers": { "type": "integer", "minimum": 0, "maximum": 100000 }, "admins": { "type": "integer", "minimum": 0, "maximum": 100000 }, "scope": { "enum": [ "workspace", "managed_workplaces" ] }, "maximum_records_per_section": { "const": 100000 }, "scheduled_hours": { "type": "number", "minimum": 0 }, "over_weekly_limit": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000 } }, "additionalProperties": false }, "TeamWorker": { "type": "object", "required": [ "id", "company_id", "name", "email", "role_tag", "avatar_color", "employee_code", "role", "hourly_pay_rate", "max_weekly_hours", "login_enabled", "row_revision", "public_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "role_tag": { "type": "string" }, "avatar_color": { "type": "string" }, "employee_code": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "manager", "employee" ] }, "hourly_pay_rate": { "type": [ "number", "null" ] }, "max_weekly_hours": { "type": [ "number", "null" ] }, "login_enabled": { "type": "boolean" }, "row_revision": { "type": "integer", "minimum": 1 }, "public_id": { "type": "integer", "minimum": 1, "description": "Public numeric ID for existing /users/{id} catalogue and reviewed profile commands; id remains the native workforce UUID." } }, "additionalProperties": false }, "TeamMember": { "type": "object", "required": [ "company_id", "member_id", "scope", "user", "locations", "managed_locations" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "workspace", "managed_workplaces" ] }, "user": { "$ref": "#/components/schemas/TeamWorker" }, "locations": { "type": "array", "maxItems": 10000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "managed_locations": { "type": "array", "maxItems": 10000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false }, "TeamDirectoryEntry": { "type": "object", "required": [ "user", "locations", "scheduled_hours", "over_weekly_limit" ], "properties": { "user": { "$ref": "#/components/schemas/TeamWorker" }, "locations": { "type": "array", "maxItems": 10000, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "scheduled_hours": { "type": "number", "minimum": 0 }, "over_weekly_limit": { "type": [ "boolean", "null" ] } }, "additionalProperties": false }, "TeamDirectory": { "type": "object", "required": [ "company_id", "member_id", "scope", "week_from", "search", "location_id", "data", "has_more", "next_cursor" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "scope": { "enum": [ "workspace", "managed_workplaces" ] }, "week_from": { "type": "string", "format": "date" }, "search": { "type": "string" }, "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/TeamDirectoryEntry" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 8192 } }, "additionalProperties": false }, "DirectoryPerson": { "type": "object", "required": [ "id", "name", "role", "role_tag", "avatar_color" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "manager", "employee" ] }, "role_tag": { "type": "string" }, "avatar_color": { "type": "string" } }, "additionalProperties": false }, "DirectorySearch": { "type": "object", "required": [ "company_id", "member_id", "search", "data", "has_more" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "search": { "type": "string", "minLength": 2, "maxLength": 80 }, "data": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/DirectoryPerson" } }, "has_more": { "type": "boolean" } }, "additionalProperties": false }, "SetupProgress": { "type": "object", "required": [ "company_id", "member_id", "observed_at", "steps", "verified_colleague" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "observed_at": { "type": "string", "format": "date-time" }, "steps": { "type": "object", "required": [ "workplace", "team", "published_shift" ], "properties": { "workplace": { "type": "boolean" }, "team": { "type": "boolean" }, "published_shift": { "type": "boolean" } }, "additionalProperties": false }, "verified_colleague": { "type": "boolean" } }, "additionalProperties": false }, "DelegatedWorkplaceGroup": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "locations": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 256 } }, "required": [ "id", "name", "parent_id", "locations" ] }, "DelegatedRole": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "staffing.read", "staffing.manage", "payroll.read", "payroll.export", "payroll.adjust" ] }, "maxItems": 5, "minItems": 1 } }, "required": [ "id", "name", "capabilities" ] }, "DelegatedGrant": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "role_id": { "type": "string", "format": "uuid" }, "subject_type": { "type": "string", "enum": [ "user", "scim_group" ] }, "subject_id": { "type": "string", "format": "uuid" }, "scope_type": { "type": "string", "enum": [ "workspace", "group", "location" ] }, "scope_id": { "type": [ "string", "null" ], "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "role_id", "subject_type", "subject_id", "scope_type", "scope_id", "expires_at" ] }, "DelegationConfig": { "type": "object", "additionalProperties": false, "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/DelegatedWorkplaceGroup" }, "maxItems": 64 }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/DelegatedRole" }, "maxItems": 32 }, "bindings": { "type": "array", "items": { "$ref": "#/components/schemas/DelegatedGrant" }, "maxItems": 256 } }, "required": [ "groups", "roles", "bindings" ] }, "DelegationConfiguration": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "config": { "$ref": "#/components/schemas/DelegationConfig" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "staffing.read", "staffing.manage", "payroll.read", "payroll.export", "payroll.adjust" ] }, "maxItems": 5, "minItems": 5 }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "revision", "config", "capabilities", "labels" ] }, "DelegationReview": { "type": "object", "additionalProperties": false, "properties": { "review_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "previous": { "$ref": "#/components/schemas/DelegationConfig" }, "proposed": { "$ref": "#/components/schemas/DelegationConfig" }, "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "review_id", "expires_at", "previous", "proposed", "revision", "labels" ] }, "DelegationResult": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "config": { "$ref": "#/components/schemas/DelegationConfig" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "revision", "config", "labels" ] }, "DelegationMember": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "DelegationSCIMGroup": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "connection": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "name", "connection", "enabled" ] }, "DelegationMemberPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DelegationMember" }, "maxItems": 25 }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "items", "next_cursor" ] }, "DelegationSCIMGroupPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DelegationSCIMGroup" }, "maxItems": 25 }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "items", "next_cursor" ] }, "DelegationHistoryPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "previous": { "$ref": "#/components/schemas/DelegationConfig" }, "config": { "$ref": "#/components/schemas/DelegationConfig" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "created_at", "actor_id", "revision", "previous", "config", "labels" ] }, "maxItems": 25 }, "next_cursor": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "before", "id" ] } ] } }, "required": [ "items", "next_cursor" ] }, "DelegatedStaffingWorkplaces": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "can_manage": { "type": "boolean" } }, "required": [ "id", "name", "can_manage" ] } }, "ReviewDelegationBody": { "type": "object", "additionalProperties": false, "properties": { "config": { "$ref": "#/components/schemas/DelegationConfig" }, "revision": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" } }, "required": [ "config", "revision" ] }, "ApplyDelegationBody": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "confirmed": { "const": true, "type": "boolean" } }, "required": [ "request_id", "review_id", "confirmed" ] }, "PayrollFrozenLine": { "type": "object", "additionalProperties": false, "properties": { "clock_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "employee_code": { "type": "string" }, "name": { "type": "string" }, "date": { "type": "string", "format": "date" }, "pay_code": { "type": "string" }, "minutes": { "type": "number" }, "rate_minor": { "type": "integer" }, "amount_minor": { "type": "integer" }, "currency": { "type": "string" }, "rate_id": { "type": "string", "format": "uuid" }, "clock_in": { "type": "string", "format": "date-time" }, "clock_out": { "type": "string", "format": "date-time" }, "approved_by": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "unit": { "type": "string", "enum": [ "hour", "shift" ] }, "multiplier_bps": { "type": "integer", "minimum": 10000, "maximum": 50000 }, "duration_us": { "type": "integer", "minimum": 0, "maximum": 604800000000 }, "workplace_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "policy_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "policy_revision": { "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "shift_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "source_fingerprint": { "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^[0-9a-f]{64}$" } ] } }, "required": [ "clock_id", "user_id", "employee_code", "name", "date", "pay_code", "minutes", "rate_minor", "amount_minor", "currency", "rate_id", "clock_in", "clock_out", "approved_by" ] }, "PayrollChangeExport": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "total_minor": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollFrozenLine" } } }, "required": [ "id", "from_date", "to_date", "currency", "total_minor", "lines" ] }, "PayrollChangeFacts": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "effective_from": { "type": "string", "format": "date" }, "effective_until": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date" } ] }, "rate_minor": { "type": "integer" }, "currency": { "type": "string" }, "source": { "type": "string" }, "verified": { "type": "boolean" }, "created_by": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "created_at": { "type": "string", "format": "date-time" }, "export_id": { "type": "string", "format": "uuid" }, "clock_id": { "type": "string", "format": "uuid" }, "original_minor": { "type": "integer" }, "current_minor": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollFrozenLine" } }, "desired_minor": { "type": "integer" }, "delta_minor": { "type": "integer" }, "reason": { "type": "string" }, "adjustment_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "external_reference": { "type": "string" }, "expected_minor": { "type": "integer" }, "reported_minor": { "type": "integer" }, "expected_items": { "type": "integer" }, "reported_items": { "type": "integer" }, "difference_minor": { "type": "integer" }, "matched": { "type": "boolean" }, "evidence_type": { "type": "string", "enum": [ "administrator_reported" ] }, "policy_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "config": { "$ref": "#/components/schemas/PayrollPolicyConfig" }, "timezone": { "type": "string" }, "fixed_pay_id": { "type": "string", "format": "uuid" }, "employee_code": { "type": "string" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "amount_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "pay_code": { "type": "string", "enum": [ "SALARY", "BONUS", "ALLOWANCE", "OTHER" ] }, "reference": { "type": "string" } }, "required": [] }, "PayrollChangeReview": { "type": "object", "additionalProperties": false, "properties": { "review_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "rate", "adjustment", "reconciliation", "policy", "fixed_pay", "fixed_adjustment", "fixed_reconciliation" ] }, "expires_at": { "type": "string", "format": "date-time" }, "before": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PayrollChangeFacts" } ] }, "after": { "$ref": "#/components/schemas/PayrollChangeFacts" }, "notes": { "type": "string" } }, "required": [ "review_id", "kind", "expires_at", "before", "after", "notes" ] }, "PayrollAdjustment": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "export_id": { "type": "string", "format": "uuid" }, "clock_id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string" }, "previous_minor": { "type": "integer" }, "desired_minor": { "type": "integer" }, "delta_minor": { "type": "integer" }, "currency": { "type": "string" }, "source_line": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollFrozenLine" } }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "export_id", "clock_id", "actor_id", "reason", "previous_minor", "desired_minor", "delta_minor", "currency", "source_line", "created_at" ] }, "PayrollReconciliation": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "export_id": { "type": "string", "format": "uuid" }, "adjustment_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "actor_id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string" }, "expected_minor": { "type": "integer" }, "reported_minor": { "type": "integer" }, "expected_items": { "type": "integer" }, "reported_items": { "type": "integer" }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "export_id", "adjustment_id", "actor_id", "external_reference", "expected_minor", "reported_minor", "expected_items", "reported_items", "currency", "created_at" ] }, "PayrollChangeReceipt": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "rate", "adjustment", "reconciliation", "policy", "fixed_pay", "fixed_adjustment", "fixed_reconciliation" ] }, "before": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PayrollChangeFacts" } ] }, "after": { "$ref": "#/components/schemas/PayrollChangeFacts" }, "applied_at": { "type": "string", "format": "date-time" }, "rate_id": { "type": "string", "format": "uuid" }, "adjustment": { "$ref": "#/components/schemas/PayrollAdjustment" }, "reconciliation": { "$ref": "#/components/schemas/PayrollReconciliation" }, "policy_id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "fixed_pay": { "$ref": "#/components/schemas/PayrollFixedPay" }, "fixed_reconciliation": { "$ref": "#/components/schemas/PayrollFixedReconciliation" }, "delegated_payroll": { "type": "boolean" } }, "required": [ "request_id", "review_id", "kind", "before", "after", "applied_at" ] }, "PayrollChangeHistory": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 25, "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "rate", "adjustment", "reconciliation", "policy", "fixed_pay", "fixed_adjustment", "fixed_reconciliation" ] }, "result": { "$ref": "#/components/schemas/PayrollChangeReceipt" } }, "required": [ "id", "actor_id", "created_at", "kind", "result" ] } }, "next_cursor": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "before", "id" ] } ] } }, "required": [ "items", "next_cursor" ] }, "PayrollChangeInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "rate" }, "input": { "type": "object", "additionalProperties": false, "properties": { "user_id": { "type": "string", "format": "uuid" }, "effective_from": { "type": "string", "format": "date" }, "rate_minor": { "type": "integer", "minimum": 0, "maximum": 10000000 } }, "required": [ "user_id", "effective_from", "rate_minor" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "adjustment" }, "input": { "type": "object", "additionalProperties": false, "properties": { "export_id": { "type": "string", "format": "uuid" }, "clock_id": { "type": "string", "format": "uuid" }, "desired_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "export_id", "clock_id", "desired_minor", "reason" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "reconciliation" }, "input": { "type": "object", "additionalProperties": false, "properties": { "export_id": { "type": "string", "format": "uuid" }, "adjustment_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "external_reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "reported_minor": { "type": "integer", "minimum": -999999999999999, "maximum": 999999999999999 }, "reported_items": { "type": "integer", "minimum": 0, "maximum": 9999999 } }, "required": [ "export_id", "external_reference", "reported_minor", "reported_items" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "policy" }, "input": { "type": "object", "additionalProperties": false, "properties": { "effective_from": { "type": "string", "format": "date" }, "config": { "$ref": "#/components/schemas/PayrollPolicyConfig" } }, "required": [ "effective_from", "config" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "fixed_pay" }, "input": { "type": "object", "additionalProperties": false, "properties": { "user_id": { "type": "string", "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "amount_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "pay_code": { "type": "string", "enum": [ "SALARY", "BONUS", "ALLOWANCE", "OTHER" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "user_id", "from_date", "to_date", "amount_minor", "pay_code", "reference", "reason" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "fixed_adjustment" }, "input": { "type": "object", "additionalProperties": false, "properties": { "fixed_pay_id": { "type": "string", "format": "uuid" }, "desired_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "fixed_pay_id", "desired_minor", "reason" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "fixed_reconciliation" }, "input": { "type": "object", "additionalProperties": false, "properties": { "fixed_pay_id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "reported_minor": { "type": "integer", "minimum": -999999999999999, "maximum": 999999999999999 }, "reported_items": { "type": "integer", "minimum": 0, "maximum": 9999999 } }, "required": [ "fixed_pay_id", "external_reference", "reported_minor", "reported_items" ] } }, "required": [ "kind", "input" ] } ] }, "ApplyPayrollChangeBody": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "confirmed": { "const": true, "type": "boolean" } }, "required": [ "request_id", "review_id", "confirmed" ] }, "PayrollPolicyConfig": { "type": "object", "additionalProperties": false, "properties": { "week_start": { "type": "integer", "minimum": 1, "maximum": 7 }, "daily_overtime_minutes": { "oneOf": [ { "type": "null" }, { "type": "integer", "minimum": 1, "maximum": 1440 } ] }, "weekly_overtime_minutes": { "oneOf": [ { "type": "null" }, { "type": "integer", "minimum": 1, "maximum": 10080 } ] }, "daily_multiplier_bps": { "type": "integer", "minimum": 10000, "maximum": 50000 }, "weekly_multiplier_bps": { "type": "integer", "minimum": 10000, "maximum": 50000 }, "enhancements": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "weekdays": { "type": "array", "minItems": 1, "maxItems": 7, "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "start_minute": { "type": "integer", "minimum": 0, "maximum": 1439 }, "end_minute": { "type": "integer", "minimum": 1, "maximum": 1440 }, "multiplier_bps": { "type": "integer", "minimum": 10000, "maximum": 50000 } }, "required": [ "name", "weekdays", "start_minute", "end_minute", "multiplier_bps" ] } }, "sleep_in_mode": { "type": "string", "enum": [ "hourly_plus_allowance", "allowance_and_disturbance" ] }, "sleep_allowance_minor": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "disturbance_multiplier_bps": { "type": "integer", "minimum": 10000, "maximum": 50000 }, "breaks_paid": { "type": "boolean" }, "round_minutes": { "type": "integer", "minimum": 0, "maximum": 60 } }, "required": [ "week_start", "daily_overtime_minutes", "weekly_overtime_minutes", "daily_multiplier_bps", "weekly_multiplier_bps", "enhancements", "sleep_in_mode", "sleep_allowance_minor", "disturbance_multiplier_bps", "breaks_paid", "round_minutes" ] }, "PayrollPolicyVersion": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "effective_from": { "type": "string", "format": "date" }, "config": { "$ref": "#/components/schemas/PayrollPolicyConfig" }, "currency": { "type": "string" }, "timezone": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "revision", "effective_from", "config", "currency", "timezone", "created_at" ] }, "PayrollPolicyPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/PayrollPolicyVersion" } }, "next_cursor": { "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] } }, "required": [ "items", "next_cursor" ] }, "PayrollComponentPolicy": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "const": 2 }, "timezone": { "type": "string" }, "component_rounding": { "type": "string" }, "overtime_boundary": { "type": "string" }, "enhancement_boundary": { "type": "string" }, "sleep_in": { "type": "string" }, "policies": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "effective_from": { "type": "string", "format": "date" }, "config": { "$ref": "#/components/schemas/PayrollPolicyConfig" }, "currency": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "revision", "effective_from", "config", "currency", "timezone" ] } }, "coverage": { "type": "string" }, "basic_rules": { "type": "object", "additionalProperties": false, "properties": { "breaks_paid": { "type": "boolean" }, "round_minutes": { "type": "integer", "minimum": 0 }, "rate_boundary": { "type": "string" } }, "required": [ "breaks_paid", "round_minutes", "rate_boundary" ] } }, "required": [ "schema_version", "timezone", "component_rounding", "overtime_boundary", "enhancement_boundary", "sleep_in", "policies", "coverage", "basic_rules" ] }, "PayrollFixedPay": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "original_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "name": { "type": "string" }, "employee_code": { "type": "string" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "pay_code": { "type": "string", "enum": [ "SALARY", "BONUS", "ALLOWANCE", "OTHER" ] }, "amount_minor": { "type": "integer", "minimum": -1000000000000, "maximum": 1000000000000 }, "reference": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "actor_id", "user_id", "original_id", "name", "employee_code", "from_date", "to_date", "currency", "pay_code", "amount_minor", "reference", "reason", "created_at" ] }, "PayrollFixedReconciliation": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "format": "uuid" }, "fixed_pay_id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string" }, "expected_minor": { "type": "integer", "minimum": -1000000000000, "maximum": 1000000000000 }, "reported_minor": { "type": "integer", "minimum": -999999999999999, "maximum": 999999999999999 }, "reported_items": { "type": "integer", "minimum": 0, "maximum": 9999999 }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "actor_id", "fixed_pay_id", "external_reference", "expected_minor", "reported_minor", "reported_items", "currency", "created_at" ] }, "PayrollFixedPayPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/PayrollFixedPay" } }, "next_cursor": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "before", "id" ] } ] } }, "required": [ "items", "next_cursor" ] }, "PayrollWorkplaces": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "can_export": { "type": "boolean" }, "can_adjust": { "type": "boolean" } }, "required": [ "id", "name", "can_export", "can_adjust" ] } }, "ScopedPayrollExport": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "total_minor": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollFrozenLine" } }, "location_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "workplace" ] }, "created_at": { "type": "string", "format": "date-time" }, "line_count": { "type": "integer", "minimum": 0 }, "policy": { "type": "object", "additionalProperties": true } }, "required": [ "id", "from_date", "to_date", "currency", "total_minor", "lines", "location_id", "scope", "created_at", "line_count", "policy" ] }, "ScopedPayrollExportPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "total_minor": { "type": "integer" }, "location_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "workplace" ] }, "created_at": { "type": "string", "format": "date-time" }, "line_count": { "type": "integer", "minimum": 0 } }, "required": [ "id", "from_date", "to_date", "currency", "total_minor", "location_id", "scope", "created_at", "line_count" ] } }, "next_cursor": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "before", "id" ] } ] } }, "required": [ "items", "next_cursor" ] }, "ScopedPayrollReview": { "type": "object", "additionalProperties": false, "properties": { "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "total_minor": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollFrozenLine" } }, "location_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "workplace" ] }, "policy": { "type": "object", "additionalProperties": true }, "review_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "clock_id": { "type": "string", "format": "uuid" }, "worker": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "clock_id", "worker", "reason" ] } } }, "required": [ "from_date", "to_date", "currency", "total_minor", "lines", "location_id", "scope", "policy", "review_id", "expires_at", "issues" ] }, "ScopedPayrollAdjustmentReview": { "type": "object", "additionalProperties": false, "properties": { "review_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "rate", "adjustment", "reconciliation", "policy", "fixed_pay", "fixed_adjustment", "fixed_reconciliation" ] }, "expires_at": { "type": "string", "format": "date-time" }, "before": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PayrollChangeFacts" } ] }, "after": { "$ref": "#/components/schemas/PayrollChangeFacts" }, "notes": { "type": "string" }, "location_id": { "type": "string", "format": "uuid" } }, "required": [ "review_id", "kind", "expires_at", "before", "after", "notes", "location_id" ] }, "ScopedPayrollAdjustmentPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollAdjustment" } }, "next_cursor": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "before": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "before", "id" ] } ] } }, "required": [ "items", "next_cursor" ] }, "ReviewScopedPayrollBody": { "type": "object", "additionalProperties": false, "properties": { "location_id": { "type": "string", "format": "uuid" }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } }, "required": [ "location_id", "from_date", "to_date" ] }, "FreezeScopedPayrollBody": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "confirmed": { "const": true, "type": "boolean" }, "location_id": { "type": "string", "format": "uuid" } }, "required": [ "request_id", "review_id", "confirmed", "location_id" ] }, "ReviewScopedPayrollAdjustmentBody": { "type": "object", "additionalProperties": false, "properties": { "location_id": { "type": "string", "format": "uuid" }, "input": { "type": "object", "additionalProperties": false, "properties": { "export_id": { "type": "string", "format": "uuid" }, "clock_id": { "type": "string", "format": "uuid" }, "desired_minor": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "export_id", "clock_id", "desired_minor", "reason" ] } }, "required": [ "location_id", "input" ] }, "WorkspaceParticipant": { "type": "object", "additionalProperties": false, "required": [ "id", "company_id", "name", "role", "role_tag", "avatar_color", "email", "employee_code", "hourly_pay_rate", "max_weekly_hours" ], "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "manager", "employee" ] }, "role_tag": { "type": "string" }, "avatar_color": { "type": "string" }, "email": { "type": "string" }, "employee_code": { "type": "string" }, "hourly_pay_rate": { "type": "number", "nullable": true, "minimum": 0 }, "max_weekly_hours": { "type": "number", "nullable": true, "minimum": 0 }, "row_revision": { "type": "integer", "minimum": 1 }, "login_enabled": { "type": "boolean" } } }, "WorkspaceParticipants": { "type": "object", "additionalProperties": false, "required": [ "company_id", "member_id", "scope_hash", "directory_scope", "users", "assignments" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "scope_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "directory_scope": { "type": "string", "enum": [ "requested_participants" ] }, "users": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/WorkspaceParticipant" } }, "assignments": { "type": "array", "maxItems": 10000, "items": { "type": "object", "additionalProperties": false, "required": [ "company_id", "user_id", "location_id" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "location_id": { "type": "string", "format": "uuid" } } } } } }, "WorkspaceParticipantsBody": { "type": "object", "additionalProperties": false, "required": [ "user_ids" ], "properties": { "user_ids": { "type": "array", "maxItems": 500, "items": { "type": "string", "format": "uuid" }, "minItems": 1, "uniqueItems": true } } }, "WorkspaceRotaRoster": { "type": "object", "additionalProperties": false, "required": [ "company_id", "member_id", "scope_hash", "location_id", "search", "role_tag", "total", "data", "has_more", "next_cursor" ], "properties": { "company_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "scope_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "location_id": { "type": "string", "format": "uuid" }, "search": { "type": "string", "maxLength": 80 }, "role_tag": { "type": "string", "nullable": true, "maxLength": 80 }, "total": { "type": "integer", "minimum": 0, "maximum": 100000 }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/WorkspaceParticipant" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true, "maxLength": 8192 } } }, "DocumentDeletionReview": { "type": "object", "additionalProperties": false, "required": [ "version_id", "document_id", "subject_id", "filename", "bytes", "sha256", "version_revision", "document_revision", "current_version", "policy_revision", "retention_until", "reason", "blockers", "enabled", "metadata_retained", "external_copies_removed", "review_token" ], "properties": { "version_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": [ "integer", "null" ], "minimum": 1 }, "filename": { "type": "string" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 4194304 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "version_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "document_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "current_version": { "type": [ "string", "null" ], "format": "uuid" }, "policy_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "retention_until": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": "string" }, "blockers": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "metadata_retained": { "const": true }, "external_copies_removed": { "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "DocumentDeletionAuthorized": { "type": "object", "additionalProperties": false, "required": [ "version_id", "authorized_at", "state", "metadata_retained", "external_copies_removed" ], "properties": { "version_id": { "type": "string", "format": "uuid" }, "authorized_at": { "type": "string", "format": "date-time" }, "state": { "const": "pending" }, "metadata_retained": { "const": true }, "external_copies_removed": { "const": false } } }, "DocumentDeletionStatus": { "type": "object", "additionalProperties": false, "required": [ "version_id", "authorized_at", "state", "attempts", "completed_at", "provider_absence_verified", "metadata_retained", "external_copies_removed" ], "properties": { "version_id": { "type": "string", "format": "uuid" }, "authorized_at": { "type": "string", "format": "date-time" }, "state": { "enum": [ "pending", "leased", "retry", "needs_attention", "complete" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 10000 }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "provider_absence_verified": { "type": "boolean" }, "metadata_retained": { "const": true }, "external_copies_removed": { "const": false } } }, "DocumentDeletionRetried": { "type": "object", "additionalProperties": false, "required": [ "version_id", "state", "attempts" ], "properties": { "version_id": { "type": "string", "format": "uuid" }, "state": { "const": "retry" }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9999 } } }, "ProfileRedactionReview": { "type": "object", "additionalProperties": false, "required": [ "case_id", "subject_id", "subject_name", "subject_email", "case_revision", "profile_revision", "policy_revision", "offboarded_at", "retention_until", "reason", "blockers", "enabled", "removed_fields", "retained_data", "full_erasure_completed", "case_closed_by_action", "review_token" ], "properties": { "case_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": [ "integer", "null" ], "minimum": 1 }, "subject_name": { "type": "string" }, "subject_email": { "type": "string" }, "case_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "profile_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "policy_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "offboarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "retention_until": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "blockers": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "removed_fields": { "type": "array", "items": { "type": "string" } }, "retained_data": { "type": "array", "items": { "type": "string" } }, "full_erasure_completed": { "type": "boolean", "const": false }, "case_closed_by_action": { "type": "boolean", "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "ProfileRedactionResult": { "type": "object", "additionalProperties": false, "required": [ "case_id", "subject_id", "authorized_at", "state", "sync_generation", "retained_data", "full_erasure_completed", "case_closed_by_action" ], "properties": { "case_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": [ "integer", "null" ], "minimum": 1 }, "authorized_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "const": "primary_details_removed" }, "sync_generation": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "retained_data": { "type": "array", "items": { "type": "string" } }, "full_erasure_completed": { "type": "boolean", "const": false }, "case_closed_by_action": { "type": "boolean", "const": false } } }, "LeaveAccrualPublicPolicy": { "type": "object", "properties": { "period_quantity": { "type": "number", "minimum": 0, "maximum": 100000, "multipleOf": 0.0001 }, "already_awarded": { "type": "number", "minimum": 0, "maximum": 100000, "multipleOf": 0.0001 }, "eligible_from": { "type": "string", "format": "date" }, "eligible_to": { "type": "string", "format": "date" }, "frequency": { "enum": [ "daily", "calendar_month_end", "upfront" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 }, "enabled": { "type": "boolean" } }, "required": [ "period_quantity", "already_awarded", "eligible_from", "eligible_to", "frequency", "timezone", "enabled" ], "additionalProperties": false }, "LeaveAccrualPolicy": { "type": "object", "properties": { "period_quantity": { "type": "number", "minimum": 0, "maximum": 100000, "multipleOf": 0.0001 }, "already_awarded": { "type": "number", "minimum": 0, "maximum": 100000, "multipleOf": 0.0001 }, "eligible_from": { "type": "string", "format": "date" }, "eligible_to": { "type": "string", "format": "date" }, "frequency": { "enum": [ "daily", "calendar_month_end", "upfront" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 }, "enabled": { "type": "boolean" }, "reference": { "type": "string", "minLength": 10, "maxLength": 500 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "period_quantity", "already_awarded", "eligible_from", "eligible_to", "frequency", "timezone", "enabled", "reference", "reason" ], "additionalProperties": false }, "LeaveAccrualCalculation": { "type": "object", "properties": { "local_today": { "type": "string", "format": "date" }, "earned_through": { "type": [ "string", "null" ], "format": "date" }, "period_days": { "type": "integer", "minimum": 1, "maximum": 366 }, "eligible_days": { "type": "integer", "minimum": 1, "maximum": 366 }, "credited_days": { "type": "integer", "minimum": 0, "maximum": 366 }, "cumulative_quantity": { "type": "number" }, "full_eligible_quantity": { "type": "number" }, "rounding": { "const": "cumulative_nearest_0.0001_half_up" }, "basis": { "const": "inclusive_calendar_days" }, "already_awarded": { "type": "number" }, "automatic_posted_quantity": { "type": "number" }, "calculated_change": { "type": "number" }, "balance_change": { "type": "number" } }, "required": [ "local_today", "earned_through", "period_days", "eligible_days", "credited_days", "cumulative_quantity", "full_eligible_quantity", "rounding", "basis", "already_awarded", "automatic_posted_quantity", "calculated_change", "balance_change" ], "additionalProperties": false }, "LeaveAccrualState": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "rule": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9]+$" }, "policy": { "$ref": "#/components/schemas/LeaveAccrualPublicPolicy" }, "work_pattern_version": { "type": "string", "pattern": "^[0-9]+$" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "policy", "work_pattern_version", "created_at" ], "additionalProperties": false } ] }, "calculation": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LeaveAccrualCalculation" } ] }, "posting_blocker": { "enum": [ null, "not_configured", "policy_paused", "worker_inactive", "approver_access_changed", "work_pattern_changed", "worker_not_commissioned" ] } }, "required": [ "account", "rule", "calculation", "posting_blocker" ], "additionalProperties": false }, "LeaveAccrualReview": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "policy": { "$ref": "#/components/schemas/LeaveAccrualPolicy" }, "previous_rule": { "type": "string", "pattern": "^[0-9]+$" }, "calculation": { "$ref": "#/components/schemas/LeaveAccrualCalculation" }, "balance_after": { "type": "number" }, "worker_active": { "type": "boolean" }, "worker_revision": { "type": "string", "pattern": "^[0-9]+$" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "account", "policy", "previous_rule", "calculation", "balance_after", "worker_active", "worker_revision", "review_token" ], "additionalProperties": false }, "LeaveAccrualResult": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/LeaveAccount" }, "rule_id": { "type": "string", "pattern": "^[0-9]+$" }, "entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "balance_change": { "type": "number" } }, "required": [ "account", "rule_id", "entry_id", "balance_change" ], "additionalProperties": false }, "ResourceChangeInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "credential" }, "input": { "type": "object", "additionalProperties": false, "properties": { "user_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "dbs", "level3", "first_aid", "medication", "driving", "restraint" ] }, "status": { "type": "string", "enum": [ "valid", "in_progress", "expired", "missing" ] }, "expires_on": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date" } ] }, "deadline": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date" } ] } }, "required": [ "user_id", "kind", "status", "expires_on", "deadline" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "attendance_correction" }, "input": { "type": "object", "additionalProperties": false, "properties": { "attendance_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "time_in": { "type": "string", "format": "date-time" }, "time_out": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer", "minimum": 0, "maximum": 2880 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "attendance_id", "time_in", "time_out", "break_minutes", "reason" ] } }, "required": [ "kind", "input" ] }, { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "attendance_approval" }, "input": { "type": "object", "additionalProperties": false, "properties": { "attendance_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } }, "required": [ "attendance_ids" ] } }, "required": [ "kind", "input" ] } ] }, "ResourceChangeReview": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "review_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "kind": { "const": "credential" }, "before": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "valid", "in_progress", "expired", "missing" ] }, "expires_on": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date" } ] }, "deadline": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date" } ] } }, "required": [ "id", "status", "expires_on", "deadline" ] } ] }, "after": { "type": "object", "additionalProperties": false, "properties": { "user_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "dbs", "level3", "first_aid", "medication", "driving", "restraint" ] }, "status": { "type": "string", "enum": [ "valid", "in_progress", "expired", "missing" ] }, "expires_on": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date" } ] }, "deadline": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date" } ] } }, "required": [ "user_id", "kind", "status", "expires_on", "deadline" ] } }, "required": [ "review_id", "expires_at", "kind", "before", "after" ] }, { "type": "object", "additionalProperties": false, "properties": { "review_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "kind": { "const": "attendance_correction" }, "before": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "location_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "time_in": { "type": "string", "format": "date-time" }, "time_out": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "break_minutes": { "type": "integer" }, "approval_status": { "type": "string" }, "shift_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "reason": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "user_id", "location_id", "time_in", "time_out", "break_minutes", "approval_status", "shift_id", "reason" ] }, "after": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "location_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "time_in": { "type": "string", "format": "date-time" }, "time_out": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "break_minutes": { "type": "integer" }, "approval_status": { "type": "string" }, "shift_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "reason": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "user_id", "location_id", "time_in", "time_out", "break_minutes", "approval_status", "shift_id", "reason" ] } }, "required": [ "review_id", "expires_at", "kind", "before", "after" ] }, { "type": "object", "additionalProperties": false, "properties": { "review_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "kind": { "const": "attendance_approval" }, "before": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "location_id": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "uuid" } ] }, "time_in": { "type": "string", "format": "date-time" }, "time_out": { "oneOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "break_minutes": { "type": "integer" }, "approval_status": { "type": "string" } }, "required": [ "id", "user_id", "location_id", "time_in", "time_out", "break_minutes", "approval_status" ] } }, "after": { "type": "object", "additionalProperties": false, "properties": { "attendance_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "approval_status": { "const": "approved" } }, "required": [ "attendance_ids", "approval_status" ] } }, "required": [ "review_id", "expires_at", "kind", "before", "after" ] } ] }, "ResourceChangeReceipt": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "applied_at": { "type": "string", "format": "date-time" }, "kind": { "const": "credential" }, "credential_id": { "type": "string", "format": "uuid" }, "row_revision": { "type": "string", "pattern": "^[1-9][0-9]*$" } }, "required": [ "request_id", "review_id", "applied_at", "kind", "credential_id", "row_revision" ] }, { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "applied_at": { "type": "string", "format": "date-time" }, "kind": { "const": "attendance_correction" }, "attendance_id": { "type": "string", "format": "uuid" }, "approval_status": { "const": "pending" } }, "required": [ "request_id", "review_id", "applied_at", "kind", "attendance_id", "approval_status" ] }, { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "applied_at": { "type": "string", "format": "date-time" }, "kind": { "const": "attendance_approval" }, "approved_count": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "request_id", "review_id", "applied_at", "kind", "approved_count" ] } ] }, "CredentialErasureCounts": { "type": "object", "additionalProperties": false, "required": [ "credentials", "audit", "commands", "reviews", "invalidations" ], "properties": { "credentials": { "type": "integer", "minimum": 0, "maximum": 10000 }, "audit": { "type": "integer", "minimum": 0, "maximum": 10000 }, "commands": { "type": "integer", "minimum": 0, "maximum": 10000 }, "reviews": { "type": "integer", "minimum": 0, "maximum": 10000 }, "invalidations": { "type": "integer", "minimum": 0, "maximum": 10000 } } }, "CredentialErasureReview": { "type": "object", "additionalProperties": false, "required": [ "case_id", "subject_id", "offboarded_at", "retention_until", "blockers", "enabled", "retained_data", "full_erasure_completed", "case_closed_by_action", "review_token", "scope", "counts", "policies" ], "properties": { "case_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": [ "integer", "null" ], "minimum": 1 }, "offboarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "retention_until": { "type": [ "string", "null" ], "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "retained_data": { "type": "array", "items": { "type": "string" } }, "full_erasure_completed": { "type": "boolean", "const": false }, "case_closed_by_action": { "type": "boolean", "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "scope": { "type": "string", "const": "linked_credential_records_v1" }, "counts": { "$ref": "#/components/schemas/CredentialErasureCounts" }, "policies": { "type": "array", "maxItems": 3, "items": { "type": "object", "additionalProperties": false, "required": [ "category", "revision", "retention_days", "anchor", "anchor_at", "retention_until", "policy_reference" ], "properties": { "category": { "type": "string", "enum": [ "credentials", "audit", "integrations" ] }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "anchor": { "type": "string", "enum": [ "event_at", "offboarded_at" ] }, "anchor_at": { "type": [ "string", "null" ], "format": "date-time" }, "retention_until": { "type": [ "string", "null" ], "format": "date-time" }, "policy_reference": { "type": "string" } } } } } }, "CredentialErasureResult": { "type": "object", "additionalProperties": false, "required": [ "case_id", "subject_id", "authorized_at", "state", "sync_generation", "retained_data", "full_erasure_completed", "case_closed_by_action" ], "properties": { "case_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": [ "integer", "null" ], "minimum": 1 }, "authorized_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "const": "linked_credential_records_removed" }, "sync_generation": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "retained_data": { "type": "array", "items": { "type": "string" } }, "full_erasure_completed": { "type": "boolean", "const": false }, "case_closed_by_action": { "type": "boolean", "const": false }, "removed_counts": { "$ref": "#/components/schemas/CredentialErasureCounts" } } }, "AttendanceHistoryErasureCounts": { "type": "object", "additionalProperties": false, "required": [ "commands", "reviews" ], "properties": { "commands": { "type": "integer", "minimum": 0, "maximum": 10000 }, "reviews": { "type": "integer", "minimum": 0, "maximum": 10000 } } }, "AttendanceHistoryErasureReview": { "type": "object", "additionalProperties": false, "required": [ "case_id", "subject_id", "offboarded_at", "retention_until", "blockers", "enabled", "retained_data", "full_erasure_completed", "case_closed_by_action", "review_token", "scope", "counts", "policies" ], "properties": { "case_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": [ "integer", "null" ], "minimum": 1 }, "offboarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "retention_until": { "type": [ "string", "null" ], "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "retained_data": { "type": "array", "items": { "type": "string" } }, "full_erasure_completed": { "type": "boolean", "const": false }, "case_closed_by_action": { "type": "boolean", "const": false }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "scope": { "type": "string", "const": "attendance_command_history_v1" }, "counts": { "$ref": "#/components/schemas/AttendanceHistoryErasureCounts" }, "policies": { "type": "array", "maxItems": 3, "items": { "type": "object", "additionalProperties": false, "required": [ "category", "revision", "retention_days", "anchor", "anchor_at", "retention_until", "policy_reference" ], "properties": { "category": { "type": "string", "enum": [ "attendance", "audit", "integrations" ] }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 36500 }, "anchor": { "type": "string", "enum": [ "event_at", "offboarded_at" ] }, "anchor_at": { "type": [ "string", "null" ], "format": "date-time" }, "retention_until": { "type": [ "string", "null" ], "format": "date-time" }, "policy_reference": { "type": "string" } } } } } }, "AttendanceHistoryErasureResult": { "type": "object", "additionalProperties": false, "required": [ "case_id", "subject_id", "authorized_at", "state", "sync_generation", "retained_data", "full_erasure_completed", "case_closed_by_action" ], "properties": { "case_id": { "type": "string", "format": "uuid" }, "subject_id": { "type": [ "integer", "null" ], "minimum": 1 }, "authorized_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "const": "attendance_command_history_removed" }, "sync_generation": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "retained_data": { "type": "array", "items": { "type": "string" } }, "full_erasure_completed": { "type": "boolean", "const": false }, "case_closed_by_action": { "type": "boolean", "const": false }, "removed_counts": { "$ref": "#/components/schemas/AttendanceHistoryErasureCounts" } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry a write safely for 24 hours. Reuse the same key, body, path and If-Match. A different request with the same key returns 409. Keys are isolated by organization and authenticated principal. Replays still consume quota.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } }, "Workspace": { "name": "X-ShiftForest-Workspace", "in": "header", "required": false, "description": "Company UUID for a verified human session. Must identify an active login membership. Not supported with API keys. Keep one client and replica per Auth account and selected workspace.", "schema": { "type": "string", "format": "uuid" } } } }, "paths": { "/users/creation-context": { "post": { "operationId": "prepare_worker_creation", "description": "Requires users:read and users:write on an independent integration, or an active human administrator. Creator-bound keys cannot use worker commands. Editing pay, weekly hours or payroll codes additionally requires pay:read and pay:write. The integration must have access to every current and proposed workplace. Account administrators/managers require the workspace workflow. No email change, account role, password, PIN, login enablement, invitation or ownership change is supported. Creation requires explicit rate (integer currency minor units), weekly hours, current numeric job role and at least one numeric workplace. It also requires pay:read and pay:write. request_id becomes the workforce UUID and must not already belong to an Auth user or another record. No Auth user or email is created. login_enabled is false. Omit employee_code to generate one; supplied payroll codes must be unique within the organization. Prepare the review without changing records. Do not reuse a context after related records change. ", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "profile" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "profile": { "$ref": "#/components/schemas/WorkerProfile" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerProfileReview" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed review, duplicate identity/email/payroll code, or conflicting command/receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/users/{id}/profile-context": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "prepare_worker_profile", "description": "Requires users:read and users:write on an independent integration, or an active human administrator. Creator-bound keys cannot use worker commands. Editing pay, weekly hours or payroll codes additionally requires pay:read and pay:write. The integration must have access to every current and proposed workplace. Account administrators/managers require the workspace workflow. No email change, account role, password, PIN, login enablement, invitation or ownership change is supported. A current If-Match is required for both context and mutation. Removing a workplace with future shifts is rejected. Prepare the review without changing records. Do not reuse a context after related records change. ", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Current GET /users/{id} ETag. Stale profile returns 412; review again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "changes" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "changes": { "$ref": "#/components/schemas/WorkerProfileChanges" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerProfileReview" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed review, duplicate identity/email/payroll code, or conflicting command/receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{id}/profile": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "$ref": "#/components/parameters/Workspace" } ], "patch": { "operationId": "update_worker_profile", "description": "Requires users:read and users:write on an independent integration, or an active human administrator. Creator-bound keys cannot use worker commands. Editing pay, weekly hours or payroll codes additionally requires pay:read and pay:write. The integration must have access to every current and proposed workplace. Account administrators/managers require the workspace workflow. No email change, account role, password, PIN, login enablement, invitation or ownership change is supported. A current If-Match is required for both context and mutation. Removing a workplace with future shifts is rejected. Mutations require Idempotency-Key and a reviewed token from the corresponding context, using exactly the same request_id/details. Human writes require a recently verified authenticator. Durable command UUIDs survive 24-hour generic receipt expiry; exact retries must retain path, body, review_token and If-Match. Reuse with different data returns 409. Current authority and workplace access are rechecked before replay. Returned versions reflect the original command and may be stale; GET the worker before further changes. Rate changes remain unverified for payroll until separately reviewed. ", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "Current GET /users/{id} ETag. Stale profile returns 412; review again." }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Retry a write safely for 24 hours. Reuse the same key, body, path and If-Match. A different request with the same key returns 409. Keys are isolated by organization and authenticated principal. Replays still consume quota.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "changes", "review_token" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "changes": { "$ref": "#/components/schemas/WorkerProfileChanges" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerUpdated" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted worker version at command completion" }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed review, duplicate identity/email/payroll code, or conflicting command/receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shifts": { "get": { "operationId": "list_shifts", "description": "Unknown and duplicate query parameters return 400. Shift cursors preserve the journal snapshot across pages. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque tenant-signed cursor. Keep list filters and limit unchanged on continuation.", "schema": { "type": "string" } }, { "name": "external_namespace", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Supply both external lookup parameters.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "", "schema": { "type": "string", "format": "date-time" } }, { "name": "match", "in": "query", "required": false, "description": "Half-open intervals; touching endpoints do not overlap.", "schema": { "type": "string", "enum": [ "overlaps", "starts_within" ], "default": "overlaps" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated drafts,deleted,open; otherwise only published, non-deleted, assigned shifts.", "schema": { "type": "string" } }, { "name": "location", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1 } }, { "name": "user", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shift" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_shift", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "location", "shift_type", "start_time", "end_time" ], "properties": { "user": { "type": [ "integer", "null" ], "minimum": 1 }, "location": { "type": "integer", "minimum": 1 }, "role": { "type": [ "integer", "null" ], "minimum": 1 }, "minutes_break": { "type": "integer", "minimum": 0 }, "published": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 10000 }, "shift_type": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 }, "start_time": { "type": "string", "format": "date-time", "description": "ISO 8601 with explicit offset; stored in UTC." }, "end_time": { "type": "string", "format": "date-time", "description": "ISO 8601 with explicit offset; stored in UTC." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/shifts/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_shifts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update_shifts", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "user": { "type": [ "integer", "null" ], "minimum": 1 }, "location": { "type": "integer", "minimum": 1 }, "role": { "type": [ "integer", "null" ], "minimum": 1 }, "minutes_break": { "type": "integer", "minimum": 0 }, "published": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 10000 }, "shift_type": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 }, "start_time": { "type": "string", "format": "date-time", "description": "ISO 8601 with explicit offset; stored in UTC." }, "end_time": { "type": "string", "format": "date-time", "description": "ISO 8601 with explicit offset; stored in UTC." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_shift", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users": { "get": { "operationId": "list_users", "description": "Unknown and duplicate query parameters return 400. Shift cursors preserve the journal snapshot across pages. Catalogue pages exclude records inserted after the first page using a transactionally ordered company sequence; existing records remain live and current access is rechecked. Imported numeric IDs do not bypass this boundary. Pre-upgrade catalogue cursors return 400 and must restart from the first page. Keep every query parameter unchanged while following a cursor. Combine search (case-insensitive literal substring of first name plus last name), location (authorized public numeric workplace ID) and level (workspace access level). Filters use AND. Search is trimmed and limited to 80 Unicode code points; percent, underscore and backslash have no wildcard meaning. Unknown, foreign or unauthorized locations produce an empty page. Membership and names remain live between pages; insertion fencing is not a frozen directory snapshot. This route retains administrator/integration authorization; it does not grant manager or employee directory access. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque tenant-signed cursor. Keep list filters and limit unchanged on continuation.", "schema": { "type": "string" } }, { "name": "external_namespace", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Supply both external lookup parameters.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Trimmed literal name substring, 1\u201380 Unicode code points; no control characters. Does not search email, pay or notes.", "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "location", "in": "query", "required": false, "description": "Public numeric workplace ID; only authorized memberships match.", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "level", "in": "query", "required": false, "description": "Workspace access level, not the employee job role.", "schema": { "type": "string", "enum": [ "admin", "manager", "employee" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryUser" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_worker_record", "description": "Requires users:read and users:write on an independent integration, or an active human administrator. Creator-bound keys cannot use worker commands. Editing pay, weekly hours or payroll codes additionally requires pay:read and pay:write. The integration must have access to every current and proposed workplace. Account administrators/managers require the workspace workflow. No email change, account role, password, PIN, login enablement, invitation or ownership change is supported. Creation requires explicit rate (integer currency minor units), weekly hours, current numeric job role and at least one numeric workplace. It also requires pay:read and pay:write. request_id becomes the workforce UUID and must not already belong to an Auth user or another record. No Auth user or email is created. login_enabled is false. Omit employee_code to generate one; supplied payroll codes must be unique within the organization. Mutations require Idempotency-Key and a reviewed token from the corresponding context, using exactly the same request_id/details. Human writes require a recently verified authenticator. Durable command UUIDs survive 24-hour generic receipt expiry; exact retries must retain path, body, review_token and If-Match. Reuse with different data returns 409. Current authority and workplace access are rechecked before replay. Returned versions reflect the original command and may be stale; GET the worker before further changes. Rate changes remain unverified for payroll until separately reviewed. ", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Retry a write safely for 24 hours. Reuse the same key, body, path and If-Match. A different request with the same key returns 409. Keys are isolated by organization and authenticated principal. Replays still consume quota.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "profile", "review_token" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "profile": { "$ref": "#/components/schemas/WorkerProfile" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "201": { "description": "Created workforce record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkerCreated" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted worker version at command completion" }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed review, duplicate identity/email/payroll code, or conflicting command/receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/users/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_users", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryUser" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update_users", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } }, "required": [ "id", "version", "external_ids" ] } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/locations": { "get": { "operationId": "list_locations", "description": "Unknown and duplicate query parameters return 400. Shift cursors preserve the journal snapshot across pages. Catalogue pages exclude records inserted after the first page using a transactionally ordered company sequence; existing records remain live and current access is rechecked. Imported numeric IDs do not bypass this boundary. Pre-upgrade catalogue cursors return 400 and must restart from the first page. Keep every query parameter unchanged while following a cursor. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque tenant-signed cursor. Keep list filters and limit unchanged on continuation.", "schema": { "type": "string" } }, { "name": "external_namespace", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Supply both external lookup parameters.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } }, "required": [ "id", "version", "external_ids" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/locations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_locations", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } }, "required": [ "id", "version", "external_ids" ] } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update_locations", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } }, "required": [ "id", "version", "external_ids" ] } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/roles": { "get": { "operationId": "list_roles", "description": "Unknown and duplicate query parameters return 400. Shift cursors preserve the journal snapshot across pages. Catalogue pages exclude records inserted after the first page using a transactionally ordered company sequence; existing records remain live and current access is rechecked. Imported numeric IDs do not bypass this boundary. Pre-upgrade catalogue cursors return 400 and must restart from the first page. Keep every query parameter unchanged while following a cursor. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque tenant-signed cursor. Keep list filters and limit unchanged on continuation.", "schema": { "type": "string" } }, { "name": "external_namespace", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Supply both external lookup parameters.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } }, "required": [ "id", "version", "external_ids" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/roles/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_roles", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "version": { "type": "integer", "minimum": 1 }, "external_ids": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxProperties": 32 } }, "required": [ "id", "version", "external_ids" ] } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shifts/changes": { "get": { "operationId": "shift_changes", "description": "Complete baseline plus every later change, including drafts/open/deleted records. Store the checkpoint only after committing the entire page. Idle feeds return a non-null next_cursor. Event snapshots and tombstones are retained indefinitely (at least 90 days). Independent integration cursors are bound to the integration and its effective workplace permissions. Rotation with unchanged permissions retains the cursor. When a shift moves outside authorized workplaces, access.removed returns only id, version and deleted:true; remove its active replica view and replace the previous payload with this minimal tombstone. Another principal or changed workplace permissions requires a fresh replica; do not reuse an old cursor. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque tenant-signed cursor. Keep list filters and limit unchanged on continuation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/shifts/{id}/publish": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "shift_publish", "description": "Atomic lifecycle action with If-Match. Clocking and acknowledgement require a verified Supabase user session. Manager on-behalf actions require recent MFA and a reason of at least 10 characters. Clocking retries must reuse request_id and the exact body/version. Static NFC badge IDs are not proof. Geofence is opt-in device-reported position, not network verification. Approval requires a different manager. Active attendance must be clocked out before cancellation.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 2000 }, "method": { "type": "string", "enum": [ "qr", "nfc", "geofence", "manager" ] }, "terminal_id": { "type": "string", "format": "uuid" }, "stamp": { "type": "integer", "description": "Fresh terminal timestamp in milliseconds" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracy": { "type": "number" }, "position_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" }, "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shifts/{id}/acknowledge": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "shift_acknowledge", "description": "Atomic lifecycle action with If-Match. Clocking and acknowledgement require a verified Supabase user session. Manager on-behalf actions require recent MFA and a reason of at least 10 characters. Clocking retries must reuse request_id and the exact body/version. Static NFC badge IDs are not proof. Geofence is opt-in device-reported position, not network verification. Approval requires a different manager. Active attendance must be clocked out before cancellation.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 2000 }, "method": { "type": "string", "enum": [ "qr", "nfc", "geofence", "manager" ] }, "terminal_id": { "type": "string", "format": "uuid" }, "stamp": { "type": "integer", "description": "Fresh terminal timestamp in milliseconds" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracy": { "type": "number" }, "position_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" }, "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shifts/{id}/clock-in": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "shift_clock_in", "description": "Atomic lifecycle action with If-Match. Clocking and acknowledgement require a verified Supabase user session. Manager on-behalf actions require recent MFA and a reason of at least 10 characters. Clocking retries must reuse request_id and the exact body/version. Static NFC badge IDs are not proof. Geofence is opt-in device-reported position, not network verification. Approval requires a different manager. Active attendance must be clocked out before cancellation.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 2000 }, "method": { "type": "string", "enum": [ "qr", "nfc", "geofence", "manager" ] }, "terminal_id": { "type": "string", "format": "uuid" }, "stamp": { "type": "integer", "description": "Fresh terminal timestamp in milliseconds" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracy": { "type": "number" }, "position_at": { "type": "string", "format": "date-time" } }, "required": [ "request_id", "method" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" }, "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shifts/{id}/clock-out": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "shift_clock_out", "description": "Atomic lifecycle action with If-Match. Clocking and acknowledgement require a verified Supabase user session. Manager on-behalf actions require recent MFA and a reason of at least 10 characters. Clocking retries must reuse request_id and the exact body/version. Static NFC badge IDs are not proof. Geofence is opt-in device-reported position, not network verification. Approval requires a different manager. Active attendance must be clocked out before cancellation.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 2000 }, "method": { "type": "string", "enum": [ "qr", "nfc", "geofence", "manager" ] }, "terminal_id": { "type": "string", "format": "uuid" }, "stamp": { "type": "integer", "description": "Fresh terminal timestamp in milliseconds" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracy": { "type": "number" }, "position_at": { "type": "string", "format": "date-time" } }, "required": [ "request_id", "method" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" }, "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shifts/{id}/approve": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "shift_approve", "description": "Atomic lifecycle action with If-Match. Clocking and acknowledgement require a verified Supabase user session. Manager on-behalf actions require recent MFA and a reason of at least 10 characters. Clocking retries must reuse request_id and the exact body/version. Static NFC badge IDs are not proof. Geofence is opt-in device-reported position, not network verification. Approval requires a different manager. Active attendance must be clocked out before cancellation.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 2000 }, "method": { "type": "string", "enum": [ "qr", "nfc", "geofence", "manager" ] }, "terminal_id": { "type": "string", "format": "uuid" }, "stamp": { "type": "integer", "description": "Fresh terminal timestamp in milliseconds" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracy": { "type": "number" }, "position_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" }, "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shifts/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "shift_cancel", "description": "Atomic lifecycle action with If-Match. Clocking and acknowledgement require a verified Supabase user session. Manager on-behalf actions require recent MFA and a reason of at least 10 characters. Clocking retries must reuse request_id and the exact body/version. Static NFC badge IDs are not proof. Geofence is opt-in device-reported position, not network verification. Approval requires a different manager. Active attendance must be clocked out before cancellation.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Quoted current version; stale writes return 412." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 2000 }, "method": { "type": "string", "enum": [ "qr", "nfc", "geofence", "manager" ] }, "terminal_id": { "type": "string", "format": "uuid" }, "stamp": { "type": "integer", "description": "Fresh terminal timestamp in milliseconds" }, "nonce": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "accuracy": { "type": "number" }, "position_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shift" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource version" }, "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/locations/{id}/on-shift-now": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "on_shift_now", "description": "Location manager/admin only. Actual open attendance, including overdue clock-outs, is separate from current scheduled staff without an active clock at this home. Refresh for current state; this list is not a historical snapshot. Both arrays share one cursor and page limit. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "scheduled_not_clocked_in", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shift_id": { "type": [ "integer", "null" ] }, "attendance_id": { "type": [ "integer", "null" ] }, "clocked_in_at": { "type": [ "string", "null" ], "format": "date-time" }, "clocked_in_at_unix": { "type": [ "number", "null" ] }, "method": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "clocked_in", "scheduled_not_clocked_in" ] } } } }, "scheduled_not_clocked_in": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shift_id": { "type": [ "integer", "null" ] }, "attendance_id": { "type": [ "integer", "null" ] }, "clocked_in_at": { "type": [ "string", "null" ], "format": "date-time" }, "clocked_in_at_unix": { "type": [ "number", "null" ] }, "method": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "clocked_in", "scheduled_not_clocked_in" ] } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale If-Match version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Attempt quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rotas": { "post": { "operationId": "ensure_rota", "description": "Create/retrieve a home operational rota of 1\u201331 inclusive dates. Rota IDs are UUIDs; imported resource IDs remain numeric. Manager access required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "location", "from_date", "to_date" ], "properties": { "location": { "type": "integer", "minimum": 1 }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "integer", "minimum": 1 }, "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" }, "id": { "type": "string", "format": "uuid" } } } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale If-Match version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Attempt quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/rotas/{id}/validate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "validate_rota", "description": "Manager-only current preview for up to 31 operational dates and 1000 shifts. Returns validation, complete numeric shift IDs and versions, draft_count and a principal-bound review_token. Fetch the listed shifts for display before submitting the token to publish. Oversized periods fail without a partial preview.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotaReviewedValidation" } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Invalid dates, inaccessible rota or failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Publication blocked; response contains published=false and validation findings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale If-Match version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Attempt quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/rotas/{id}/publish": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "publish_rota", "description": "Manager-only atomic publication of the reviewed operational period. Requires the exact review_token from a fresh validation and a durable Idempotency-Key. Missing preconditions return 428; changed shifts, policy or validation return 409 with no publication. Retry identical commands with the same key for 24 hours; do not revalidate automatically after an ambiguous response. v1 compatibility writes retain their original behavior.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "review_token" ], "additionalProperties": false, "properties": { "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotaPublication" } } }, "headers": { "Idempotency-Replayed": { "description": "true when replaying a stored successful response", "schema": { "type": "string", "enum": [ "true" ] } } } }, "400": { "description": "Invalid dates, inaccessible rota or failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Rota validation refused publication (published=false with findings) or another domain conflict", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RotaPublication" } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale If-Match version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Attempt quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Retry a write safely for 24 hours. Reuse the same key, body, path and If-Match. A different request with the same key returns 409. Keys are isolated by organization and authenticated principal. Replays still consume quota.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ] } }, "/organization": { "get": { "operationId": "get_organization", "summary": "Discover authenticated organization", "responses": { "200": { "description": "Authenticated discovery", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "timezone", "currency", "api_version", "scopes", "key_expires_at", "principal_type", "integration_id", "location_access" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "api_version": { "const": "v2" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "key_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "principal_type": { "enum": [ "human", "creator_bound_key", "integration" ] }, "integration_id": { "type": [ "string", "null" ], "format": "uuid" }, "location_access": { "type": [ "object", "null" ], "required": [ "all_locations", "locations" ], "properties": { "all_locations": { "type": "boolean" }, "locations": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": false } } } } } }, "401": { "description": "Invalid or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale If-Match version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": " Includes principal_type, integration_id and the effective workplace scope. Bind a local replica to this identity, scopes and location_access before syncing; do not reuse personnel data from a different principal." }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/capabilities": { "get": { "operationId": "get_capabilities", "summary": "Discover authenticated capabilities", "responses": { "200": { "description": "Authenticated discovery", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "idempotency_retention_hours", "pagination", "changes_resources", "scopes", "payroll_calculation", "document_signing", "human_attendance_session_required", "principal_type", "integration_id", "location_access", "resources", "request_acceptance_session_required", "limits" ], "properties": { "version": { "const": "v2" }, "idempotency_retention_hours": { "const": 24 }, "pagination": { "const": "cursor" }, "changes_resources": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "payroll_calculation": { "const": false }, "document_signing": { "const": false }, "human_attendance_session_required": { "const": true }, "principal_type": { "enum": [ "human", "creator_bound_key", "integration" ] }, "integration_id": { "type": [ "string", "null" ], "format": "uuid" }, "location_access": { "type": [ "object", "null" ], "required": [ "all_locations", "locations" ], "properties": { "all_locations": { "type": "boolean" }, "locations": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": false }, "resources": { "type": "array", "items": { "type": "string" } }, "request_acceptance_session_required": { "const": true }, "recovery_decisions_session_required": { "const": true }, "recovery_status_scope": { "const": "recovery:read" }, "recovery_status_polling": { "const": true }, "limits": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1 } }, "privacy_session_required": { "const": true }, "privacy_automatic_hr_erasure": { "const": false }, "privacy_export_max_days": { "const": 366 }, "privacy_export_max_bytes": { "const": 8388608 }, "leave_entitlement_ledger": { "const": true }, "leave_partial_days": { "const": true }, "leave_automatic_accrual": { "const": true }, "leave_entitlement_write_session_required": { "const": true }, "leave_policy_amendments": { "const": true }, "staffing_evidence": { "const": true }, "staffing_evidence_session_required": { "const": true }, "staffing_evidence_public_sharing": { "const": false }, "leave_custom_times": { "const": true }, "leave_pending_withdrawal": { "const": true }, "leave_ambiguous_local_times": { "const": "rejected" }, "leave_own_record_read": { "const": true }, "private_files": { "type": "boolean" }, "private_files_session_required": { "type": "boolean" }, "private_files_public_sharing": { "type": "boolean" }, "attendance_summary": { "const": true }, "attendance_summary_maximum_records": { "const": 100000 }, "dashboard_attention": { "type": "boolean", "const": true }, "browser_push_devices": { "const": true, "description": "Own human-session device controls are supported. GET /notifications/push/devices reports whether enrollment is configured." }, "user_directory_filters": { "type": "array", "items": { "type": "string", "enum": [ "search", "location", "level" ] }, "description": "Supported worker directory filters." }, "team_summary": { "type": "boolean" }, "team_directory": { "type": "boolean" }, "directory_search": { "type": "boolean" }, "setup_progress": { "type": "boolean" }, "delegated_staffing_roles": { "type": "boolean", "const": true }, "delegation_requires_human_session": { "type": "boolean", "const": true } } } } } }, "401": { "description": "Invalid or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope or authority", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Stale If-Match version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or configuration unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/availability": { "get": { "operationId": "list_availability", "description": "Requires availability:read and administrator integration authority. Inclusive from/to dates, at most 366 days. Keyset pages bound to query, company and principal; upper ID watermark excludes later creations. Existing rows remain live rather than a historical snapshot. No all-resource change feed is implied. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "user", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityDay" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_availability", "description": "Requires availability:write and administrator integration authority. Create one complete date; existing dates return 409. Company availability preferences apply. Reuse a durable Idempotency-Key after a timeout; receipts last 24 hours.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "user", "date", "intervals" ], "properties": { "user": { "type": "integer", "minimum": 1 }, "date": { "type": "string", "format": "date" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone captured for this date; defaults to the company timezone on creation." }, "intervals": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/AvailabilityInterval" }, "description": "Complete replacement, sorted server-side. Non-overlapping local wall-clock ranges; midnight is 24:00. Split overnight ranges across dates. Both occurrences of repeated DST clock times apply; nonexistent boundary times are rejected." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityDay" } } }, "headers": { "ETag": { "description": "Quoted monotonic resource version for If-Match", "schema": { "type": "string" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/availability/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_availability", "description": "Requires availability:read and administrator integration authority. Deleted and other-company dates return 404.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityDay" } } }, "headers": { "ETag": { "description": "Quoted monotonic resource version for If-Match", "schema": { "type": "string" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update_availability", "description": "Requires availability:write and administrator integration authority. Replaces all intervals for this date, preserving worker/date identity and detaching its repeating pattern. Requires the current If-Match version.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "intervals" ], "properties": { "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone captured for this date; defaults to the company timezone on creation." }, "intervals": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/AvailabilityInterval" }, "description": "Complete replacement, sorted server-side. Non-overlapping local wall-clock ranges; midnight is 24:00. Split overnight ranges across dates. Both occurrences of repeated DST clock times apply; nonexistent boundary times are rejected." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityDay" } } }, "headers": { "ETag": { "description": "Quoted monotonic resource version for If-Match", "schema": { "type": "string" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_availability", "description": "Requires availability:write and administrator integration authority. Removes the complete date from every interface. Requires current If-Match.", "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0 } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shift-requests/creation-context": { "get": { "operationId": "preview_shift_request", "description": "Requires shift_requests:read for scoped keys. Only the authenticated source employee can propose a future published shift change. Returns current source/target details and a principal-bound fingerprint; selecting a target does not create a request.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCreationContext" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "shift", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "kind", "in": "query", "required": true, "schema": { "enum": [ "drop", "swap" ] } }, { "name": "target_shift", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Required for swap; omitted for drop. Both employees must be assigned to the workplaces they would cover." } ] }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/shift-requests": { "get": { "operationId": "list_shift_requests", "description": "Requires shift_requests:read for scoped keys. Participants see their own requests; managers see requests at workplaces they manage. Default status=active includes pending/accepted. Historical lists require inclusive from/to operational rota dates (at most 93 days). Keyset cursors bind principal/company/query and exclude later creations; existing rows remain live. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShiftRequest" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "all", "pending", "accepted", "approved", "denied" ], "default": "active" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "location", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ] }, "post": { "operationId": "create_shift_request", "description": "Requires shift_requests:write for scoped keys. Caller must own the source shift. Send the exact current creation-context review_token and a durable request_id; same identity/payload replays the existing request without creating another. Reuse Idempotency-Key for exact HTTP replay for 24 hours. Requests remain on the rota until approved.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftRequest" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted monotonic request version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "shift", "kind", "review_token" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Persist one UUID per logical request, including across process restarts. Receipts remain with request history." }, "shift": { "type": "integer", "minimum": 1 }, "kind": { "enum": [ "drop", "swap" ] }, "target_shift": { "type": [ "integer", "null" ], "minimum": 1 }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "message": { "type": "string", "maxLength": 2000 } }, "allOf": [ { "if": { "properties": { "kind": { "const": "swap" } } }, "then": { "required": [ "target_shift" ], "properties": { "target_shift": { "type": "integer", "minimum": 1 } } } }, { "if": { "properties": { "kind": { "const": "drop" } } }, "then": { "properties": { "target_shift": { "type": "null" } } } } ] } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/shift-requests/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_shift_request", "description": "Requires shift_requests:read for scoped keys. Returns a minimized request, including retained closed decisions. Missing and unauthorized requests return 404.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftRequest" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted monotonic request version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shift-requests/{id}/review-context": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "review_shift_request", "description": "Requires shift_requests:read for scoped keys. Returns current authorized shift summaries, request version, permitted canonical decision values (accepted/approved/denied), consent_current and an opaque review_token. A source-only manager receives no target-shift details outside their scope. Reload after conflicts; retain the unsaved response.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestReviewContext" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted monotonic request version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shift-requests/{id}/accept": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "accept_shift_request", "description": "Requires shift_requests:write for scoped keys. Only the invited colleague authenticated through their own session can accept. API keys cannot attest employee consent, even with write scope. Acceptance records both current shift versions and the current workspace workflow policy. A changed shift or workflow policy requires renewed acceptance. Requires the current If-Match plus the matching principal-bound review-context token. Changed request version returns 412; changed shifts/policy return 409. Reload and review; never force an old decision.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftRequest" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted monotonic request version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "review_token" ], "properties": { "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "message": { "type": "string", "maxLength": 2000 } } } } } } } }, "/shift-requests/{id}/approve": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "approve_shift_request", "description": "Requires shift_requests:approve for scoped keys. Independent manager must manage both affected workplaces, be neither employee, and have current colleague acceptance for a swap. Approval rechecks attendance, availability, overlap, leave, hours, credentials and final staffing constraints. Failure rolls back every assignment and the request decision. Requires the current If-Match plus the matching principal-bound review-context token. Changed request version returns 412; changed shifts/policy return 409. Reload and review; never force an old decision.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftRequest" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted monotonic request version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "review_token" ], "properties": { "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "message": { "type": "string", "maxLength": 2000 } } } } } } } }, "/shift-requests/{id}/deny": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "deny_shift_request", "description": "Requires shift_requests:approve for scoped keys. The invited colleague or a location manager can decline/deny; an integration key additionally requires approve scope. Use cancel for the requestor\u2019s own request. Requires the current If-Match plus the matching principal-bound review-context token. Changed request version returns 412; changed shifts/policy return 409. Reload and review; never force an old decision.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftRequest" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted monotonic request version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "review_token" ], "properties": { "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "message": { "type": "string", "maxLength": 2000 } } } } } } } }, "/shift-requests/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "cancel_shift_request", "description": "Requires shift_requests:write for scoped keys. Only the requestor can cancel. Retains the decision and consent history; no physical delete endpoint is offered. Requires the current If-Match plus the matching principal-bound review-context token. Changed request version returns 412; changed shifts/policy return 409. Reload and review; never force an old decision.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftRequest" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted monotonic request version" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "review_token" ], "properties": { "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "message": { "type": "string", "maxLength": 2000 } } } } } } } }, "/attendance": { "get": { "operationId": "list_attendance", "description": "Requires attendance_history:read, with an independent integration or active administrator session. Start-time window [from,to), at most 93 days. Actual attendance workplace is authoritative; voided records are excluded unless requested. No device, network address or free-text notes. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "user", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "location", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "include_voided", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttendanceRecord" }, "maxItems": 250 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/attendance/{id}": { "get": { "operationId": "get_attendance", "description": "Requires attendance_history:read, with an independent integration or active administrator session. Start-time window [from,to), at most 93 days. Actual attendance workplace is authoritative; voided records are excluded unless requested. No device, network address or free-text notes. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceRecord" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource revision; this API is read-only." } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/leave": { "get": { "operationId": "list_leave", "description": "Requires leave:read, with an independent integration or active administrator session. Inclusive overlapping from/to dates, at most 366 days. Current workplace membership governs visibility; reasons and notes are omitted. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "user", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "denied" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveRecord" }, "maxItems": 250 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/leave/{id}": { "get": { "operationId": "get_leave", "description": "Requires leave:read, with an independent integration or active administrator session. Inclusive overlapping from/to dates, at most 366 days. Current workplace membership governs visibility; reasons and notes are omitted. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live. Active human requesters may also read their own exact leave record, including withdrawn_at. This does not grant access to other workers, collection reads, credentials or payroll.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveRecord" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource revision; this API is read-only." } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/credentials": { "get": { "operationId": "list_credentials", "description": "Requires credentials:read, with an independent integration or active administrator session. Current workplace membership governs visibility. Status is the recorded review status; evaluate expiry and deadline against your intended work date and approved policy. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "user", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "valid", "in_progress", "expired", "missing" ] } }, { "name": "expires_before", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialRecord" }, "maxItems": 250 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/credentials/{id}": { "get": { "operationId": "get_credentials", "description": "Requires credentials:read, with an independent integration or active administrator session. Current workplace membership governs visibility. Status is the recorded review status; evaluate expiry and deadline against your intended work date and approved policy. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecord" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource revision; this API is read-only." } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/payroll-exports": { "get": { "operationId": "list_payroll_exports", "description": "Requires payroll_exports:read plus pay:read and all workplaces, with an independent integration or active administrator session. Frozen reviewed exports only. Optional complete inclusive overlap window, at most 366 days. Exact money totals and fractional minutes are decimal strings. No provider certification is implied. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollExport" }, "maxItems": 250 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/payroll-exports/{id}": { "get": { "operationId": "get_payroll_exports", "description": "Requires payroll_exports:read plus pay:read and all workplaces, with an independent integration or active administrator session. Frozen reviewed exports only. Optional complete inclusive overlap window, at most 366 days. Exact money totals and fractional minutes are decimal strings. No provider certification is implied. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollExport" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted resource revision; this API is read-only." } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/payroll-exports/{id}/lines": { "get": { "operationId": "list_payroll_exports_lines", "description": "Requires payroll_exports:read plus pay:read and all workplaces, with an independent integration or active administrator session. Frozen reviewed exports only. Optional complete inclusive overlap window, at most 366 days. Exact money totals and fractional minutes are decimal strings. No provider certification is implied. Pages are bound to principal, permissions and unchanged filters, with an insertion watermark; updates to existing records remain live. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollExportLine" }, "maxItems": 250 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/sync/checkpoint": { "get": { "operationId": "create_read_checkpoint", "description": "Create this checkpoint BEFORE reading the initial resource pages. Store the resulting snapshot and checkpoint atomically, then catch up using /sync/changes. Independent integrations or active administrator sessions only; creator-bound keys are unsupported. Requires each selected resource read scope; attendance uses attendance_history:read and payroll additionally requires pay:read plus all workplaces.", "parameters": [ { "name": "resources", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated distinct resource names. Every resource requires its own read scope." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "cursor", "resources" ], "properties": { "cursor": { "type": "string" }, "resources": { "type": "array", "items": { "type": "string", "enum": [ "shifts", "users", "locations", "roles", "availability", "shift-requests", "attendance", "leave", "credentials", "payroll-exports" ] }, "uniqueItems": true } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Checkpoint invalid or visibility changed; clear and rebuild the replica", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/sync/changes": { "get": { "operationId": "list_resource_changes", "description": "Ordered minimal invalidations, not historical payloads. For refresh, GET the current resource by ID, apply your replica filters and upsert or remove it; an authorized 404 means remove. For remove, delete the cached record without fetching it. Commit effects and next_cursor atomically, including empty/idle pages. At most 1000 organization journal rows are scanned per request; empty pages may have has_more=true. Limit may change between polls. Cursors bind tenant, principal, selected resources, permissions and workplace visibility generation. HTTP 410 requires clearing the replica and rebuilding from a new checkpoint, including after membership changes or shift workplace moves. Events are retained without automatic pruning pending an approved retention policy. Webhooks are hints and are not emitted for this new feed. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "cursor", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8192 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceChange" }, "maxItems": 250 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" } } } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Checkpoint invalid or visibility changed; clear and rebuild the replica", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/recovery/status": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "list_recovery_status", "description": "Read-only status for a human workplace manager or independent integration with recovery:read. At most 93 inclusive shift rota dates. Workplace-scoped, no offer recipient list, manager reason or eligibility evidence. Poll this bounded endpoint; recovery is not yet a resource change-feed or webhook topic. Cursor is bound to credential, workspace, permissions and query; restart after a visibility change. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "location", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryStatusPage" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recovery/candidates": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "list_recovery_candidates", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Reviews eligible and ineligible candidates for a future published open shift without assigning anyone. Inspect remaining findings even when eligible; improvement does not certify full staffing. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "shift", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "stage", "in": "query", "required": false, "description": "Filter the complete eligible directory before pagination. Omit for all staffing categories.", "schema": { "enum": [ "internal", "bank", "agency" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCandidates" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recovery/prepare": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "prepare_recovery", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Review 1\u201320 distinct recipients in the same internal/bank/agency stage. They must already have linked active workspace accounts. Expiry must be at least one minute and at most 24 hours away, no later than shift start. Read-only preparation; can_launch must be true. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryLaunchReview" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryPreparation" } } } } } }, "/recovery/campaigns": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "launch_recovery", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Persist request_id, the complete reviewed body and Idempotency-Key before sending. Retry the identical command after a lost response. The API receipt lasts 24 hours and the domain command remains durable. A 409 requires a fresh review and a new decision. Manager launch/cancellation require recent MFA; acceptance is explicit employee consent. Permissions are checked before replay. Creates offers, reserves assignment and never assigns a worker. Changes to the shift cancel approval. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryLaunched" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryLaunchCommand" } } } } } }, "/recovery/campaigns/{campaign}": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_recovery_campaign", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Returns current responses and the cancellation review token. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person.", "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCampaign" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recovery/campaigns/{campaign}/cancel": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "cancel_recovery", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Persist request_id, the complete reviewed body and Idempotency-Key before sending. Retry the identical command after a lost response. The API receipt lasts 24 hours and the domain command remains durable. A 409 requires a fresh review and a new decision. Manager launch/cancellation require recent MFA; acceptance is explicit employee consent. Permissions are checked before replay. Cancels pending offers without changing assignment. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person.", "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCancelled" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCancelCommand" } } } } } }, "/recovery/offers": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "list_my_recovery_offers", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Lists pending unexpired offers only. Review each offer before acting; launch authority or eligibility may since have changed. This is a live collection, not a historical snapshot. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryOffers" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recovery/offers/{offer}": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_recovery_offer", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Provides available actions and an actor-bound review token; excludes other workers and credential details. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person.", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryOfferReview" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recovery/offers/{offer}/accept": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "accept_recovery_offer", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Persist request_id, the complete reviewed body and Idempotency-Key before sending. Retry the identical command after a lost response. The API receipt lasts 24 hours and the domain command remains durable. A 409 requires a fresh review and a new decision. Manager launch/cancellation require recent MFA; acceptance is explicit employee consent. Permissions are checked before replay. The first valid acceptance assigns the shift and closes other offers atomically. Rechecks availability, leave, overlap, contract limits and configured staffing rules. No new or worsened blocking finding is allowed. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person.", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryResponded" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryResponseCommand" } } } } } }, "/recovery/offers/{offer}/decline": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "decline_recovery_offer", "description": "Requires the person\u2019s own verified session; API keys cannot use this operation. Managers need current workplace access; employees can review/respond only to their own offers. Persist request_id, the complete reviewed body and Idempotency-Key before sending. Retry the identical command after a lost response. The API receipt lasts 24 hours and the domain command remains durable. A 409 requires a fresh review and a new decision. Manager launch/cancellation require recent MFA; acceptance is explicit employee consent. Permissions are checked before replay. Declines only this offer without changing assignment. Recovery campaign and offer IDs are UUIDs; shift, worker and workplace IDs are public numeric v2 IDs. Review tokens are opaque and must be presented unchanged. No offer sends external email unless delivery is enabled and the employee opted in. Never automatically accept or approve on behalf of a person.", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryResponded" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryResponseCommand" } } } } } }, "/recovery/simulate": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "simulate_staffing", "description": "Read-only comparison for a signed-in manager with access to the shift workplace. POST JSON {shift, workers} using numeric public IDs for one future published open shift and 1\u20135 distinct workers assigned to that workplace. Each option assigns the same shift to one worker independently. Shifts are bounded to 25 elapsed hours. Uses current canonical coverage/rules and recovery eligibility, with counts and redacted findings (first 50; totals remain complete). Basic eligibility failures return evaluated=false and proposed=null; a blocking rule failure still returns the evaluated proposal. Improved/worsened counts compare keyed blocking findings and their deficit amounts, not summed units. No writes, offers, notifications, cost forecast, consent or automatic assignment. snapshot_token identifies this result and is not an approval token. Current facts must be rechecked when offering or accepting. Rejects API keys, If-Match, Idempotency-Key and query parameters. Existing deficits may remain even when eligible=true.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffingSimulation" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review, eligibility or authority changed, or command identity reused for a different decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required If-Match, review_token or Idempotency-Key missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Worker unavailable in this organization or workplace access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; Allow lists the supported methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A JSON request body is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unsupported compatibility operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "shift", "workers" ], "properties": { "shift": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workers": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } } } } } } } }, "/privacy/requests": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "list_privacy_requests", "description": "Own requests require an active human membership. Workspace scope requires administrator access and recent MFA. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "scope", "in": "query", "schema": { "enum": [ "mine", "workspace" ], "default": "mine" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 }, "description": "Opaque signed cursor bound to this route, query, workspace and human principal. Preserve all filters and limit." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyCases" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "submit_privacy_request", "description": "Submit for yourself without requiring MFA. One active case of each kind per person; maximum 20 submissions per day. No automatic data change or email. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyCase" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "access", "correction", "erasure", "restriction", "objection", "portability" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 } }, "required": [ "request_id", "kind", "message" ], "additionalProperties": false } } } } } }, "/privacy/requests/{case_id}": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "get_privacy_request", "description": "Own request or verified administrator. next_event_cursor pages activity; completion evidence references are hidden from the subject. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 }, "description": "Opaque signed cursor bound to this route, query, workspace and human principal. Preserve all filters and limit." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyCaseDetail" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/privacy/requests/{case_id}/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "review_privacy_request", "description": "Prepare a reply/withdrawal as subject, or a decision as a different verified administrator. due_at is an explicitly reviewed deadline, never a legal default. Closing decisions require completion_reference. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyCaseReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "reply", "withdraw", "in_review", "awaiting_subject", "fulfilled", "partially_fulfilled", "denied" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "due_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completion_reference": { "anyOf": [ { "type": "string", "minLength": 10, "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "action", "message", "due_at", "completion_reference" ], "additionalProperties": false } } } } } }, "/privacy/requests/{case_id}/actions": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "apply_privacy_request_action", "description": "Apply the reviewed case action. Human-recorded fulfilment does not export or erase any data. Stale state returns 409. Maximum 100 events per case per day. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyCase" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "reply", "withdraw", "in_review", "awaiting_subject", "fulfilled", "partially_fulfilled", "denied" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "due_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completion_reference": { "anyOf": [ { "type": "string", "minLength": 10, "maxLength": 1000 }, { "type": "null" } ] }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "action", "message", "due_at", "completion_reference", "request_id", "review_token" ], "additionalProperties": false } } } } } }, "/privacy/subjects": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "list_privacy_subjects", "description": "Verified administrators may search current and former workers for rights intake and preservation. Does not restore login access. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 }, "description": "Opaque signed cursor bound to this route, query, workspace and human principal. Preserve all filters and limit." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacySubjects" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/privacy/intake/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "review_privacy_intake", "description": "Verified administrator records a request received through an independently verified process. Subject must be another worker in this workspace, including inactive workers. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyIntakeReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "integer", "minimum": 1 }, "kind": { "enum": [ "access", "correction", "erasure", "restriction", "objection", "portability" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "identity_reference": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "subject", "kind", "message", "identity_reference" ], "additionalProperties": false } } } } } }, "/privacy/intake": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "submit_privacy_intake", "description": "Explicit identity/process verification attestation required. Save evidence reference, not identity documents. No email, invitation or Auth change. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyCase" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "integer", "minimum": 1 }, "kind": { "enum": [ "access", "correction", "erasure", "restriction", "objection", "portability" ] }, "message": { "type": "string", "minLength": 10, "maxLength": 2000 }, "identity_reference": { "type": "string", "minLength": 10, "maxLength": 1000 }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "confirmed": { "const": true } }, "required": [ "subject", "kind", "message", "identity_reference", "request_id", "review_token", "confirmed" ], "additionalProperties": false } } } } } }, "/privacy/governance": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "get_privacy_governance", "description": "Verified administrator reads approved policies and paged holds. Separate flags expose automatic HR erasure and export-copy purge. Approval alone does not activate deletion. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "subject", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 }, "description": "Opaque signed cursor bound to this route, query, workspace and human principal. Preserve all filters and limit." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyGovernance" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/privacy/policies/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "review_privacy_policy", "description": "Current workspace owner with recent MFA reviews an approved retention policy. No default period. Profile/identity anchor is offboarded_at; exports use export_created_at; others allow event_at or offboarded_at. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyPolicyReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/PrivacyPolicyInput" } }, "required": [ "policy" ], "additionalProperties": false } } } } } }, "/privacy/policies": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "approve_privacy_policy", "description": "Record an explicitly approved policy. Rechecks owner and review before applying. Does not enable a purge worker. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyPolicyApproved" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/PrivacyPolicyInput" }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "confirmed": { "const": true } }, "required": [ "policy", "request_id", "review_token", "confirmed" ], "additionalProperties": false } } } } } }, "/privacy/holds/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "review_privacy_hold", "description": "Verified administrator places or releases a scoped preservation hold. Place uses a new hold_id, numeric subject and distinct categories; release uses existing hold_id with subject/categories null. Holds have no automatic expiry. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyHoldReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "place", "release" ] }, "hold_id": { "type": "string", "format": "uuid" }, "subject": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "categories": { "anyOf": [ { "type": "array", "items": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "minItems": 1, "maxItems": 12, "uniqueItems": true }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "action", "hold_id", "subject", "categories", "reason" ], "additionalProperties": false } } } } } }, "/privacy/holds": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "apply_privacy_hold", "description": "Apply the reviewed hold. Maximum 20 active holds per subject. Any active subject hold conservatively preserves composite personal export copies. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyHoldChanged" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "place", "release" ] }, "hold_id": { "type": "string", "format": "uuid" }, "subject": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "categories": { "anyOf": [ { "type": "array", "items": { "enum": [ "profile", "identity", "schedule", "attendance", "leave", "credentials", "payroll", "audit", "integrations", "exports", "backups", "documents" ] }, "minItems": 1, "maxItems": 12, "uniqueItems": true }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "action", "hold_id", "subject", "categories", "reason", "request_id", "review_token" ], "additionalProperties": false } } } } } }, "/privacy/exports/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "review_personal_export", "description": "Own active access/portability case or verified administrator; recent MFA required for both. Requires approved export policy. Inclusive company-local period up to 366 days; maximum 1000 records per section, 10000 total, 8 MiB, 64 matching payroll batches. Expiry must be 1 minute\u201324 hours ahead. Lists exact coverage/omissions; not a complete SAR. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyExportReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "case_id", "from", "to", "expires_at" ], "additionalProperties": false } } } } } }, "/privacy/exports": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "create_personal_export", "description": "Capture exact reviewed records once. Maximum 10 unpurged copies per subject. Case remains open. Source records, policy or case changes require a new review. Access expiry does not delete the retained copy. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyExportCreated" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date-time" }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "confirmed": { "const": true } }, "required": [ "case_id", "from", "to", "expires_at", "request_id", "review_token", "confirmed" ], "additionalProperties": false } } } } } }, "/privacy/requests/{case_id}/exports": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "list_personal_exports", "description": "Own case or verified administrator; recent MFA required for both. Shows available, expired, revoked and purged copies; no payload in list. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 }, "description": "Opaque signed cursor bound to this route, query, workspace and human principal. Preserve all filters and limit." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyExports" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/privacy/exports/{export_id}": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "download_personal_export", "description": "Own case or verified administrator; recent MFA required. Verify SHA-256 over exact UTF-8 canonical_json, byte count, organization_id and export id before saving. Expired/revoked/purged access returns 410. No public download links. Downloaded copies cannot be recalled. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyExportDownload" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/privacy/exports/{export_id}/revoke": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "revoke_personal_export", "description": "Revoke further download access using current revision and durable request_id. Does not erase stored payload or recall downloaded copies; retention and holds still apply. Human sessions only: API keys cannot impersonate a requester or decide privacy rights. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match. Persist request_id and exact body across retries; new payloads need new command IDs. Reviews are fresh reads and must be repeated after 409. All responses use Cache-Control: no-store. Privacy changes are polled through these endpoints, not included in the general workforce change feed.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyExportRevoked" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "request_id", "revision", "reason" ], "additionalProperties": false } } } } } }, "/leave-balances": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "listLeaveBalances", "description": "Read approved entitlement accounts overlapping up to 366 days. No account means unconfigured, not zero entitlement. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveBalances" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leave-ledger/{account_id}": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getLeaveLedger", "description": "Read immutable signed quantities and captured daily calculations. Free-text evidence, reasons and approver identities are omitted from this integration projection. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveLedger" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leave-policies/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "reviewLeavePolicy", "description": "Review an explicitly supplied policy and reconcile existing approved leave. Another administrator with recent MFA must approve; no statutory defaults or automatic accrual. Work patterns are Monday-first, non-overlapping local paid intervals; hours match configured minutes and day fractions total at most one per weekday. Patterns and units are retained unchanged after approval. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeavePolicyReview" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/LeaveEntitlementPolicy" } }, "required": [ "policy" ], "additionalProperties": false } } } } } }, "/leave-policies": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "createLeavePolicy", "description": "Create an approved entitlement account with opening entitlement and reconciled historical charges atomically. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveAccount" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/LeaveEntitlementPolicy" }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmed": { "const": true } }, "required": [ "policy", "request_id", "review_token", "confirmed" ], "additionalProperties": false } } } } } }, "/leave-ledger/{account_id}/adjustments/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "reviewLeaveAdjustment", "description": "Review manual accrual, correction, adjustment, proration, expiry or TOIL earned using independently approved calculations. Carryover out uses a negative quantity and a later account for the same worker, kind and unit. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveAdjustmentReview" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "accrual", "accrual_correction", "adjustment", "proration", "carryover_out", "expiry", "toil_earned" ] }, "quantity": { "type": "number", "minimum": -100000, "maximum": 100000 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "reference": { "type": "string", "minLength": 10, "maxLength": 500 }, "destination_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "kind", "quantity", "reason", "reference", "destination_id" ], "additionalProperties": false } } } } } }, "/leave-ledger/{account_id}/adjustments": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "applyLeaveAdjustment", "description": "Append an auditable adjustment; carryover debits and credits commit atomically. Quantity has at most four decimal places. No automatic legal formula is assumed. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveAdjustmentResult" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "accrual", "accrual_correction", "adjustment", "proration", "carryover_out", "expiry", "toil_earned" ] }, "quantity": { "type": "number", "minimum": -100000, "maximum": 100000 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "reference": { "type": "string", "minLength": 10, "maxLength": 500 }, "destination_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "quantity", "reason", "reference", "destination_id", "request_id", "review_token" ], "additionalProperties": false } } } } } }, "/leave-requests": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "post": { "operationId": "createLeaveRequest", "description": "Submit a pending request for yourself or a worker you manage. Morning is [00:00,12:00), afternoon [12:00,24:00), in the captured organisation timezone. Request period is at most 366 days. Exact request identity prevents duplicate insertion on retry. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveRecord" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "subject": { "type": "integer", "minimum": 1 }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "type": { "enum": [ "holiday", "sickness", "toil", "additional" ] }, "message": { "type": "string", "maxLength": 500 }, "start_minute": { "type": "integer", "minimum": 0, "maximum": 1439, "description": "Local minute on the boundary date; end1440 is the next midnight. Repeated or nonexistent local times are rejected." }, "end_minute": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "Local minute on the boundary date; end1440 is the next midnight. Repeated or nonexistent local times are rejected." } }, "required": [ "request_id", "subject", "from", "to", "type", "message", "start_minute", "end_minute" ], "additionalProperties": false } } } } } }, "/leave/{id}/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "post": { "operationId": "reviewLeaveDecision", "description": "Another authorised manager reviews a pending approval/denial or cancellation of approved leave, including current entitlement effects. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveDecisionReview" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "enum": [ "approved", "denied" ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "decision", "reason" ], "additionalProperties": false } } } } } }, "/leave/{id}/decisions": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "post": { "operationId": "applyLeaveDecision", "description": "Apply the exact reviewed decision. Approval and all account debits are atomic; cancellation reverses the original captured amounts. Concurrent account or leave changes require a fresh review. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveDecisionResult" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "enum": [ "approved", "denied" ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "decision", "reason", "request_id", "review_token" ], "additionalProperties": false } } } } } }, "/leave-ledger/{account_id}/policies": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getLeavePolicyHistory", "description": "Read the original approved pattern separately from paginated immutable amendments. Reasons, approval identities and evidence references are omitted. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeavePolicyHistory" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leave-ledger/{account_id}/policy/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "reviewLeavePolicyAmendment", "description": "Review a complete replacement work-pattern set and its corrections to every approved leave charge. Original policies and entries remain unchanged. Another administrator with recent MFA must approve. No automatic statutory formula is assumed. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeavePolicyAmendmentReview" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "patterns": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/LeaveWorkPattern" } }, "policy_reference": { "type": "string", "minLength": 10, "maxLength": 500 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "patterns", "policy_reference", "reason" ], "additionalProperties": false } } } } } }, "/leave-ledger/{account_id}/policy": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "amendLeavePolicy", "description": "Commit the reviewed policy version and explicit correction entries atomically. Persist request_id and exact body for uncertain retries; 409 requires a fresh review. An amendment cannot change the account period, unit or negative-balance policy. Human workspace sessions may read their own or managed workers. Independent scoped integrations with leave:read may read balances/ledger only within their workplace scope; creator-bound legacy keys are denied. All writes require a human session; policy and adjustment writes require another administrator with recent MFA. Omit Idempotency-Key and If-Match on these routes. Persist request_id and exact body across uncertain retries; do not cache review responses. Pages are live, bounded, and signed to the query, principal and workspace; poll balances/ledger separately from the workforce change feed. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeavePolicyAmendmentResult" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "patterns": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/LeaveWorkPattern" } }, "policy_reference": { "type": "string", "minLength": 10, "maxLength": 500 }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmed": { "const": true } }, "required": [ "patterns", "policy_reference", "reason", "request_id", "review_token", "confirmed" ], "additionalProperties": false } } } } } }, "/staffing-evidence": { "get": { "operationId": "listStaffingPacks", "description": "Read bounded metadata in opaque ID order. Cursor binds workspace, principal, workplace, filters and page size. Workplace managers and administrators in their selected active workspace only; API keys are denied. Creation, preview, download and revocation require recent MFA; listing requires current workplace access. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match; persist request_id and the exact body for uncertain retries. A 409 requires a fresh review. All responses use Cache-Control: no-store. Evidence changes are polled here, outside the general change feed. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "workplace", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffingPackPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createStaffingPack", "description": "Freeze the reviewed bytes once. Source content and retention policy changes invalidate review. Retain the same pack_id from review, a stable request_id, exact body and review_token. At most 50 unpurged copies per workplace. Source changes never modify a captured pack. Workplace managers and administrators in their selected active workspace only; API keys are denied. Creation, preview, download and revocation require recent MFA; listing requires current workplace access. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match; persist request_id and the exact body for uncertain retries. A 409 requires a fresh review. All responses use Cache-Control: no-store. Evidence changes are polled here, outside the general change feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffingPackSummary" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStaffingPackBody" } } } } } }, "/staffing-evidence/review": { "post": { "operationId": "reviewStaffingPack", "description": "Review one workplace over 1\u201331 inclusive company-local dates. Supply a new pack_id. Expiry must be 1 minute\u201324 hours away. Owner-approved export retention is required. Bounds are 1000 rows per source section, 2000 timeline segments, 10000 records total and 8 MiB; shorten the period on rejection. Unknown history is explicit; current records are not historical reconstruction and counts do not certify staffing adequacy. Workplace managers and administrators in their selected active workspace only; API keys are denied. Creation, preview, download and revocation require recent MFA; listing requires current workplace access. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match; persist request_id and the exact body for uncertain retries. A 409 requires a fresh review. All responses use Cache-Control: no-store. Evidence changes are polled here, outside the general change feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffingPackReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewStaffingPackBody" } } } } } }, "/staffing-evidence/{pack_id}": { "parameters": [ { "name": "pack_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "downloadStaffingPack", "description": "Verify exact canonical_json UTF-8 bytes, SHA-256, byte count, workspace and pack id. Captured payload follows StaffingPackPayload. Expired, revoked or purged copies return 410. No public bearer links; downloaded files cannot be recalled. Workplace managers and administrators in their selected active workspace only; API keys are denied. Creation, preview, download and revocation require recent MFA; listing requires current workplace access. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match; persist request_id and the exact body for uncertain retries. A 409 requires a fresh review. All responses use Cache-Control: no-store. Evidence changes are polled here, outside the general change feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffingPackDownload" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/staffing-evidence/{pack_id}/revoke": { "parameters": [ { "name": "pack_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "revokeStaffingPack", "description": "Revoke future access using the listed decimal revision and durable request_id. Retained immutable bytes follow approved export retention and holds; revocation does not delete source evidence or downloaded copies. Workplace managers and administrators in their selected active workspace only; API keys are denied. Creation, preview, download and revocation require recent MFA; listing requires current workplace access. Select membership with X-ShiftForest-Workspace. Writes reject query parameters, Idempotency-Key and If-Match; persist request_id and the exact body for uncertain retries. A 409 requires a fresh review. All responses use Cache-Control: no-store. Evidence changes are polled here, outside the general change feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffingPackRevoked" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export access expired, revoked or purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeStaffingPackBody" } } } } } }, "/leave/{id}/withdraw/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "post": { "operationId": "reviewLeaveWithdrawal", "description": "Only the active requester may withdraw their own pending leave. No manager impersonation, API-key consent, self-approval or cancellation of approved leave. Recent MFA is not required for this own-request action. Review the exact request and reason; confirmation binds current request and worker revision. Preserve the same request_id and body for retries after uncertain responses. A manager approval or source change requires refresh. The retained record has status denied plus withdrawn_at; no entitlement balance changes. Omit Idempotency-Key and If-Match. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveWithdrawalReview" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The active requester human session is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "reason" ], "additionalProperties": false } } } } } }, "/leave/{id}/withdraw": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "post": { "operationId": "withdrawLeave", "description": "Only the active requester may withdraw their own pending leave. No manager impersonation, API-key consent, self-approval or cancellation of approved leave. Recent MFA is not required for this own-request action. Review the exact request and reason; confirmation binds current request and worker revision. Preserve the same request_id and body for retries after uncertain responses. A manager approval or source change requires refresh. The retained record has status denied plus withdrawn_at; no entitlement balance changes. Omit Idempotency-Key and If-Match. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveWithdrawalResult" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The active requester human session is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "reason", "request_id", "review_token" ], "additionalProperties": false } } } } } }, "/files": { "get": { "operationId": "listPrivateFiles", "description": "List one worker\u2019s file metadata in opaque ID order. Cursors bind workspace, principal, subject and page size. Gate booleans describe deployment readiness; policy_ready describes the workspace policy. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "subject", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFilePage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/uploads": { "post": { "operationId": "reservePrivateFile", "description": "Reserve an immutable PDF/JPEG/PNG version up to 4 MiB. PDFs must be structurally valid, unencrypted, without embedded files or non-whitespace trailing content after the final EOF marker. New document revision is \"0\"; replacements use the current document revision and unchanged title. Employees cannot replace management-issued files or request acknowledgements. Capacity limits: 500 lifetime version records and 100 MiB per workspace; 256 MiB across this deployment. Unverified or blocked reservations count as 4 MiB each until an exact clean scan verifies their actual size. These engineering limits are independent of billing. Reservation lasts 15 minutes; policy snapshot records owner-approved retention from reservation time. This does not upload or publish bytes. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFileReservation" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservePrivateFileBody" } } } } } }, "/files/{document_id}": { "get": { "operationId": "getPrivateFile", "description": "Read file and descending version history with an opaque cursor bound to principal and page size. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFileHistory" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{document_id}/retire": { "post": { "operationId": "retirePrivateFile", "description": "Confirm retirement of the reviewed revision and record a reason. Revokes all version downloads; keeps metadata, versions and acknowledgements. Management-issued files require management. This does not erase bytes. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store.", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFile" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetirePrivateFileBody" } } } } } }, "/files/versions/{version_id}/upload": { "post": { "operationId": "createPrivateFileUpload", "description": "Obtain a credential for the reserving uploader only. PUT exact raw bytes to upload_url with returned headers, then complete before upload_expires_at. Supabase credentials remain valid for 2 hours; the shorter 15-minute reservation controls acceptance, not provider token revocation. Upsert is false. Late or uncompleted bytes stay private and cannot become available. Never log or persist upload_url. A retry may issue a different token for the same immutable path. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store.", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFileUploadCredential" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/files/versions/{version_id}/complete": { "post": { "operationId": "completePrivateFileUpload", "description": "Queue independent size, SHA-256, file-type and malware verification. Completion does not mean available. Missing objects retry with backoff; errors, encryption and limits never count as a clean scan. Poll history; available means scanned, not a safety guarantee. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store.", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFileVersion" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletePrivateFileBody" } } } } } }, "/files/versions/{version_id}/acknowledge": { "post": { "operationId": "acknowledgePrivateFile", "description": "The worker acknowledges the current available version and exact SHA-256 when acknowledgement was requested. A later version needs a new acknowledgement. Managers cannot acknowledge on the worker\u2019s behalf. This is not an electronic signature. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store.", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFileVersion" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgePrivateFileBody" } } } } } }, "/files/versions/{version_id}/content": { "get": { "operationId": "downloadPrivateFile", "description": "Download an available, unretired, unexpired version as an attachment. Authorization is checked before fetching bytes and again after verifying size/digest/type. Storage paths and bearer download links are not returned. Bytes already sent cannot be recalled. Human sessions only; API keys are denied. Employees may access their own files; managers require current worker scope and recent MFA. Select workspace with X-ShiftForest-Workspace. No Idempotency-Key or If-Match: persist each request_id and exact command for uncertain retries. Writes reject query parameters. Poll file metadata for progress; files are outside the general change feed. All responses are no-store.", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verified private attachment", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Document unavailable, retired or retention deadline passed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Document capability not commissioned, storage/scanner unavailable or verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/attendance/summary": { "get": { "operationId": "get_attendance_summary", "description": "Requires attendance_history:read on an independent integration, or an active administrator session. Captured attendance workplace governs visibility; legacy rows fall back to their shift workplace. Start-time window [from,to), at most 93 elapsed days, optional public numeric worker/workplace filters. One statement snapshot; up to100000 matching nonvoid records. A larger result returns422 without partial totals; narrow the query. Days with no sessions are omitted. Counts include open sessions; duration sums include closed sessions only. Break duration is capped at each session duration. Exact decimal seconds are strings. No rounding, paid-break policy, rates, overtime, payroll approval or historical contract calculation is applied. Totals workers are distinct across the whole window, not the sum of daily counts. The result is live, not a frozen payroll export.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "user", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "location", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceSummary" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many matching records, or a nonfinite/invalid retained duration. Narrow the window or correct the affected records. No partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Summarize recorded attendance by company-local clock-in date" }, "parameters": [ { "$ref": "#/components/parameters/Workspace" } ] }, "/dashboard/attention": { "get": { "operationId": "get_dashboard_attention", "description": "Human administrator or manager workspace session only; integration and creator-bound keys are denied. Fixed current company-local month and configured Monday/Sunday week, with no query filters. Counts other members pending leave in current management scope, noncancelled draft shifts by retained rota date, and closed nonvoid unapproved clock records by clock-in month. Attendance scope uses captured workplace, falling back to the linked shift only for legacy records; current worker membership does not rewrite history. Company/member IDs are native UUIDs, not public numeric workforce IDs. rota_week is the Monday navigation anchor used by the retained rota UI, including Sunday-start weeks. Each section has a100000 matching-record budget; overflow returns422 without partial counts. Counts come from one statement snapshot, are not payroll approval, and contain no employee details.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardAttention" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many matching records, or a nonfinite/invalid retained duration. Narrow the window or correct the affected records. No partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Summarize recorded attendance by company-local clock-in date" } }, "/notifications/push/devices": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "get": { "operationId": "list_push_devices", "description": "Own active human workspace session only; API keys are denied. Select the workspace with X-ShiftForest-Workspace. No query parameters. Device IDs are native UUIDs. Responses contain labels, revisions and timestamps, never endpoint capabilities or encryption secrets. Provider acceptance does not guarantee display or reading. Enrollment and delivery remain disabled until commissioned. Lists the up to 100 own device records, with active devices first and remaining history newest first. configured=false disables enrollment but allows listing and revocation. At most 20 unexpired active devices across an Auth identity. Browser permission must follow a direct user action.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushDevices" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required enrollment idempotency key or revocation version missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Browser notification configuration or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Own device not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Active device limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-contract-coverage": "positive" }, "post": { "operationId": "enroll_push_device", "description": "Own active human workspace session only; API keys are denied. Select the workspace with X-ShiftForest-Workspace. No query parameters. Device IDs are native UUIDs. Responses contain labels, revisions and timestamps, never endpoint capabilities or encryption secrets. Provider acceptance does not guarantee display or reading. Enrollment and delivery remain disabled until commissioned. Requires explicit consent, canonical subscription keys and the currently configured application key. Preserve Idempotency-Key and exact body across retries (24 hours). A replacement increments the binding revision and cancels old queued events. Cross-account replacement requires existing subscription-key proof. A fresh enrollment expires after 90 days; old events are not backfilled.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Retry a write safely for 24 hours. Reuse the same key, body, path and If-Match. A different request with the same key returns 409. Keys are isolated by organization and authenticated principal. Replays still consume quota.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushDevice" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted current device revision" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required enrollment idempotency key or revocation version missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Browser notification configuration or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Own device not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Active device limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-contract-coverage": "positive", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushEnrollment" } } } } } }, "/notifications/push/devices/{device}": { "parameters": [ { "$ref": "#/components/parameters/Workspace" } ], "delete": { "operationId": "revoke_push_device", "description": "Own active human workspace session only; API keys are denied. Select the workspace with X-ShiftForest-Workspace. No query parameters. Device IDs are native UUIDs. Responses contain labels, revisions and timestamps, never endpoint capabilities or encryption secrets. Provider acceptance does not guarantee display or reading. Enrollment and delivery remain disabled until commissioned. Requires If-Match with the listed revision. A stale revision returns 412; refresh before retrying. Clears stored endpoint/key capabilities and cancels unsent deliveries. Already accepted notifications cannot reliably be recalled.", "parameters": [ { "name": "device", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushDevice" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "Quoted current device revision" } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Required enrollment idempotency key or revocation version missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Browser notification configuration or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Own device not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Active device limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-contract-coverage": "positive" } }, "/team/summary": { "get": { "operationId": "get_team_summary", "description": "Human administrator/manager workspace session only. Complete matching workforce counts and scheduled hours for seven days starting at week, using retained rota date or company-local start date. Literal case-insensitive name search. location is a native workplace UUID; unauthorized workplaces return403. Workplace filter selects workers; administrator hours include all their workplaces, manager hours only managed workplaces. Draft and published shifts count, cancelled shifts do not. Current paid-break preference applies. Weekly-limit comparison is null for managers. Maximum100000 matching workers and shifts per section; overflow returns422 without partial totals. This is a live summary, not a payroll approval or immutable snapshot.", "parameters": [ { "name": "week", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 80 } }, { "name": "location", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Native workplace UUID, not a public numeric catalogue ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamSummary" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many matching records, or a nonfinite/invalid retained duration. Narrow the window or correct the affected records. No partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Summarize recorded attendance by company-local clock-in date" } }, "/team/members/{id}": { "get": { "operationId": "get_team_member", "description": "Fresh worker profile for active human administrator/manager sessions. All IDs are native UUIDs. Explicit profile field allowlist and current workplaces; manager workplace memberships are limited to managed sites. The managed_locations array is the caller management scope, for scoping separately loaded historical rows. Includes row_revision for reviewed writes. Missing, foreign or out-of-scope workers return404. Employees and integration keys are denied. No Auth identifiers or private credential records are returned. Maximum10000 workplaces per array; overflow returns422 without partial data.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Team member unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many matching records, or a nonfinite/invalid retained duration. Narrow the window or correct the affected records. No partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Summarize recorded attendance by company-local clock-in date" } }, "/team/members": { "get": { "operationId": "get_team_directory", "description": "Human administrator/manager directory with native UUIDs and explicit profile projection. Seven-day per-worker scheduled hours use the same scope and exact-second rules as team summary. Cursor pages contain at most100 workers and bind to the human identity, current role/workplaces, filters and page size. Cursors expire after24h and exclude later-created workers through a committed catalogue insertion fence; existing names, memberships and schedules remain live. UUID keyset traversal, not offset pagination. Each page caps visible memberships at10000 and shifts at100000; overflow returns422 with no partial rows. Missing or unauthorized workplace filters return403. Integration keys are denied. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "parameters": [ { "name": "week", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 80 } }, { "name": "location", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Native workplace UUID, not a public numeric catalogue ID." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDirectory" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many matching records, or a nonfinite/invalid retained duration. Narrow the window or correct the affected records. No partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Summarize recorded attendance by company-local clock-in date" } }, "/directory/search": { "get": { "operationId": "search_directory_people", "description": "Human selected-workspace name or role-tag lookup. Literal case-insensitive substring matching, ordered by name and native UUID. Administrators may find workspace workers; managers and employees may find themselves and colleagues sharing a current workplace. At most20 minimal display records; has_more asks the caller to refine the search, not to infer a total. Current scope is rechecked on every request. No email, pay, employee codes, credentials or Auth IDs. Integration keys are denied.", "parameters": [ { "name": "search", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 80 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectorySearch" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many matching records, or a nonfinite/invalid retained duration. Narrow the window or correct the affected records. No partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Summarize recorded attendance by company-local clock-in date" } }, "/setup/progress": { "get": { "operationId": "get_setup_progress", "description": "Current selected-workspace setup facts for an active human administrator. workplace means a workplace exists; team means at least one other workforce record exists; published_shift means a noncancelled published shift has an assignee. verified_colleague means another enabled linked worker has a current matching verified Auth email and available account. Imported data may satisfy these checks. This is not activation history, evidence of worker login, policy approval, payroll reconciliation or production readiness. No behavioural events are collected. Integration credentials and other roles are denied.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupProgress" } } } }, "400": { "description": "Unknown/invalid query or body; invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient tenant access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting reference or external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "Version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "If-Match required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retry without advancing cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Date not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 65536 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON body required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many matching records, or a nonfinite/invalid retained duration. Narrow the window or correct the affected records. No partial result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Summarize recorded attendance by company-local clock-in date" } }, "/access/configuration": { "get": { "operationId": "delegationConfiguration", "description": "Human session in the selected workspace only; API keys are denied. Administrator and recent authenticator MFA required except /access/workplaces, which returns only current staffing access. Groups include descendant workplaces (maximum eight levels); each workplace belongs to at most one group. Only staffing.read and staffing.manage are supported; manage includes read. Grants expire within 366 days and never change base roles. Direct grants remain bound to the reviewed login identity. SCIM grants require current active membership, no manual hold and an enabled connection. All IDs in this namespace are opaque UUIDs, including member and workplace identifiers; discover them through /access/members and /access/workplaces, not numeric workforce resource IDs. Reviews expire after five minutes and bind the exact configuration, revision and relevant identity state. Persist request_id and review_id for uncertain apply retries. A 409 requires reloading and reviewing again. No If-Match, Idempotency-Key or write query parameters. All responses are no-store. Configurations are limited to 128 KiB through RPC; HTTP request bodies are limited to 64 KiB. Changes are polled, outside the general sync feed. History uses the paired before/id cursor, newest first. Discovery uses after UUID, ascending. Pages contain at most 25 entries; records remain live during paging.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationConfiguration" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/access/review": { "post": { "operationId": "reviewDelegation", "description": "Human session in the selected workspace only; API keys are denied. Administrator and recent authenticator MFA required except /access/workplaces, which returns only current staffing access. Groups include descendant workplaces (maximum eight levels); each workplace belongs to at most one group. Only staffing.read and staffing.manage are supported; manage includes read. Grants expire within 366 days and never change base roles. Direct grants remain bound to the reviewed login identity. SCIM grants require current active membership, no manual hold and an enabled connection. All IDs in this namespace are opaque UUIDs, including member and workplace identifiers; discover them through /access/members and /access/workplaces, not numeric workforce resource IDs. Reviews expire after five minutes and bind the exact configuration, revision and relevant identity state. Persist request_id and review_id for uncertain apply retries. A 409 requires reloading and reviewing again. No If-Match, Idempotency-Key or write query parameters. All responses are no-store. Configurations are limited to 128 KiB through RPC; HTTP request bodies are limited to 64 KiB. Changes are polled, outside the general sync feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewDelegationBody" } } } } } }, "/access/commands": { "post": { "operationId": "applyDelegation", "description": "Human session in the selected workspace only; API keys are denied. Administrator and recent authenticator MFA required except /access/workplaces, which returns only current staffing access. Groups include descendant workplaces (maximum eight levels); each workplace belongs to at most one group. Only staffing.read and staffing.manage are supported; manage includes read. Grants expire within 366 days and never change base roles. Direct grants remain bound to the reviewed login identity. SCIM grants require current active membership, no manual hold and an enabled connection. All IDs in this namespace are opaque UUIDs, including member and workplace identifiers; discover them through /access/members and /access/workplaces, not numeric workforce resource IDs. Reviews expire after five minutes and bind the exact configuration, revision and relevant identity state. Persist request_id and review_id for uncertain apply retries. A 409 requires reloading and reviewing again. No If-Match, Idempotency-Key or write query parameters. All responses are no-store. Configurations are limited to 128 KiB through RPC; HTTP request bodies are limited to 64 KiB. Changes are polled, outside the general sync feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationResult" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyDelegationBody" } } } } } }, "/access/history": { "get": { "operationId": "delegationHistory", "description": "Human session in the selected workspace only; API keys are denied. Administrator and recent authenticator MFA required except /access/workplaces, which returns only current staffing access. Groups include descendant workplaces (maximum eight levels); each workplace belongs to at most one group. Only staffing.read and staffing.manage are supported; manage includes read. Grants expire within 366 days and never change base roles. Direct grants remain bound to the reviewed login identity. SCIM grants require current active membership, no manual hold and an enabled connection. All IDs in this namespace are opaque UUIDs, including member and workplace identifiers; discover them through /access/members and /access/workplaces, not numeric workforce resource IDs. Reviews expire after five minutes and bind the exact configuration, revision and relevant identity state. Persist request_id and review_id for uncertain apply retries. A 409 requires reloading and reviewing again. No If-Match, Idempotency-Key or write query parameters. All responses are no-store. Configurations are limited to 128 KiB through RPC; HTTP request bodies are limited to 64 KiB. Changes are polled, outside the general sync feed. History uses the paired before/id cursor, newest first. Discovery uses after UUID, ascending. Pages contain at most 25 entries; records remain live during paging.", "parameters": [ { "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationHistoryPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/access/scim-groups": { "get": { "operationId": "delegationSCIMGroups", "description": "Human session in the selected workspace only; API keys are denied. Administrator and recent authenticator MFA required except /access/workplaces, which returns only current staffing access. Groups include descendant workplaces (maximum eight levels); each workplace belongs to at most one group. Only staffing.read and staffing.manage are supported; manage includes read. Grants expire within 366 days and never change base roles. Direct grants remain bound to the reviewed login identity. SCIM grants require current active membership, no manual hold and an enabled connection. All IDs in this namespace are opaque UUIDs, including member and workplace identifiers; discover them through /access/members and /access/workplaces, not numeric workforce resource IDs. Reviews expire after five minutes and bind the exact configuration, revision and relevant identity state. Persist request_id and review_id for uncertain apply retries. A 409 requires reloading and reviewing again. No If-Match, Idempotency-Key or write query parameters. All responses are no-store. Configurations are limited to 128 KiB through RPC; HTTP request bodies are limited to 64 KiB. Changes are polled, outside the general sync feed. History uses the paired before/id cursor, newest first. Discovery uses after UUID, ascending. Pages contain at most 25 entries; records remain live during paging.", "parameters": [ { "in": "query", "name": "search", "schema": { "type": "string", "maxLength": 80 } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationSCIMGroupPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/access/members": { "get": { "operationId": "delegationMembers", "description": "Human session in the selected workspace only; API keys are denied. Administrator and recent authenticator MFA required except /access/workplaces, which returns only current staffing access. Groups include descendant workplaces (maximum eight levels); each workplace belongs to at most one group. Only staffing.read and staffing.manage are supported; manage includes read. Grants expire within 366 days and never change base roles. Direct grants remain bound to the reviewed login identity. SCIM grants require current active membership, no manual hold and an enabled connection. All IDs in this namespace are opaque UUIDs, including member and workplace identifiers; discover them through /access/members and /access/workplaces, not numeric workforce resource IDs. Reviews expire after five minutes and bind the exact configuration, revision and relevant identity state. Persist request_id and review_id for uncertain apply retries. A 409 requires reloading and reviewing again. No If-Match, Idempotency-Key or write query parameters. All responses are no-store. Configurations are limited to 128 KiB through RPC; HTTP request bodies are limited to 64 KiB. Changes are polled, outside the general sync feed. History uses the paired before/id cursor, newest first. Discovery uses after UUID, ascending. Pages contain at most 25 entries; records remain live during paging.", "parameters": [ { "in": "query", "name": "search", "schema": { "type": "string", "maxLength": 80 } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationMemberPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/access/workplaces": { "get": { "operationId": "delegatedStaffingWorkplaces", "description": "Human session in the selected workspace only; API keys are denied. Administrator and recent authenticator MFA required except /access/workplaces, which returns only current staffing access. Groups include descendant workplaces (maximum eight levels); each workplace belongs to at most one group. Only staffing.read and staffing.manage are supported; manage includes read. Grants expire within 366 days and never change base roles. Direct grants remain bound to the reviewed login identity. SCIM grants require current active membership, no manual hold and an enabled connection. All IDs in this namespace are opaque UUIDs, including member and workplace identifiers; discover them through /access/members and /access/workplaces, not numeric workforce resource IDs. Reviews expire after five minutes and bind the exact configuration, revision and relevant identity state. Persist request_id and review_id for uncertain apply retries. A 409 requires reloading and reviewing again. No If-Match, Idempotency-Key or write query parameters. All responses are no-store. Configurations are limited to 128 KiB through RPC; HTTP request bodies are limited to 64 KiB. Changes are polled, outside the general sync feed. History uses the paired before/id cursor, newest first. Discovery uses after UUID, ascending. Pages contain at most 25 entries; records remain live during paging.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegatedStaffingWorkplaces" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-changes/review": { "post": { "operationId": "reviewPayrollChange", "description": "Human administrator in the selected workspace with recent authenticator MFA only. API keys are denied. Opaque UUID identifiers: obtain workers from the human team directory, original batch UUIDs from /payroll-exports and attendance UUIDs using /payroll-changes/exports/{id}. Rates use integer minor units, effective from local date until the next dated rate; existing exports remain immutable. Adjustments specify the desired cumulative total for one attendance, not a delta; the server reviews the signed difference including every previous correction. Reconciliation is administrator-reported evidence, not verified provider acceptance; omit adjustment_id for the original frozen batch, or supply one to reconcile that signed adjustment. Reviews expire after five minutes; at most twenty pending reviews per administrator. Persist exact request_id and review_id across uncertain responses. Current authority is checked before replay; changed or expired state returns 409 and requires a fresh review. All responses are no-store. Omit If-Match, Idempotency-Key and write query parameters. Poll history for changes; these records are outside the general sync feed. Generic CSV only; no statutory pay, tax or provider certification is inferred. Effective-dated policy versions must start on their configured ISO week boundary, which cannot subsequently change. Policies use company timezone/currency captured at approval. Thresholds are whole minutes, null disables overtime; multipliers are basis points, 10000 means normal pay. The highest applicable daily/weekly/enhancement multiplier wins without stacking. Entire attendance belongs to its local start day/week and enhancement start window; earlier approved attendance in that week counts even outside the export and when already exported. Recorded sleep-in disturbance time is actual elapsed time, including DST; no break allocation is inferred. Allowances require a single attendance exactly matching a reviewed sleep-in shift. Paid time rounds to configured minutes, then each attendance/pay-code/multiplier component rounds half up to a minor unit. Export format schema_version 2 retains unit, base rate and multiplier, with frozen policy provenance; consume canonical amount_minor rather than treating rate_minor as an enhanced rate. Existing frozen exports remain unchanged. Preview limits: 93 days, 100000 context records, 20000 pay items/issues and 8 MiB. Policy history has at most 1024 immutable versions; newest-first 25 per page. No salary proration, statutory pay or tax is inferred. New reviewed changes support exact-integer totals up to 8000000000000000 minor units. Legacy exports beyond that bound remain readable through the decimal-string /payroll-exports endpoints; the change/raw-UUID namespace rejects them with 422. Fixed salary/pay kinds require an explicit agreed gross amount and a period of at most 366 days, with employee payroll code, pay code, agreement reference and reason. No salary proration is inferred. Active positive salary periods cannot overlap each other or effective paid hourly attendance; a zero cumulative salary reversal permits a replacement period or hourly pay. Increasing a reversed salary rechecks overlapping pay. Salary hours are not automatically used as hourly overtime context. Fixed adjustments specify the desired cumulative total against the original item and append a signed row; originals and corrections remain immutable. The fixed-pay-v1 CSV uses unique pay item and original IDs, without invented attendance IDs. Reconcile each original or signed correction item separately (one expected pay item); evidence is administrator-reported. Fixed payments are human-MFA-administrator-only, not delegated by one workplace grant.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollChangeReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollChangeInput" } } } } } }, "/payroll-changes/commands": { "post": { "operationId": "applyPayrollChange", "description": "Also accepts a scoped adjustment review made through /payroll-access/adjustment-review with current workplace payroll.adjust authority and recent MFA. Other review kinds require administrator access. Human in the selected workspace with recent authenticator MFA. API keys are denied. Opaque UUID identifiers: obtain workers from the human team directory, original batch UUIDs from /payroll-exports and attendance UUIDs using /payroll-changes/exports/{id}. Rates use integer minor units, effective from local date until the next dated rate; existing exports remain immutable. Adjustments specify the desired cumulative total for one attendance, not a delta; the server reviews the signed difference including every previous correction. Reconciliation is administrator-reported evidence, not verified provider acceptance; omit adjustment_id for the original frozen batch, or supply one to reconcile that signed adjustment. Reviews expire after five minutes; at most twenty pending reviews per administrator. Persist exact request_id and review_id across uncertain responses. Current authority is checked before replay; changed or expired state returns 409 and requires a fresh review. All responses are no-store. Omit If-Match, Idempotency-Key and write query parameters. Poll history for changes; these records are outside the general sync feed. Generic CSV only; no statutory pay, tax or provider certification is inferred. Effective-dated policy versions must start on their configured ISO week boundary, which cannot subsequently change. Policies use company timezone/currency captured at approval. Thresholds are whole minutes, null disables overtime; multipliers are basis points, 10000 means normal pay. The highest applicable daily/weekly/enhancement multiplier wins without stacking. Entire attendance belongs to its local start day/week and enhancement start window; earlier approved attendance in that week counts even outside the export and when already exported. Recorded sleep-in disturbance time is actual elapsed time, including DST; no break allocation is inferred. Allowances require a single attendance exactly matching a reviewed sleep-in shift. Paid time rounds to configured minutes, then each attendance/pay-code/multiplier component rounds half up to a minor unit. Export format schema_version 2 retains unit, base rate and multiplier, with frozen policy provenance; consume canonical amount_minor rather than treating rate_minor as an enhanced rate. Existing frozen exports remain unchanged. Preview limits: 93 days, 100000 context records, 20000 pay items/issues and 8 MiB. Policy history has at most 1024 immutable versions; newest-first 25 per page. No salary proration, statutory pay or tax is inferred. New reviewed changes support exact-integer totals up to 8000000000000000 minor units. Legacy exports beyond that bound remain readable through the decimal-string /payroll-exports endpoints; the change/raw-UUID namespace rejects them with 422. Fixed salary/pay kinds require an explicit agreed gross amount and a period of at most 366 days, with employee payroll code, pay code, agreement reference and reason. No salary proration is inferred. Active positive salary periods cannot overlap each other or effective paid hourly attendance; a zero cumulative salary reversal permits a replacement period or hourly pay. Increasing a reversed salary rechecks overlapping pay. Salary hours are not automatically used as hourly overtime context. Fixed adjustments specify the desired cumulative total against the original item and append a signed row; originals and corrections remain immutable. The fixed-pay-v1 CSV uses unique pay item and original IDs, without invented attendance IDs. Reconcile each original or signed correction item separately (one expected pay item); evidence is administrator-reported. Fixed payments are human-MFA-administrator-only, not delegated by one workplace grant.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollChangeReceipt" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyPayrollChangeBody" } } } } } }, "/payroll-changes/history": { "get": { "operationId": "payrollChangeHistory", "description": "Human administrator in the selected workspace with recent authenticator MFA only. API keys are denied. Opaque UUID identifiers: obtain workers from the human team directory, original batch UUIDs from /payroll-exports and attendance UUIDs using /payroll-changes/exports/{id}. Rates use integer minor units, effective from local date until the next dated rate; existing exports remain immutable. Adjustments specify the desired cumulative total for one attendance, not a delta; the server reviews the signed difference including every previous correction. Reconciliation is administrator-reported evidence, not verified provider acceptance; omit adjustment_id for the original frozen batch, or supply one to reconcile that signed adjustment. Reviews expire after five minutes; at most twenty pending reviews per administrator. Persist exact request_id and review_id across uncertain responses. Current authority is checked before replay; changed or expired state returns 409 and requires a fresh review. All responses are no-store. Omit If-Match, Idempotency-Key and write query parameters. Poll history for changes; these records are outside the general sync feed. Generic CSV only; no statutory pay, tax or provider certification is inferred. Effective-dated policy versions must start on their configured ISO week boundary, which cannot subsequently change. Policies use company timezone/currency captured at approval. Thresholds are whole minutes, null disables overtime; multipliers are basis points, 10000 means normal pay. The highest applicable daily/weekly/enhancement multiplier wins without stacking. Entire attendance belongs to its local start day/week and enhancement start window; earlier approved attendance in that week counts even outside the export and when already exported. Recorded sleep-in disturbance time is actual elapsed time, including DST; no break allocation is inferred. Allowances require a single attendance exactly matching a reviewed sleep-in shift. Paid time rounds to configured minutes, then each attendance/pay-code/multiplier component rounds half up to a minor unit. Export format schema_version 2 retains unit, base rate and multiplier, with frozen policy provenance; consume canonical amount_minor rather than treating rate_minor as an enhanced rate. Existing frozen exports remain unchanged. Preview limits: 93 days, 100000 context records, 20000 pay items/issues and 8 MiB. Policy history has at most 1024 immutable versions; newest-first 25 per page. No salary proration, statutory pay or tax is inferred. New reviewed changes support exact-integer totals up to 8000000000000000 minor units. Legacy exports beyond that bound remain readable through the decimal-string /payroll-exports endpoints; the change/raw-UUID namespace rejects them with 422. Fixed salary/pay kinds require an explicit agreed gross amount and a period of at most 366 days, with employee payroll code, pay code, agreement reference and reason. No salary proration is inferred. Active positive salary periods cannot overlap each other or effective paid hourly attendance; a zero cumulative salary reversal permits a replacement period or hourly pay. Increasing a reversed salary rechecks overlapping pay. Salary hours are not automatically used as hourly overtime context. Fixed adjustments specify the desired cumulative total against the original item and append a signed row; originals and corrections remain immutable. The fixed-pay-v1 CSV uses unique pay item and original IDs, without invented attendance IDs. Reconcile each original or signed correction item separately (one expected pay item); evidence is administrator-reported. Fixed payments are human-MFA-administrator-only, not delegated by one workplace grant.", "parameters": [ { "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollChangeHistory" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-changes/exports/{id}": { "get": { "operationId": "payrollChangeExport", "description": "Human administrator in the selected workspace with recent authenticator MFA only. API keys are denied. Opaque UUID identifiers: obtain workers from the human team directory, original batch UUIDs from /payroll-exports and attendance UUIDs using /payroll-changes/exports/{id}. Rates use integer minor units, effective from local date until the next dated rate; existing exports remain immutable. Adjustments specify the desired cumulative total for one attendance, not a delta; the server reviews the signed difference including every previous correction. Reconciliation is administrator-reported evidence, not verified provider acceptance; omit adjustment_id for the original frozen batch, or supply one to reconcile that signed adjustment. Reviews expire after five minutes; at most twenty pending reviews per administrator. Persist exact request_id and review_id across uncertain responses. Current authority is checked before replay; changed or expired state returns 409 and requires a fresh review. All responses are no-store. Omit If-Match, Idempotency-Key and write query parameters. Poll history for changes; these records are outside the general sync feed. Generic CSV only; no statutory pay, tax or provider certification is inferred. Effective-dated policy versions must start on their configured ISO week boundary, which cannot subsequently change. Policies use company timezone/currency captured at approval. Thresholds are whole minutes, null disables overtime; multipliers are basis points, 10000 means normal pay. The highest applicable daily/weekly/enhancement multiplier wins without stacking. Entire attendance belongs to its local start day/week and enhancement start window; earlier approved attendance in that week counts even outside the export and when already exported. Recorded sleep-in disturbance time is actual elapsed time, including DST; no break allocation is inferred. Allowances require a single attendance exactly matching a reviewed sleep-in shift. Paid time rounds to configured minutes, then each attendance/pay-code/multiplier component rounds half up to a minor unit. Export format schema_version 2 retains unit, base rate and multiplier, with frozen policy provenance; consume canonical amount_minor rather than treating rate_minor as an enhanced rate. Existing frozen exports remain unchanged. Preview limits: 93 days, 100000 context records, 20000 pay items/issues and 8 MiB. Policy history has at most 1024 immutable versions; newest-first 25 per page. No salary proration, statutory pay or tax is inferred. New reviewed changes support exact-integer totals up to 8000000000000000 minor units. Legacy exports beyond that bound remain readable through the decimal-string /payroll-exports endpoints; the change/raw-UUID namespace rejects them with 422. Fixed salary/pay kinds require an explicit agreed gross amount and a period of at most 366 days, with employee payroll code, pay code, agreement reference and reason. No salary proration is inferred. Active positive salary periods cannot overlap each other or effective paid hourly attendance; a zero cumulative salary reversal permits a replacement period or hourly pay. Increasing a reversed salary rechecks overlapping pay. Salary hours are not automatically used as hourly overtime context. Fixed adjustments specify the desired cumulative total against the original item and append a signed row; originals and corrections remain immutable. The fixed-pay-v1 CSV uses unique pay item and original IDs, without invented attendance IDs. Reconcile each original or signed correction item separately (one expected pay item); evidence is administrator-reported. Fixed payments are human-MFA-administrator-only, not delegated by one workplace grant.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollChangeExport" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-changes/policies": { "get": { "operationId": "payrollPolicies", "description": "Human administrator in the selected workspace with recent authenticator MFA only. API keys are denied. Opaque UUID identifiers: obtain workers from the human team directory, original batch UUIDs from /payroll-exports and attendance UUIDs using /payroll-changes/exports/{id}. Rates use integer minor units, effective from local date until the next dated rate; existing exports remain immutable. Adjustments specify the desired cumulative total for one attendance, not a delta; the server reviews the signed difference including every previous correction. Reconciliation is administrator-reported evidence, not verified provider acceptance; omit adjustment_id for the original frozen batch, or supply one to reconcile that signed adjustment. Reviews expire after five minutes; at most twenty pending reviews per administrator. Persist exact request_id and review_id across uncertain responses. Current authority is checked before replay; changed or expired state returns 409 and requires a fresh review. All responses are no-store. Omit If-Match, Idempotency-Key and write query parameters. Poll history for changes; these records are outside the general sync feed. Generic CSV only; no statutory pay, tax or provider certification is inferred. Effective-dated policy versions must start on their configured ISO week boundary, which cannot subsequently change. Policies use company timezone/currency captured at approval. Thresholds are whole minutes, null disables overtime; multipliers are basis points, 10000 means normal pay. The highest applicable daily/weekly/enhancement multiplier wins without stacking. Entire attendance belongs to its local start day/week and enhancement start window; earlier approved attendance in that week counts even outside the export and when already exported. Recorded sleep-in disturbance time is actual elapsed time, including DST; no break allocation is inferred. Allowances require a single attendance exactly matching a reviewed sleep-in shift. Paid time rounds to configured minutes, then each attendance/pay-code/multiplier component rounds half up to a minor unit. Export format schema_version 2 retains unit, base rate and multiplier, with frozen policy provenance; consume canonical amount_minor rather than treating rate_minor as an enhanced rate. Existing frozen exports remain unchanged. Preview limits: 93 days, 100000 context records, 20000 pay items/issues and 8 MiB. Policy history has at most 1024 immutable versions; newest-first 25 per page. No salary proration, statutory pay or tax is inferred. New reviewed changes support exact-integer totals up to 8000000000000000 minor units. Legacy exports beyond that bound remain readable through the decimal-string /payroll-exports endpoints; the change/raw-UUID namespace rejects them with 422. Fixed salary/pay kinds require an explicit agreed gross amount and a period of at most 366 days, with employee payroll code, pay code, agreement reference and reason. No salary proration is inferred. Active positive salary periods cannot overlap each other or effective paid hourly attendance; a zero cumulative salary reversal permits a replacement period or hourly pay. Increasing a reversed salary rechecks overlapping pay. Salary hours are not automatically used as hourly overtime context. Fixed adjustments specify the desired cumulative total against the original item and append a signed row; originals and corrections remain immutable. The fixed-pay-v1 CSV uses unique pay item and original IDs, without invented attendance IDs. Reconcile each original or signed correction item separately (one expected pay item); evidence is administrator-reported. Fixed payments are human-MFA-administrator-only, not delegated by one workplace grant.", "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,17}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollPolicyPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-changes/fixed-pay": { "get": { "operationId": "payrollFixedItems", "description": "Human administrator in the selected workspace with recent authenticator MFA only. API keys are denied. Opaque UUID identifiers: obtain workers from the human team directory, original batch UUIDs from /payroll-exports and attendance UUIDs using /payroll-changes/exports/{id}. Rates use integer minor units, effective from local date until the next dated rate; existing exports remain immutable. Adjustments specify the desired cumulative total for one attendance, not a delta; the server reviews the signed difference including every previous correction. Reconciliation is administrator-reported evidence, not verified provider acceptance; omit adjustment_id for the original frozen batch, or supply one to reconcile that signed adjustment. Reviews expire after five minutes; at most twenty pending reviews per administrator. Persist exact request_id and review_id across uncertain responses. Current authority is checked before replay; changed or expired state returns 409 and requires a fresh review. All responses are no-store. Omit If-Match, Idempotency-Key and write query parameters. Poll history for changes; these records are outside the general sync feed. Generic CSV only; no statutory pay, tax or provider certification is inferred. Effective-dated policy versions must start on their configured ISO week boundary, which cannot subsequently change. Policies use company timezone/currency captured at approval. Thresholds are whole minutes, null disables overtime; multipliers are basis points, 10000 means normal pay. The highest applicable daily/weekly/enhancement multiplier wins without stacking. Entire attendance belongs to its local start day/week and enhancement start window; earlier approved attendance in that week counts even outside the export and when already exported. Recorded sleep-in disturbance time is actual elapsed time, including DST; no break allocation is inferred. Allowances require a single attendance exactly matching a reviewed sleep-in shift. Paid time rounds to configured minutes, then each attendance/pay-code/multiplier component rounds half up to a minor unit. Export format schema_version 2 retains unit, base rate and multiplier, with frozen policy provenance; consume canonical amount_minor rather than treating rate_minor as an enhanced rate. Existing frozen exports remain unchanged. Preview limits: 93 days, 100000 context records, 20000 pay items/issues and 8 MiB. Policy history has at most 1024 immutable versions; newest-first 25 per page. No salary proration, statutory pay or tax is inferred. New reviewed changes support exact-integer totals up to 8000000000000000 minor units. Legacy exports beyond that bound remain readable through the decimal-string /payroll-exports endpoints; the change/raw-UUID namespace rejects them with 422. Fixed salary/pay kinds require an explicit agreed gross amount and a period of at most 366 days, with employee payroll code, pay code, agreement reference and reason. No salary proration is inferred. Active positive salary periods cannot overlap each other or effective paid hourly attendance; a zero cumulative salary reversal permits a replacement period or hourly pay. Increasing a reversed salary rechecks overlapping pay. Salary hours are not automatically used as hourly overtime context. Fixed adjustments specify the desired cumulative total against the original item and append a signed row; originals and corrections remain immutable. The fixed-pay-v1 CSV uses unique pay item and original IDs, without invented attendance IDs. Reconcile each original or signed correction item separately (one expected pay item); evidence is administrator-reported. Fixed payments are human-MFA-administrator-only, not delegated by one workplace grant.", "parameters": [ { "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollFixedPayPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-changes/fixed-pay/{id}": { "get": { "operationId": "payrollFixedItem", "description": "Human administrator in the selected workspace with recent authenticator MFA only. API keys are denied. Opaque UUID identifiers: obtain workers from the human team directory, original batch UUIDs from /payroll-exports and attendance UUIDs using /payroll-changes/exports/{id}. Rates use integer minor units, effective from local date until the next dated rate; existing exports remain immutable. Adjustments specify the desired cumulative total for one attendance, not a delta; the server reviews the signed difference including every previous correction. Reconciliation is administrator-reported evidence, not verified provider acceptance; omit adjustment_id for the original frozen batch, or supply one to reconcile that signed adjustment. Reviews expire after five minutes; at most twenty pending reviews per administrator. Persist exact request_id and review_id across uncertain responses. Current authority is checked before replay; changed or expired state returns 409 and requires a fresh review. All responses are no-store. Omit If-Match, Idempotency-Key and write query parameters. Poll history for changes; these records are outside the general sync feed. Generic CSV only; no statutory pay, tax or provider certification is inferred. Effective-dated policy versions must start on their configured ISO week boundary, which cannot subsequently change. Policies use company timezone/currency captured at approval. Thresholds are whole minutes, null disables overtime; multipliers are basis points, 10000 means normal pay. The highest applicable daily/weekly/enhancement multiplier wins without stacking. Entire attendance belongs to its local start day/week and enhancement start window; earlier approved attendance in that week counts even outside the export and when already exported. Recorded sleep-in disturbance time is actual elapsed time, including DST; no break allocation is inferred. Allowances require a single attendance exactly matching a reviewed sleep-in shift. Paid time rounds to configured minutes, then each attendance/pay-code/multiplier component rounds half up to a minor unit. Export format schema_version 2 retains unit, base rate and multiplier, with frozen policy provenance; consume canonical amount_minor rather than treating rate_minor as an enhanced rate. Existing frozen exports remain unchanged. Preview limits: 93 days, 100000 context records, 20000 pay items/issues and 8 MiB. Policy history has at most 1024 immutable versions; newest-first 25 per page. No salary proration, statutory pay or tax is inferred. New reviewed changes support exact-integer totals up to 8000000000000000 minor units. Legacy exports beyond that bound remain readable through the decimal-string /payroll-exports endpoints; the change/raw-UUID namespace rejects them with 422. Fixed salary/pay kinds require an explicit agreed gross amount and a period of at most 366 days, with employee payroll code, pay code, agreement reference and reason. No salary proration is inferred. Active positive salary periods cannot overlap each other or effective paid hourly attendance; a zero cumulative salary reversal permits a replacement period or hourly pay. Increasing a reversed salary rechecks overlapping pay. Salary hours are not automatically used as hourly overtime context. Fixed adjustments specify the desired cumulative total against the original item and append a signed row; originals and corrections remain immutable. The fixed-pay-v1 CSV uses unique pay item and original IDs, without invented attendance IDs. Reconcile each original or signed correction item separately (one expected pay item); evidence is administrator-reported. Fixed payments are human-MFA-administrator-only, not delegated by one workplace grant.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollFixedPay" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-access/workplaces": { "get": { "operationId": "payrollWorkplaces", "description": "Human workspace sessions only; API keys denied. Workplace UUID comes from /payroll-access/workplaces. Money reads and writes require recent authenticator MFA. Administrators or explicit current workplace payroll.read/export/adjust grants; export and adjust imply read. Base manager role does not confer payroll access. Global rates, policy, salary and reconciliation remain administrator-only. Each response contains only this workplace, even for an older global batch; totals and line counts are recomputed. Poll bounded history using both returned cursor values. Reviews expire after five minutes; freeze requires payroll.export. Keep the same request_id, review_id and location_id on uncertain retry. Authority is rechecked before replay. Apply scoped adjustment reviews through /payroll-changes/commands; desired_minor is the cumulative attendance total including prior adjustments. Original exports remain immutable. Omit If-Match and Idempotency-Key; write requests accept no query parameters. All responses are no-store. Generic component CSV only; no payroll provider certification.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollWorkplaces" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payroll-access/review": { "post": { "operationId": "reviewScopedPayroll", "description": "Human workspace sessions only; API keys denied. Workplace UUID comes from /payroll-access/workplaces. Money reads and writes require recent authenticator MFA. Administrators or explicit current workplace payroll.read/export/adjust grants; export and adjust imply read. Base manager role does not confer payroll access. Global rates, policy, salary and reconciliation remain administrator-only. Each response contains only this workplace, even for an older global batch; totals and line counts are recomputed. Poll bounded history using both returned cursor values. Reviews expire after five minutes; freeze requires payroll.export. Keep the same request_id, review_id and location_id on uncertain retry. Authority is rechecked before replay. Apply scoped adjustment reviews through /payroll-changes/commands; desired_minor is the cumulative attendance total including prior adjustments. Original exports remain immutable. Omit If-Match and Idempotency-Key; write requests accept no query parameters. All responses are no-store. Generic component CSV only; no payroll provider certification.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopedPayrollReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewScopedPayrollBody" } } } } } }, "/payroll-access/exports": { "post": { "operationId": "freezeScopedPayroll", "description": "Human workspace sessions only; API keys denied. Workplace UUID comes from /payroll-access/workplaces. Money reads and writes require recent authenticator MFA. Administrators or explicit current workplace payroll.read/export/adjust grants; export and adjust imply read. Base manager role does not confer payroll access. Global rates, policy, salary and reconciliation remain administrator-only. Each response contains only this workplace, even for an older global batch; totals and line counts are recomputed. Poll bounded history using both returned cursor values. Reviews expire after five minutes; freeze requires payroll.export. Keep the same request_id, review_id and location_id on uncertain retry. Authority is rechecked before replay. Apply scoped adjustment reviews through /payroll-changes/commands; desired_minor is the cumulative attendance total including prior adjustments. Original exports remain immutable. Omit If-Match and Idempotency-Key; write requests accept no query parameters. All responses are no-store. Generic component CSV only; no payroll provider certification.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopedPayrollExport" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreezeScopedPayrollBody" } } } } }, "get": { "operationId": "scopedPayrollExports", "description": "Human workspace sessions only; API keys denied. Workplace UUID comes from /payroll-access/workplaces. Money reads and writes require recent authenticator MFA. Administrators or explicit current workplace payroll.read/export/adjust grants; export and adjust imply read. Base manager role does not confer payroll access. Global rates, policy, salary and reconciliation remain administrator-only. Each response contains only this workplace, even for an older global batch; totals and line counts are recomputed. Poll bounded history using both returned cursor values. Reviews expire after five minutes; freeze requires payroll.export. Keep the same request_id, review_id and location_id on uncertain retry. Authority is rechecked before replay. Apply scoped adjustment reviews through /payroll-changes/commands; desired_minor is the cumulative attendance total including prior adjustments. Original exports remain immutable. Omit If-Match and Idempotency-Key; write requests accept no query parameters. All responses are no-store. Generic component CSV only; no payroll provider certification.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopedPayrollExportPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "location_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "id", "schema": { "type": "string", "format": "uuid" } } ] } }, "/payroll-access/exports/{id}": { "get": { "operationId": "scopedPayrollExport", "description": "Human workspace sessions only; API keys denied. Workplace UUID comes from /payroll-access/workplaces. Money reads and writes require recent authenticator MFA. Administrators or explicit current workplace payroll.read/export/adjust grants; export and adjust imply read. Base manager role does not confer payroll access. Global rates, policy, salary and reconciliation remain administrator-only. Each response contains only this workplace, even for an older global batch; totals and line counts are recomputed. Poll bounded history using both returned cursor values. Reviews expire after five minutes; freeze requires payroll.export. Keep the same request_id, review_id and location_id on uncertain retry. Authority is rechecked before replay. Apply scoped adjustment reviews through /payroll-changes/commands; desired_minor is the cumulative attendance total including prior adjustments. Original exports remain immutable. Omit If-Match and Idempotency-Key; write requests accept no query parameters. All responses are no-store. Generic component CSV only; no payroll provider certification.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopedPayrollExport" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "location_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/payroll-access/adjustment-review": { "post": { "operationId": "reviewScopedPayrollAdjustment", "description": "Human workspace sessions only; API keys denied. Workplace UUID comes from /payroll-access/workplaces. Money reads and writes require recent authenticator MFA. Administrators or explicit current workplace payroll.read/export/adjust grants; export and adjust imply read. Base manager role does not confer payroll access. Global rates, policy, salary and reconciliation remain administrator-only. Each response contains only this workplace, even for an older global batch; totals and line counts are recomputed. Poll bounded history using both returned cursor values. Reviews expire after five minutes; freeze requires payroll.export. Keep the same request_id, review_id and location_id on uncertain retry. Authority is rechecked before replay. Apply scoped adjustment reviews through /payroll-changes/commands; desired_minor is the cumulative attendance total including prior adjustments. Original exports remain immutable. Omit If-Match and Idempotency-Key; write requests accept no query parameters. All responses are no-store. Generic component CSV only; no payroll provider certification.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopedPayrollAdjustmentReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewScopedPayrollAdjustmentBody" } } } } } }, "/payroll-access/adjustments": { "get": { "operationId": "scopedPayrollAdjustments", "description": "Human workspace sessions only; API keys denied. Workplace UUID comes from /payroll-access/workplaces. Money reads and writes require recent authenticator MFA. Administrators or explicit current workplace payroll.read/export/adjust grants; export and adjust imply read. Base manager role does not confer payroll access. Global rates, policy, salary and reconciliation remain administrator-only. Each response contains only this workplace, even for an older global batch; totals and line counts are recomputed. Poll bounded history using both returned cursor values. Reviews expire after five minutes; freeze requires payroll.export. Keep the same request_id, review_id and location_id on uncertain retry. Authority is rechecked before replay. Apply scoped adjustment reviews through /payroll-changes/commands; desired_minor is the cumulative attendance total including prior adjustments. Original exports remain immutable. Omit If-Match and Idempotency-Key; write requests accept no query parameters. All responses are no-store. Generic component CSV only; no payroll provider certification.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopedPayrollAdjustmentPage" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or inaccessible payroll source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Calculation or exact-integer limits exceeded; reduce the scope or use decimal-string legacy export reads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "location_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "id", "schema": { "type": "string", "format": "uuid" } } ] } }, "/workspace/rota-roster": { "get": { "operationId": "workspaceRotaRoster", "description": "Human workspace session required; API keys denied. Select membership with X-ShiftForest-Workspace. Omit If-Match and Idempotency-Key. Responses are no-store. IDs are workforce UUIDs, not numeric integration IDs or Auth IDs. Current tenant and workplace authority is checked on every read. Employee peer records redact email, pay, employee code and weekly limits; login status and row revision are omitted. Compare scope_hash across pages or participant batches and discard the traversal if it changes. These reads are not an authorization grant or an immutable snapshot. Includes workers with no shifts. total counts all current matching workers within the insertion boundary, independently of page size. Use next_cursor unchanged with identical filters and limit; cursors expire after one hour. Later insertions are excluded, while edits and removals remain live. Search is case-insensitive name substring; role_tag is exact. Maximum 100,000 matching workers. Employee own-rota preferences restrict results to self. A privacy synchronization reset invalidates older cursors with HTTP 410; clear stored replica data and rebuild from a fresh checkpoint/snapshot before resuming.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceRotaRoster" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workspace access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor filters or authority changed; restart traversal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Supported result budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Privacy synchronization reset: discard the local replica and restart its checkpoint and snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "location", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "role_tag", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 } } ] } }, "/workspace/participants": { "post": { "operationId": "workspaceParticipants", "description": "Human workspace session required; API keys denied. Select membership with X-ShiftForest-Workspace. Omit If-Match and Idempotency-Key. Responses are no-store. IDs are workforce UUIDs, not numeric integration IDs or Auth IDs. Current tenant and workplace authority is checked on every read. Employee peer records redact email, pay, employee code and weekly limits; login status and row revision are omitted. Compare scope_hash across pages or participant batches and discard the traversal if it changes. These reads are not an authorization grant or an immutable snapshot. Submit 1\u2013500 distinct user_ids without query parameters. Only requested profiles within current visibility are returned; unavailable IDs are omitted. Assignment rows are restricted to current workplace scope. This is a participant projection, never a complete company directory. Maximum 10,000 assignments and 8 MiB per response.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceParticipants" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workspace access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cursor filters or authority changed; restart traversal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Supported result budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceParticipantsBody" } } } } } }, "/privacy/documents/{version_id}/deletion/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "review_document_deletion", "description": "Human session and recent MFA required. Review, authorization and retry require the current workspace owner; status requires an administrator. Immutable authorization revokes access immediately; only independent provider absence verification marks completion. Metadata, backups and downloaded copies are retained separately. Active subject holds and unelapsed owner-approved retention block authorization. Deletion is disabled until commissioned. No query parameters, If-Match or Idempotency-Key. Persist the exact request_id and body across retries; review again after a state conflict. Cache-Control: no-store. Retry uses the observed attempt count and never authorizes a new object.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDeletionReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deletion record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deletion worker not commissioned or temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } } } } } } } }, "/privacy/documents/{version_id}/deletion": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "document_deletion_status", "description": "Human session and recent MFA required. Review, authorization and retry require the current workspace owner; status requires an administrator. Immutable authorization revokes access immediately; only independent provider absence verification marks completion. Metadata, backups and downloaded copies are retained separately. Active subject holds and unelapsed owner-approved retention block authorization. Deletion is disabled until commissioned. No query parameters, If-Match or Idempotency-Key. Persist the exact request_id and body across retries; review again after a state conflict. Cache-Control: no-store. Retry uses the observed attempt count and never authorizes a new object.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDeletionStatus" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deletion record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deletion worker not commissioned or temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "authorize_document_deletion", "description": "Human session and recent MFA required. Review, authorization and retry require the current workspace owner; status requires an administrator. Immutable authorization revokes access immediately; only independent provider absence verification marks completion. Metadata, backups and downloaded copies are retained separately. Active subject holds and unelapsed owner-approved retention block authorization. Deletion is disabled until commissioned. No query parameters, If-Match or Idempotency-Key. Persist the exact request_id and body across retries; review again after a state conflict. Cache-Control: no-store. Retry uses the observed attempt count and never authorizes a new object.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDeletionAuthorized" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deletion record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deletion worker not commissioned or temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "reason", "confirmed", "review_token" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "confirmed": { "const": true }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } } } } } }, "/privacy/documents/{version_id}/deletion/retry": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "retry_document_deletion", "description": "Human session and recent MFA required. Review, authorization and retry require the current workspace owner; status requires an administrator. Immutable authorization revokes access immediately; only independent provider absence verification marks completion. Metadata, backups and downloaded copies are retained separately. Active subject holds and unelapsed owner-approved retention block authorization. Deletion is disabled until commissioned. No query parameters, If-Match or Idempotency-Key. Persist the exact request_id and body across retries; review again after a state conflict. Cache-Control: no-store. Retry uses the observed attempt count and never authorizes a new object.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDeletionRetried" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Human membership, administrator/owner scope or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deletion record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deletion worker not commissioned or temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "reason", "confirmed", "attempts" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "confirmed": { "const": true }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9999 } } } } } } } }, "/privacy/requests/{case_id}/profile-redaction/review": { "post": { "operationId": "review_primary_profile_redaction", "description": "Human workspace session only. Recent MFA is required. Current owner may review/apply removal of primary name, email, role tag/avatar and current API profile details for an open erasure case after reviewed offboarding and approved profile retention. Active holds or pending operational dependencies block removal. Employee code/pay/hour fields, authentication/provisioning identities, historical records, files, backups and independent copies remain. This partial action does not close the request or assert complete erasure. Persist request_id and the exact reviewed body for retries. Do not send If-Match or Idempotency-Key.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRedactionReview" } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 1000 } } } } } } } }, "/privacy/requests/{case_id}/profile-redaction": { "post": { "operationId": "apply_primary_profile_redaction", "description": "Human workspace session only. Recent MFA is required. Current owner may review/apply removal of primary name, email, role tag/avatar and current API profile details for an open erasure case after reviewed offboarding and approved profile retention. Active holds or pending operational dependencies block removal. Employee code/pay/hour fields, authentication/provisioning identities, historical records, files, backups and independent copies remain. This partial action does not close the request or assert complete erasure. Persist request_id and the exact reviewed body for retries. Do not send If-Match or Idempotency-Key.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRedactionResult" } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "review_token", "reason", "confirmed" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1000 }, "confirmed": { "type": "boolean", "const": true } } } } } } }, "get": { "operationId": "get_primary_profile_redaction", "description": "Human workspace session only. Recent MFA is required. Current owner may review/apply removal of primary name, email, role tag/avatar and current API profile details for an open erasure case after reviewed offboarding and approved profile retention. Active holds or pending operational dependencies block removal. Employee code/pay/hour fields, authentication/provisioning identities, historical records, files, backups and independent copies remain. This partial action does not close the request or assert complete erasure. Persist request_id and the exact reviewed body for retries. Do not send If-Match or Idempotency-Key.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRedactionResult" }, { "type": "null" } ] } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leave-ledger/{account_id}/accrual-rule": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getLeaveAccrualRule", "description": "Contractual calendar-day accrual, not statutory entitlement determination. period_quantity is the allowance for the full account period before inclusive eligibility proration. already_awarded is the base grant outside automation, excluding automatic entries, carryover and exceptional adjustments; it is not the remaining balance. Daily posting credits completed local days. Month-end credits completed calendar months by calendar-day weight, not equal twelfths; final partial months wait until month end. Upfront credits the eligible allowance from eligibility start. Cumulative four-decimal rounding prevents repeated-run drift. Rule approval applies the reviewed current correction immediately; paused policies post zero. Later runs pause on inactive worker, changed approving-admin access, changed work pattern, or negative correction. Human writes require another administrator and recent MFA. Scoped independent integrations need leave:read for GET; legacy keys denied. Persist request_id and exact body for uncertain retries. 409 needs fresh review. Omit Idempotency-Key and If-Match. No query parameters. All responses are no-store; poll separately from the change feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveAccrualState" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "setLeaveAccrualRule", "description": "Contractual calendar-day accrual, not statutory entitlement determination. period_quantity is the allowance for the full account period before inclusive eligibility proration. already_awarded is the base grant outside automation, excluding automatic entries, carryover and exceptional adjustments; it is not the remaining balance. Daily posting credits completed local days. Month-end credits completed calendar months by calendar-day weight, not equal twelfths; final partial months wait until month end. Upfront credits the eligible allowance from eligibility start. Cumulative four-decimal rounding prevents repeated-run drift. Rule approval applies the reviewed current correction immediately; paused policies post zero. Later runs pause on inactive worker, changed approving-admin access, changed work pattern, or negative correction. Human writes require another administrator and recent MFA. Scoped independent integrations need leave:read for GET; legacy keys denied. Persist request_id and exact body for uncertain retries. 409 needs fresh review. Omit Idempotency-Key and If-Match. No query parameters. All responses are no-store; poll separately from the change feed. ", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveAccrualResult" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/LeaveAccrualPolicy" }, "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmed": { "const": true } }, "required": [ "policy", "request_id", "review_token", "confirmed" ], "additionalProperties": false } } } } } }, "/leave-ledger/{account_id}/accrual-rule/review": { "parameters": [ { "$ref": "#/components/parameters/Workspace" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "reviewLeaveAccrualRule", "description": "Contractual calendar-day accrual, not statutory entitlement determination. period_quantity is the allowance for the full account period before inclusive eligibility proration. already_awarded is the base grant outside automation, excluding automatic entries, carryover and exceptional adjustments; it is not the remaining balance. Daily posting credits completed local days. Month-end credits completed calendar months by calendar-day weight, not equal twelfths; final partial months wait until month end. Upfront credits the eligible allowance from eligibility start. Cumulative four-decimal rounding prevents repeated-run drift. Rule approval applies the reviewed current correction immediately; paused policies post zero. Later runs pause on inactive worker, changed approving-admin access, changed work pattern, or negative correction. Human writes require another administrator and recent MFA. Scoped independent integrations need leave:read for GET; legacy keys denied. Persist request_id and exact body for uncertain retries. 409 needs fresh review. Omit Idempotency-Key and If-Match. No query parameters. All responses are no-store; poll separately from the change feed. Review token binds account, worker revision, local date, prior rule, work pattern and ledger state.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveAccrualReview" } } } }, "400": { "description": "Invalid fields, policy, state or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Worker scope, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/LeaveAccrualPolicy" } }, "required": [ "policy" ], "additionalProperties": false } } } } } }, "/resource-changes/review": { "post": { "operationId": "reviewResourceChange", "description": "Human workspace sessions with recent authenticator MFA only; independent and compatibility keys are denied. Credential changes require a workspace administrator. Attendance corrections/approvals require a manager with current worker and original-workplace access, and another manager for their own records. A manager who recorded any correction cannot approve that attendance. These commands update existing recorded attendance, not employee clock evidence or new manual attendance. Credential user_id is a worker UUID from the human team directory. Attendance review inputs use the public numeric IDs returned by /attendance; the server resolves them within the selected workspace. Reviewed facts and receipts identify canonical records with internal UUIDs. POST review returns the exact current/proposed facts for explicit human confirmation. Five-minute review lifetime, twenty pending reviews per actor, at most 100 unique approvals. Keep the same request_id and review_id for uncertain retries; replays recheck current scope before returning a historical receipt. Changed facts, expired review, voided attendance or locked payroll require a fresh review or controlled payroll adjustment. Corrections return approval to pending and keep attendance audit history. Credential dates are nullable local ISO dates; recorded status is human-attested metadata, not provider verification. Resulting canonical resources appear in the existing attendance/credential change feed. No query parameters, If-Match or Idempotency-Key. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceChangeReview" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or unavailable source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid resource state or bounded operation limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceChangeInput" } } } } } }, "/resource-changes/commands": { "post": { "operationId": "applyResourceChange", "description": "Human workspace sessions with recent authenticator MFA only; independent and compatibility keys are denied. Credential changes require a workspace administrator. Attendance corrections/approvals require a manager with current worker and original-workplace access, and another manager for their own records. A manager who recorded any correction cannot approve that attendance. These commands update existing recorded attendance, not employee clock evidence or new manual attendance. Credential user_id is a worker UUID from the human team directory. Attendance review inputs use the public numeric IDs returned by /attendance; the server resolves them within the selected workspace. Reviewed facts and receipts identify canonical records with internal UUIDs. POST review returns the exact current/proposed facts for explicit human confirmation. Five-minute review lifetime, twenty pending reviews per actor, at most 100 unique approvals. Keep the same request_id and review_id for uncertain retries; replays recheck current scope before returning a historical receipt. Changed facts, expired review, voided attendance or locked payroll require a fresh review or controlled payroll adjustment. Corrections return approval to pending and keep attendance audit history. Credential dates are nullable local ISO dates; recorded status is human-attested metadata, not provider verification. Resulting canonical resources appear in the existing attendance/credential change feed. No query parameters, If-Match or Idempotency-Key. Responses are no-store.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceChangeReceipt" } } } }, "400": { "description": "Invalid fields, scope or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Inactive or invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current workplace access, human session or recent MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown endpoint or unavailable source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reviewed state changed or command identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure; retain exact command for retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid resource state or bounded operation limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_id": { "type": "string", "format": "uuid" }, "confirmed": { "const": true } }, "required": [ "request_id", "review_id", "confirmed" ] } } } } } }, "/privacy/requests/{case_id}/credential-erasure/review": { "post": { "operationId": "review_linked_credential_erasure", "description": "Human workspace session and recent MFA required. The current owner reviews/applies removal of linked credential source, audit, command, pending-review and invalidation records after primary-profile removal and approved credentials/audit/integrations retention. Event-based policies conservatively use the latest linked event or offboarding, including pending-review expiry. Any active workspace hold, retained personal/shared export, unverified document absence or unlinked legacy history blocks application. Administrators may read status. Explicit confirmation, a current review token and commissioning are required; preserve the exact request ID/body for retries. Reintroduction is blocked and consumers must clear replicas after a 410 reset. Other workforce/actor history, document metadata and external copies remain. This partial action never closes the case or claims complete erasure. Omit query parameters, If-Match and Idempotency-Key.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialErasureReview" } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} } } } } } }, "/privacy/requests/{case_id}/credential-erasure": { "post": { "operationId": "apply_linked_credential_erasure", "description": "Human workspace session and recent MFA required. The current owner reviews/applies removal of linked credential source, audit, command, pending-review and invalidation records after primary-profile removal and approved credentials/audit/integrations retention. Event-based policies conservatively use the latest linked event or offboarding, including pending-review expiry. Any active workspace hold, retained personal/shared export, unverified document absence or unlinked legacy history blocks application. Administrators may read status. Explicit confirmation, a current review token and commissioning are required; preserve the exact request ID/body for retries. Reintroduction is blocked and consumers must clear replicas after a 410 reset. Other workforce/actor history, document metadata and external copies remain. This partial action never closes the case or claims complete erasure. Omit query parameters, If-Match and Idempotency-Key.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialErasureResult" } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "review_token", "confirmed" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "confirmed": { "type": "boolean", "const": true } } } } } } }, "get": { "operationId": "get_linked_credential_erasure", "description": "Human workspace session and recent MFA required. The current owner reviews/applies removal of linked credential source, audit, command, pending-review and invalidation records after primary-profile removal and approved credentials/audit/integrations retention. Event-based policies conservatively use the latest linked event or offboarding, including pending-review expiry. Any active workspace hold, retained personal/shared export, unverified document absence or unlinked legacy history blocks application. Administrators may read status. Explicit confirmation, a current review token and commissioning are required; preserve the exact request ID/body for retries. Reintroduction is blocked and consumers must clear replicas after a 410 reset. Other workforce/actor history, document metadata and external copies remain. This partial action never closes the case or claims complete erasure. Omit query parameters, If-Match and Idempotency-Key.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CredentialErasureResult" }, { "type": "null" } ] } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/privacy/requests/{case_id}/attendance-history-erasure/review": { "post": { "operationId": "review_attendance_history_erasure", "description": "Human-session privacy workflow. Review and application require current workspace ownership and recent authenticator MFA; status requires an authorized administrator. After primary-profile removal and approved attendance/audit/integration retention, redact this worker from applied attendance correction and shared approval commands, invalidate affected pending reviews, and preserve colleagues, actor/retry identities and original aggregate counts. Canonical clock records, payroll, clock-event journals and external copies remain. Active workspace holds, retained exports, document-provider absence, ambiguous history and unreviewed schema changes block application. Application is independently commissioned and never closes the privacy case. Preserve request_id and the exact confirmed review body for uncertain retries. Redacted attendance command receipts cannot be replayed. A sync-generation change requires connected replicas to rebuild; no external-copy deletion is implied.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceHistoryErasureReview" } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": {} } } } }, "summary": "Review attendance command-history redaction" } }, "/privacy/requests/{case_id}/attendance-history-erasure": { "post": { "operationId": "apply_attendance_history_erasure", "description": "Human-session privacy workflow. Review and application require current workspace ownership and recent authenticator MFA; status requires an authorized administrator. After primary-profile removal and approved attendance/audit/integration retention, redact this worker from applied attendance correction and shared approval commands, invalidate affected pending reviews, and preserve colleagues, actor/retry identities and original aggregate counts. Canonical clock records, payroll, clock-event journals and external copies remain. Active workspace holds, retained exports, document-provider absence, ambiguous history and unreviewed schema changes block application. Application is independently commissioned and never closes the privacy case. Preserve request_id and the exact confirmed review body for uncertain retries. Redacted attendance command receipts cannot be replayed. A sync-generation change requires connected replicas to rebuild; no external-copy deletion is implied.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceHistoryErasureResult" } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "review_token", "confirmed" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "review_token": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "confirmed": { "type": "boolean", "const": true } } } } } }, "summary": "Apply reviewed attendance command-history redaction" }, "get": { "operationId": "get_attendance_history_erasure", "description": "Human-session privacy workflow. Review and application require current workspace ownership and recent authenticator MFA; status requires an authorized administrator. After primary-profile removal and approved attendance/audit/integration retention, redact this worker from applied attendance correction and shared approval commands, invalidate affected pending reviews, and preserve colleagues, actor/retry identities and original aggregate counts. Canonical clock records, payroll, clock-event journals and external copies remain. Active workspace holds, retained exports, document-provider absence, ambiguous history and unreviewed schema changes block application. Application is independently commissioned and never closes the privacy case. Preserve request_id and the exact confirmed review body for uncertain retries. Redacted attendance command receipts cannot be replayed. A sync-generation change requires connected replicas to rebuild; no external-copy deletion is implied.", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reviewed partial action or current status; null means no prior removal", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AttendanceHistoryErasureResult" }, { "type": "null" } ] } } } }, "400": { "description": "Invalid fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Active session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current authority or MFA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Review changed or removal blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not commissioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get status of attendance command-history redaction" } } }, "webhooks": { "shiftChange": { "post": { "description": "Exact changes-feed entry; RotaTree-Signature: t=,v1=. Retry for 24h; replay preserves event_id/sequence. Reject stale timestamps and deduplicate event IDs.", "parameters": [ { "name": "RotaTree-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Change" } } } }, "responses": { "200": { "description": "Acknowledged" } } } } } }