{ "openapi": "3.1.0", "info": { "title": "jeCheck API", "version": "1.0.0", "description": "REST API of jeCheck — audits, tasks, SOP routines, HACCP, staff schedule, testing, knowledge base and analytics for multi-location businesses. Authenticate with `Authorization: Bearer `. Every request acts with the permissions of the token's user. Guides: https://jecheck.io/developers", "contact": { "name": "jeCheck support", "email": "support@jecheck.io", "url": "https://jecheck.io/developers" }, "termsOfService": "https://jecheck.io/legal/terms" }, "servers": [ { "url": "https://app.jecheck.io/api/ext/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Identify the token: the acting user, the company, the plan and the effective permissions. Call `GET /me` first to check that a key works.", "x-section": "account" }, { "name": "Locations", "description": "Locations (venues, stores, branches) and regions: the list the token can see, location cards, staff and managers. Location ids are used as filters across the whole API. Creating and editing locations needs `locations.manage`; staff and managers — `locations.staff`.", "x-section": "locations" }, { "name": "Employees", "description": "Employees of the company: list with filters, employee cards, adding and editing employees, deactivation, passwords and invitations, the positions directory. Visibility follows `users.view` (employees of the locations where it applies); email and phone are returned only with `users.contacts`.", "x-section": "users" }, { "name": "Checklists", "description": "Audit checklists and their folders: list, read the full structure (sections, questions, answer types, weights, photo requirements, display conditions), create a checklist from a JSON structure, edit, duplicate, move, delete and restore, and control who may run a checklist in the mobile app.", "x-section": "checklists" }, { "name": "Audits", "description": "Conducted audits (inspections by checklist): the audit journal with filters, the result card with sections, failed questions, comments and photos, PDF reports, deletion and submitting a new audit. Visibility follows the web journal — audits of the locations where the token has `audits.view`.", "x-section": "audits" }, { "name": "Analytics", "description": "Audit analytics with the same numbers as the web analytics pages: company overview, location ranking and drill-down, checklist and question statistics, top violations, auditor strictness, plan fulfilment, corrective tasks, the AI control brief and employee tests. Figures cover only the locations where the token has `analytics.view`. Long lists end with an item `{\"_truncated\": N}` saying how many rows were cut.", "x-section": "analytics" }, { "name": "Audit planner", "description": "Planned audits: the calendar of scheduled inspections with computed statuses (planned, in progress, overdue, missed, done), audit plans and recurring series across locations, rescheduling, reassigning, cancelling and marking as done, and plan templates.", "x-section": "planner" }, { "name": "Tasks", "description": "Tasks and corrective actions: create, assign, comment, attach files, move through statuses. Visibility follows the web app: the token sees tasks of its locations (`tasks.view_all`), its teams, its projects and the tasks it is involved in.", "x-section": "tasks" }, { "name": "Projects", "description": "Projects with task numbers (KEY-N), sections, board columns, milestones, custom fields, members with project roles, external guests, status updates and automation rules. Access follows the project role (viewer, commenter, editor, admin); `projects.manage` acts as admin in every project. Tasks themselves are managed in the Tasks section with `project_id`.", "x-section": "projects" }, { "name": "Processes & requests", "description": "Business processes (purchase, repair, refund…) with a request form and an approval route. Submit requests, see what waits for your decision, approve, return, reject, delegate, complete and track the route. Managing process definitions requires `processes.manage`; analytics — `processes.reports`.", "x-section": "processes" }, { "name": "Teams", "description": "Departments and teams (maintenance, IT, cleaning…): members and heads, served locations, task queue and its distribution, team schedule, QR request points. `org.view` sees all teams, a team head sees own teams, members see their teams and queue; changes require `org.manage`. Taking a queued task — `tasks.take`.", "x-section": "teams" }, { "name": "Automation", "description": "Closed-loop automation: scenarios that turn audit violations into corrective tasks (who fixes, deadline, photo \"after\", confirmation, reminders, escalation), and the loop steps of such tasks — upload a photo \"after\", submit, accept or return. Scenarios require `automation.manage` and the paid feature `automation`.", "x-section": "automation" }, { "name": "Routines", "description": "Shift routines (SOPs without scores): routine templates with sections, steps and schedules; runs at locations with step marks, photos, completion and manager review. Visibility follows location permissions (`routines.view`, `routines.fill`, `routines.control`).", "x-section": "routines" }, { "name": "HACCP", "description": "Food-safety journals (HACCP): today's checks per location, journal entries with automatic limit checks, deviations with corrective actions, registries (equipment, suppliers, verification, medical books) and the HACCP plan. Locations follow `haccp.view`; medical books require the sensitive `haccp.medical` permission.", "x-section": "haccp" }, { "name": "Schedule & attendance", "description": "Staff schedule: shifts, publishing, open shifts, clock-in/out with breaks, who is on shift now, attendance records, timesheet, absences and shift swaps, availability, KPI and payroll. Location permissions follow `schedule.*`; pay rates and payroll require `pay.*` and are omitted otherwise.", "x-section": "schedule" }, { "name": "HR", "description": "Employee HR records: the HR card, personal data, HR documents, hiring with onboarding checklists, transfers, dismissal and absences (vacations, sick leave). Permissions apply to the employee's locations; personal data, documents and pay rates are returned only with their own permissions and every view is written to the access log.", "x-section": "hr" }, { "name": "Instructions", "description": "Company knowledge base: folders, documents with published versions, read acknowledgements and editing. Visibility follows the document and folder permissions of the acting user (\"who can view / who can edit\"); content is returned as Markdown, HTML or plain text and accepted as Markdown or HTML.", "x-section": "instructions" }, { "name": "Employee testing", "description": "Knowledge tests for employees: build tests and questions, assign them to people, positions or locations, read results, grade open answers — and take assigned tests as the acting user. Results are limited to employees of the locations of the `testing.results` / `testing.review` permissions.", "x-section": "testing" }, { "name": "Mystery shopper", "description": "Mystery shopper visits without an app: create visits with a personal link for a guest, review submitted questionnaires with automatic fraud flags, accept a visit into a regular audit, manage the guest pool and payouts, and order turnkey checks performed by jeCheck guests.", "x-section": "mystery" }, { "name": "Dashboards", "description": "Custom dashboards of cards built from the metrics catalog (audits, tasks, HACCP, schedule…). List and read dashboards, get computed card data (always limited by the viewer's permissions and locations), create and edit dashboards and cards, share them with colleagues or the whole company (`dashboards.company`).", "x-section": "dashboards" }, { "name": "Notifications", "description": "In-app notifications of the acting user (the bell in the web app and the Notifications screen in the mobile app): list, unread count, mark as read, and personal notification settings. A company key sees the notifications of its service user.", "x-section": "notifications" }, { "name": "Guest feedback", "description": "Guest reviews of locations collected from map services (Yandex Maps, 2GIS, TripAdvisor, Delivery Club) with sentiment analysis, and customer appeals from the company Telegram / WhatsApp bot with replies. Reviews need `reviews.view` (limited to its locations); appeals need `appeals.view`.", "x-section": "feedback" }, { "name": "Roles & permissions", "description": "The permission catalog, company roles, effective permissions of an employee and the access log. Changes follow the delegation rules of the web app: a non-administrator can grant only permissions they hold themselves, only on their own locations, and cannot change administrators.", "x-section": "access" }, { "name": "Help center", "description": "Search and read the jeCheck help center (jecheck.io/docs): how features work, where settings are, rules for scores, permissions and plans. Articles are returned in Markdown, in English by default. Available to every token.", "x-section": "help" } ], "paths": { "/access/log": { "get": { "operationId": "accessLogList", "summary": "List access log entries", "description": "Changes of roles and permissions, administrators and managers, views of sensitive data, exports and denied attempts — newest first.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_log_list", "x-permissions": [ "access.log" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "user_id", "in": "query", "description": "Entries where this employee is the actor or the subject", "schema": { "type": "integer" } }, { "name": "kind", "in": "query", "description": "Kind of entries", "schema": { "type": "string", "enum": [ "changes", "view", "export", "denied" ] } }, { "name": "permission", "in": "query", "description": "Permission key", "schema": { "type": "string", "maxLength": 64 } }, { "name": "date_from", "in": "query", "description": "From date (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "To date (inclusive)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "event": { "type": "string" }, "event_label": { "type": "string" }, "actor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "subject": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "permission": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "data": { "type": "object", "properties": { "name": { "type": "string" } } }, "ip": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 90211, "event": "role_assign", "event_label": "Role assigned", "actor": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "subject": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": { "id": 41, "name": "Auditor" }, "permission": null, "location": null, "data": { "name": "Auditor" }, "ip": "10.0.0.4", "created_at": "2026-11-03T10:15:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/access/permissions": { "get": { "operationId": "accessPermissionsList", "summary": "List the permission catalog", "description": "Every permission key with its group, label, description, whether it can be limited to locations (`scoped`), whether views are logged (`sensitive`) and the permissions it requires.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_permissions_list", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "group": { "type": "string" }, "group_label": { "type": "string" }, "label": { "type": "string" }, "hint": { "type": "string" }, "description": { "type": "string" }, "scoped": { "type": "boolean" }, "sensitive": { "type": "boolean" }, "requires": { "type": "array" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "key": "users.contacts", "group": "users", "group_label": "Employees", "label": "Employee phone and email", "hint": "See email and phone in the list and card", "description": "Email and phone of employees in the list, card and export.", "scoped": true, "sensitive": false, "requires": [] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/access/roles": { "get": { "operationId": "accessRolesList", "summary": "List roles", "description": "Company roles with their permissions and members. System roles (`system_key`: `employee` — everyone, `location_manager` — managers of locations and regions) are applied automatically and cannot be assigned or deleted.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_roles_list", "x-permissions": [ "access.manage", "access.roles", "access.log" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "system_key": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 41, "system_key": null, "name": "Auditor", "description": "Runs audits and reviews results", "color": "#5249e6", "permissions": [ { "key": "audits.view", "scope": "all", "location_ids": [] }, { "key": "tasks.view_all", "scope": "list", "location_ids": [ 12, 14 ] } ], "members": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "accessRolesCreate", "summary": "Create a role", "description": "A non-administrator can include only permissions they hold, within their own locations. Written to the access log.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_roles_create", "x-permissions": [ "access.roles" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Role name (system roles cannot be renamed)", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "color": { "type": [ "string", "null" ], "description": "Hex color", "maxLength": 9 }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Permission key from `GET /access/permissions`", "maxLength": 64 }, "scope": { "type": "string", "enum": [ "all", "own", "managed", "list" ], "description": "Location scope, default `all`" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Locations for `scope: list`" } }, "required": [ "key" ] }, "description": "Full list of the role permissions (replaces the current list). Required dependencies are added automatically. `scope`: `all` — all locations, `own` — the member's own locations, `managed` — locations the member manages, `list` — `location_ids`", "maxItems": 300 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "color": "string", "permissions": [ { "key": "string", "scope": "all", "location_ids": [ 12, 14 ] } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "system_key": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 41, "system_key": null, "name": "Auditor", "description": "Runs audits and reviews results", "color": "#5249e6", "permissions": [ { "key": "audits.view", "scope": "all", "location_ids": [] }, { "key": "tasks.view_all", "scope": "list", "location_ids": [ 12, 14 ] } ], "members": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/access/roles/{id}": { "get": { "operationId": "accessRolesGet", "summary": "Retrieve a role", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_roles_get", "x-permissions": [ "access.manage", "access.roles", "access.log" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "system_key": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 41, "system_key": null, "name": "Auditor", "description": "Runs audits and reviews results", "color": "#5249e6", "permissions": [ { "key": "audits.view", "scope": "all", "location_ids": [] }, { "key": "tasks.view_all", "scope": "list", "location_ids": [ 12, 14 ] } ], "members": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "accessRolesUpdate", "summary": "Update a role", "description": "Partial update. `permissions`, when passed, replaces the whole list. Members get the new permissions immediately.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_roles_update", "x-permissions": [ "access.roles" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Role name (system roles cannot be renamed)", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "color": { "type": [ "string", "null" ], "description": "Hex color", "maxLength": 9 }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Permission key from `GET /access/permissions`", "maxLength": 64 }, "scope": { "type": "string", "enum": [ "all", "own", "managed", "list" ], "description": "Location scope, default `all`" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Locations for `scope: list`" } }, "required": [ "key" ] }, "description": "Full list of the role permissions (replaces the current list). Required dependencies are added automatically. `scope`: `all` — all locations, `own` — the member's own locations, `managed` — locations the member manages, `list` — `location_ids`", "maxItems": 300 } } }, "example": { "name": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "color": "string", "permissions": [ { "key": "string", "scope": "all", "location_ids": [ 12, 14 ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "system_key": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 41, "system_key": null, "name": "Auditor", "description": "Runs audits and reviews results", "color": "#5249e6", "permissions": [ { "key": "audits.view", "scope": "all", "location_ids": [] }, { "key": "tasks.view_all", "scope": "list", "location_ids": [ 12, 14 ] } ], "members": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "accessRolesDelete", "summary": "Delete a role", "description": "Members lose the permissions of the role. System roles cannot be deleted.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_roles_delete", "x-permissions": [ "access.roles" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/access/roles/{id}/members": { "put": { "operationId": "accessRolesMembersSet", "summary": "Set role members", "description": "Replaces the members of a (non-system) role. Each assignment and removal is checked against the delegation rules and logged.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_roles_members_set", "x-permissions": [ "access.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Role id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "integer" }, "description": "Employee ids", "maxItems": 1000 } }, "required": [ "user_ids" ] }, "example": { "user_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "system_key": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 41, "system_key": null, "name": "Auditor", "description": "Runs audits and reviews results", "color": "#5249e6", "permissions": [ { "key": "audits.view", "scope": "all", "location_ids": [] }, { "key": "tasks.view_all", "scope": "list", "location_ids": [ 12, 14 ] } ], "members": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/access/users/{id}": { "get": { "operationId": "accessUsersGet", "summary": "Get permissions of an employee", "description": "Roles, personal grants and denials, and effective permissions with the locations where each applies (`location_ids: null` — all locations) and where it comes from. With only `users.access` the response contains just `user` and `account` (administrator and web-cabinet flags).", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_users_get", "x-permissions": [ "access.manage", "access.roles", "access.log", "users.access" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "account": { "type": "object", "properties": { "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "manages_locations": { "type": "array", "items": { "type": "string" } }, "manages_regions": { "type": "array" }, "can_change_admin": { "type": "boolean" }, "can_change_web_access": { "type": "boolean" } } }, "role_ids": { "type": "array", "items": { "type": "integer" } }, "system_role_ids": { "type": "array", "items": { "type": "integer" } }, "personal": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "effect": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array", "items": { "type": "integer" } } } } }, "effective": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "location_ids": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "role_id": { "type": "integer" }, "role": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } } } } }, "can_edit": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "account": { "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "manages_locations": [ "Abay Ave" ], "manages_regions": [], "can_change_admin": true, "can_change_web_access": true }, "role_ids": [ 41 ], "system_role_ids": [ 1, 2 ], "personal": [ { "key": "users.contacts", "effect": "grant", "scope": "list", "location_ids": [ 12 ] } ], "effective": [ { "key": "audits.view", "location_ids": null, "sources": [ { "source": "role", "role_id": 41, "role": "Auditor", "scope": "all", "location_ids": [] } ] } ], "can_edit": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "accessUsersUpdate", "summary": "Set roles and personal permissions of an employee", "description": "Replaces the employee's roles (`role_ids`) and/or personal permissions (`personal`); an omitted field keeps its current value. Administrators and yourself cannot be changed. Every change is logged.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_users_update", "x-permissions": [ "access.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "role_ids": { "type": "array", "items": { "type": "integer" }, "description": "Ids of company (non-system) roles", "maxItems": 100 }, "personal": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Permission key from `GET /access/permissions`", "maxLength": 64 }, "effect": { "type": "string", "enum": [ "grant", "deny" ], "description": "`grant` or `deny` (deny overrides roles)" }, "scope": { "type": "string", "enum": [ "all", "own", "managed", "list" ], "description": "Location scope, default `all`" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Locations for `scope: list`" } }, "required": [ "key", "effect" ] }, "description": "Personal grants and denials", "maxItems": 300 } } }, "example": { "role_ids": [ 12, 14 ], "personal": [ { "key": "string", "effect": "grant", "scope": "all" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "account": { "type": "object", "properties": { "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "manages_locations": { "type": "array", "items": { "type": "string" } }, "manages_regions": { "type": "array" }, "can_change_admin": { "type": "boolean" }, "can_change_web_access": { "type": "boolean" } } }, "role_ids": { "type": "array", "items": { "type": "integer" } }, "system_role_ids": { "type": "array", "items": { "type": "integer" } }, "personal": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "effect": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array", "items": { "type": "integer" } } } } }, "effective": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "location_ids": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "role_id": { "type": "integer" }, "role": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } } } } }, "can_edit": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "account": { "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "manages_locations": [ "Abay Ave" ], "manages_regions": [], "can_change_admin": true, "can_change_web_access": true }, "role_ids": [ 41 ], "system_role_ids": [ 1, 2 ], "personal": [ { "key": "users.contacts", "effect": "grant", "scope": "list", "location_ids": [ 12 ] } ], "effective": [ { "key": "audits.view", "location_ids": null, "sources": [ { "source": "role", "role_id": 41, "role": "Auditor", "scope": "all", "location_ids": [] } ] } ], "can_edit": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/access/users/{id}/account": { "patch": { "operationId": "accessUsersAccountUpdate", "summary": "Change administrator or web-cabinet access", "description": "`is_admin` — only an administrator can appoint or remove administrators (not themselves, not the company owner). `web_access: false` makes the employee \"app only\" (requires `users.access` for the employee). Logged.", "tags": [ "Roles & permissions" ], "x-mcp-tool": "access_users_account_update", "x-permissions": [ "access.manage", "access.roles", "access.log", "users.access" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_admin": { "type": "boolean" }, "web_access": { "type": "boolean" } } }, "example": { "is_admin": true, "web_access": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "account": { "type": "object", "properties": { "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "manages_locations": { "type": "array", "items": { "type": "string" } }, "manages_regions": { "type": "array" }, "can_change_admin": { "type": "boolean" }, "can_change_web_access": { "type": "boolean" } } }, "role_ids": { "type": "array", "items": { "type": "integer" } }, "system_role_ids": { "type": "array", "items": { "type": "integer" } }, "personal": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "effect": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array", "items": { "type": "integer" } } } } }, "effective": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "location_ids": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "role_id": { "type": "integer" }, "role": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array" } } } } } } }, "can_edit": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "account": { "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "manages_locations": [ "Abay Ave" ], "manages_regions": [], "can_change_admin": true, "can_change_web_access": true }, "role_ids": [ 41 ], "system_role_ids": [ 1, 2 ], "personal": [ { "key": "users.contacts", "effect": "grant", "scope": "list", "location_ids": [ 12 ] } ], "effective": [ { "key": "audits.view", "location_ids": null, "sources": [ { "source": "role", "role_id": 41, "role": "Auditor", "scope": "all", "location_ids": [] } ] } ], "can_edit": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/checklists": { "get": { "operationId": "analyticsChecklists", "summary": "Get checklist statistics", "description": "Checklists for a period: audits, average score and change, pass rate, violations. With `checklist_id` — also `selected`: compliance by section, questions sorted by violation rate (most problematic first), locations, and violations repeated at the same location. Useful to find weak spots of a checklist.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_checklists", "x-permissions": [ "analytics.view" ], "x-plan-feature": "analytics_pro", "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_id", "in": "query", "description": "Checklist id for a detailed breakdown", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "audits": { "type": "integer" }, "prev_audits": { "type": "integer" }, "avg": { "type": "number" }, "prev_avg": { "type": "number" }, "delta": { "type": "number" }, "pass_rate": { "type": "integer" }, "locations": { "type": "integer" }, "violations": { "type": "integer" }, "viol_rate": { "type": "number" }, "last": { "type": "string", "format": "date" } } } }, "selected": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "cur": { "type": "object", "properties": { "audits": { "type": "integer" }, "avg": { "type": "number" }, "pass_rate": { "type": "integer" }, "locations": { "type": "integer" }, "auditors": { "type": "integer" }, "violations": { "type": "integer" }, "viol_per_audit": { "type": "number" }, "viol_rate": { "type": "number" } } }, "prev": { "type": "object", "properties": { "audits": { "type": "integer" }, "avg": { "type": "number" }, "pass_rate": { "type": "number" }, "locations": { "type": "integer" }, "auditors": { "type": "integer" }, "violations": { "type": "integer" }, "viol_per_audit": { "type": "number" }, "viol_rate": { "type": "number" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "questions": { "type": "integer" }, "violations": { "type": "integer" }, "compliance": { "type": "number" } } } }, "questions_by_violations": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "question": { "type": "string" }, "section": { "type": "string" }, "yes": { "type": "integer" }, "no": { "type": "integer" }, "skip": { "type": "integer" }, "rate": { "type": "integer" }, "locations": { "type": "integer" }, "comments": { "type": "integer" } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "audits": { "type": "integer" }, "avg": { "type": "number" }, "min": { "type": "number" } } } }, "repeat_violations": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "string" }, "question": { "type": "string" }, "fails": { "type": "integer" }, "audits": { "type": "integer" }, "last": { "type": "string", "format": "date" } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "checklists": [ { "id": 5845, "name": "Daily dining room check", "type": "points", "audits": 10, "prev_audits": 16, "avg": 79.1, "prev_avg": 77.7, "delta": 1.4, "pass_rate": 90, "locations": 5, "violations": 17, "viol_rate": 19.5, "last": "2026-10-15" } ], "selected": { "id": 5845, "name": "Daily dining room check", "cur": { "audits": 10, "avg": 79.1, "pass_rate": 90, "locations": 5, "auditors": 2, "violations": 17, "viol_per_audit": 1.7, "viol_rate": 19.5 }, "prev": { "audits": 16, "avg": 77.7, "pass_rate": 62.5, "locations": 5, "auditors": 2, "violations": 29, "viol_per_audit": 1.8, "viol_rate": 20.9 }, "sections": [ { "id": 21626, "name": "Hall", "questions": 4, "violations": 6, "compliance": 83.8 } ], "questions_by_violations": [ { "n": 6, "question": "Cleaning log is filled in", "section": "Restroom", "yes": 5, "no": 5, "skip": 0, "rate": 50, "locations": 4, "comments": 5 } ], "locations": [ { "id": 4638, "name": "Park St", "audits": 1, "avg": 58.8, "min": 58.8 } ], "repeat_violations": [ { "location": "Embankment", "question": "Staff wear uniforms and badges", "fails": 3, "audits": 4, "last": "2026-10-14" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/control-brief": { "get": { "operationId": "analyticsControlBrief", "summary": "Get the AI control brief", "description": "The AI control brief from the home page: open problems found automatically (unstable and chronic violations, score drops, reused photos, soft auditors, missed plan, overdue tasks, HACCP, tests, instructions) with title, text, evidence facts, severity and status — most severe first, up to 15. With `signal` — one card by its UUID. Visibility follows `audits.view`; staff-related cards need `control.manage`.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_control_brief", "x-permissions": [ "audits.view" ], "x-scope": "read", "parameters": [ { "name": "signal", "in": "query", "description": "UUID of one brief card", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "detector": { "type": "string" }, "severity": { "type": "integer" }, "status": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "facts": { "type": "object", "properties": { "dept": { "type": "string" }, "deviations": { "type": "integer" }, "overdue_hours": { "type": "integer" } } }, "location_id": { "type": "integer" }, "checklist_id": { "type": [ "string", "null" ] }, "ai": { "type": "object", "properties": { "why": { "type": "string" }, "advice": { "type": "string" } } }, "since": { "type": "string", "format": "date" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "signals": [ { "uuid": "4a4007c6-b9a3-461b-8f1b-e584fbe7c45d", "detector": "haccp", "severity": 3, "status": "open", "title": "Central: HACCP risk", "text": "1 critical deviation not fixed on time (log \"Storage temperature\", 21 h overdue).", "facts": { "dept": "Central", "deviations": 1, "overdue_hours": 21 }, "location_id": 4637, "checklist_id": null, "ai": { "why": "The fridge alarm was ignored overnight.", "advice": "Check the fridge and log the corrective action." }, "since": "2026-10-17" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/locations": { "get": { "operationId": "analyticsLocations", "summary": "Rank locations", "description": "Location ranking for a period: audits, average score and change vs the previous period, pass rate, violations per audit, last audit and days since. For \"which locations are worst\", \"where have we not audited for a long time\".", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_locations", "x-permissions": [ "analytics.view" ], "x-plan-feature": "analytics_pro", "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "worst", "best", "most_audits", "longest_unaudited", "biggest_drop" ], "default": "worst" } }, { "name": "limit", "in": "query", "description": "How many locations to return", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "total_locations": { "type": "integer" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "audits": { "type": "integer" }, "prev_audits": { "type": "integer" }, "avg": { "type": "number" }, "prev_avg": { "type": "number" }, "delta": { "type": "number" }, "pass_rate": { "type": "integer" }, "violations": { "type": "integer" }, "viol_per_audit": { "type": "integer" }, "last_audit": { "type": "string", "format": "date" }, "days_since": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "total_locations": 5, "locations": [ { "id": 4638, "name": "Station Sq", "audits": 3, "prev_audits": 12, "avg": 72.2, "prev_avg": 68.8, "delta": 3.4, "pass_rate": 67, "violations": 6, "viol_per_audit": 2, "last_audit": "2026-10-15", "days_since": 19 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/locations/{location_id}": { "get": { "operationId": "analyticsLocation", "summary": "Get location analytics", "description": "One location in detail for a period: KPIs with the previous period, checklists, top violations of the location, the last 12 audits with report links, auditors.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_location", "x-permissions": [ "analytics.view" ], "x-plan-feature": "analytics_pro", "x-scope": "read", "parameters": [ { "name": "location_id", "in": "path", "required": true, "description": "Location id", "schema": { "type": "integer" } }, { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "cur": { "type": "object", "properties": { "audits": { "type": "integer" }, "avg": { "type": "number" }, "pass_rate": { "type": "integer" }, "locations": { "type": "integer" }, "auditors": { "type": "integer" }, "violations": { "type": "integer" }, "viol_per_audit": { "type": "number" }, "viol_rate": { "type": "number" } } }, "prev": { "type": "object", "properties": { "audits": { "type": "integer" }, "avg": { "type": "number" }, "pass_rate": { "type": "integer" }, "locations": { "type": "integer" }, "auditors": { "type": "integer" }, "violations": { "type": "integer" }, "viol_per_audit": { "type": "number" }, "viol_rate": { "type": "integer" } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "audits": { "type": "integer" }, "avg": { "type": "number" }, "min": { "type": "number" }, "last": { "type": "string", "format": "date" } } } }, "violations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question": { "type": "string" }, "checklist": { "type": "string" }, "section": { "type": "string" }, "fails": { "type": "integer" }, "answered": { "type": "integer" }, "rate": { "type": "integer" }, "locations": { "type": "integer" } } } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "result": { "type": "number" }, "date": { "type": "string" }, "checklist": { "type": "string" }, "auditor": { "type": "string" }, "report_url": { "type": "string", "format": "uri" } } } }, "auditors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "audits": { "type": "integer" }, "avg": { "type": "number" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "id": 4638, "name": "Embankment", "address": "Embankment, 3", "cur": { "audits": 7, "avg": 78.2, "pass_rate": 100, "locations": 1, "auditors": 3, "violations": 13, "viol_per_audit": 1.9, "viol_rate": 21.7 }, "prev": { "audits": 7, "avg": 90.4, "pass_rate": 100, "locations": 1, "auditors": 3, "violations": 5, "viol_per_audit": 0.7, "viol_rate": 10 }, "checklists": [ { "id": 5845, "name": "Daily dining room check", "audits": 4, "avg": 77.8, "min": 72.2, "last": "2026-10-14" } ], "violations": [ { "id": 197428, "question": "Staff wear uniforms and badges", "checklist": "Daily dining room check", "section": "Staff", "fails": 3, "answered": 4, "rate": 75, "locations": 1 } ], "recent": [ { "result": 77.8, "date": "2026-10-14 17:19", "checklist": "Daily dining room check", "auditor": "Marina Lebedeva", "report_url": "https://app.jecheck.io/api/reports/newVersionSavePdf/9a72f859-63a3-4046-9616-8aaf730073ff" } ], "auditors": [ { "id": 6321, "name": "Marina Lebedeva", "audits": 4, "avg": 80.4 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/overview": { "get": { "operationId": "analyticsOverview", "summary": "Get the audit overview", "description": "Company summary for a period with the previous period for comparison: number of audits, average score, pass rate (≥ 70%), violations, location coverage, plan fulfilment, open and overdue tasks; trend by day/week/month; score distribution; 5 best and 5 worst locations; top violations; locations without audits; ready-made insights. Start here for \"how are we doing\" questions.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_overview", "x-permissions": [ "analytics.view" ], "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "kpis": { "type": "object", "properties": { "audits": { "type": "object", "properties": { "value": { "type": "integer" }, "prev": { "type": "integer" } } }, "avg": { "type": "object", "properties": { "value": { "type": "integer" }, "prev": { "type": "number" } } }, "pass": { "type": "object", "properties": { "value": { "type": "number" }, "prev": { "type": "number" } } }, "violations": { "type": "object", "properties": { "value": { "type": "integer" }, "prev": { "type": "integer" }, "per_audit": { "type": "number" }, "prev_per_audit": { "type": "number" }, "rate": { "type": "number" } } }, "coverage": { "type": "object", "properties": { "value": { "type": "integer" }, "total": { "type": "integer" }, "prev": { "type": "integer" } } }, "auditors": { "type": "object", "properties": { "value": { "type": "integer" }, "prev": { "type": "integer" } } }, "plan": { "type": "object", "properties": { "value": { "type": "integer" }, "prev": { "type": "integer" }, "done": { "type": "integer" }, "planned": { "type": "integer" } } }, "tasks": { "type": "object", "properties": { "open": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string", "format": "date" }, "audits": { "type": "integer" }, "avg": { "type": "number" }, "pass": { "type": "integer" }, "violations": { "type": "integer" } } } }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "integer" }, "tone": { "type": "string" } } } }, "best_locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "audits": { "type": "integer" }, "avg": { "type": "number" }, "delta": { "type": "number" } } } }, "worst_locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "audits": { "type": "integer" }, "avg": { "type": "number" }, "delta": { "type": "number" } } } }, "top_violations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question": { "type": "string" }, "checklist": { "type": "string" }, "section": { "type": "string" }, "fails": { "type": "integer" }, "answered": { "type": "integer" }, "rate": { "type": "integer" }, "locations": { "type": "integer" } } } }, "locations_without_audits": { "type": "array" }, "insights": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "kpis": { "audits": { "value": 18, "prev": 48 }, "avg": { "value": 80, "prev": 75.9 }, "pass": { "value": 83.3, "prev": 64.6 }, "violations": { "value": 28, "prev": 90, "per_audit": 1.6, "prev_per_audit": 1.9, "rate": 19.4 }, "coverage": { "value": 5, "total": 5, "prev": 5 }, "auditors": { "value": 4, "prev": 6 }, "plan": { "value": 33, "prev": 75, "done": 8, "planned": 24 }, "tasks": { "open": 37, "overdue": 35 } }, "trend": [ { "bucket": "2026-10-05", "audits": 1, "avg": 82.4, "pass": 100, "violations": 1 } ], "distribution": [ { "label": "under 50%", "value": 0, "tone": "danger" } ], "best_locations": [ { "id": 4638, "name": "Park St", "audits": 3, "avg": 86.3, "delta": 30.9 } ], "worst_locations": [ { "id": 4638, "name": "Station Sq", "audits": 3, "avg": 72.2, "delta": 3.4 } ], "top_violations": [ { "id": 197426, "question": "Cleaning log is filled in", "checklist": "Daily dining room check", "section": "Restroom", "fails": 5, "answered": 10, "rate": 50, "locations": 4 } ], "locations_without_audits": [], "insights": [ "Average score rose by 4.1 pp: 80% vs 75.9% in the previous period." ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/plan": { "get": { "operationId": "analyticsPlan", "summary": "Get plan fulfilment", "description": "Audit plan fulfilment for a period by the planner rules (an audit counts within \"planned date ± tolerance\" for the same checklist and location): due / done / overdue (window still open) / missed and % with the previous period; breakdowns by location, auditor and checklist (worst first); missed audits; audits planned for the next 7 days; share of unplanned audits.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_plan", "x-permissions": [ "analytics.view" ], "x-plan-feature": "analytics_pro", "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "cur": { "type": "object", "properties": { "due": { "type": "integer" }, "done": { "type": "integer" }, "overdue": { "type": "integer" }, "missed": { "type": "integer" }, "rate": { "type": "integer" } } }, "prev": { "type": "object", "properties": { "due": { "type": "integer" }, "done": { "type": "integer" }, "overdue": { "type": "integer" }, "missed": { "type": "integer" }, "rate": { "type": "integer" } } }, "byLocation": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "due": { "type": "integer" }, "done": { "type": "integer" }, "overdue": { "type": "integer" }, "missed": { "type": "integer" }, "rate": { "type": "integer" } } } }, "byAuditor": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "due": { "type": "integer" }, "done": { "type": "integer" }, "overdue": { "type": "integer" }, "missed": { "type": "integer" }, "rate": { "type": "integer" } } } }, "byChecklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "due": { "type": "integer" }, "done": { "type": "integer" }, "overdue": { "type": "integer" }, "missed": { "type": "integer" }, "rate": { "type": "integer" } } } }, "missed": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "location": { "type": "string" }, "checklist": { "type": "string" }, "auditor": { "type": "string" } } } }, "upcoming": { "type": "integer" }, "unplanned": { "type": "object", "properties": { "total": { "type": "integer" }, "unplanned": { "type": "integer" } } }, "hasPlan": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "cur": { "due": 24, "done": 8, "overdue": 0, "missed": 16, "rate": 33 }, "prev": { "due": 24, "done": 18, "overdue": 0, "missed": 6, "rate": 75 }, "byLocation": [ { "id": 4638, "name": "Park St", "due": 8, "done": 1, "overdue": 0, "missed": 7, "rate": 13 } ], "byAuditor": [ { "id": 6324, "name": "Artem Volkov", "due": 4, "done": 0, "overdue": 0, "missed": 4, "rate": 0 } ], "byChecklist": [ { "id": 5848, "name": "Shift opening", "due": 4, "done": 0, "overdue": 0, "missed": 4, "rate": 0 } ], "missed": [ { "date": "2026-10-30", "location": "Park St", "checklist": "Shift opening", "auditor": "Artem Volkov" } ], "upcoming": 9, "unplanned": { "total": 18, "unplanned": 14 }, "hasPlan": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/tasks": { "get": { "operationId": "analyticsTasks", "summary": "Get task statistics", "description": "Tasks (including corrective actions from audits) for a period: created / closed / overdue, completion %, average closing time, on time; a snapshot of open tasks now (new, in progress, in review, overdue); breakdowns by priority, assignee and location; overdue tasks.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_tasks", "x-permissions": [ "analytics.view" ], "x-plan-feature": "analytics_pro", "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "cur": { "type": "object", "properties": { "created": { "type": "integer" }, "created_done": { "type": "integer" }, "created_rejected": { "type": "integer" }, "created_open": { "type": "integer" }, "created_overdue": { "type": "integer" }, "completion": { "type": "integer" }, "done": { "type": "integer" }, "close_days": { "type": "number" }, "on_time": { "type": "integer" } } }, "prev": { "type": "object", "properties": { "created": { "type": "integer" }, "created_done": { "type": "integer" }, "created_rejected": { "type": "integer" }, "created_open": { "type": "integer" }, "created_overdue": { "type": "integer" }, "completion": { "type": [ "string", "null" ] }, "done": { "type": "integer" }, "close_days": { "type": [ "string", "null" ] }, "on_time": { "type": [ "string", "null" ] } } }, "snapshot": { "type": "object", "properties": { "open": { "type": "integer" }, "new": { "type": "integer" }, "progress": { "type": "integer" }, "review": { "type": "integer" }, "overdue": { "type": "integer" }, "soon": { "type": "integer" }, "no_deadline": { "type": "integer" } } }, "trackedSince": { "type": "string" }, "byPriority": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "integer" }, "label": { "type": "string" }, "open": { "type": "integer" }, "overdue": { "type": "integer" } } } }, "byExecutor": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "done": { "type": "integer" }, "assigned": { "type": "integer" }, "completion": { "type": "integer" }, "close_days": { "type": "number" }, "on_time": { "type": "integer" } } } }, "byLocation": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "done": { "type": "integer" } } } }, "overdueList": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "deadline": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "priority": { "type": "integer" }, "location": { "type": "string" }, "executor": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "cur": { "created": 63, "created_done": 25, "created_rejected": 1, "created_open": 37, "created_overdue": 35, "completion": 40, "done": 25, "close_days": 0.4, "on_time": 56 }, "prev": { "created": 0, "created_done": 0, "created_rejected": 0, "created_open": 0, "created_overdue": 0, "completion": null, "done": 0, "close_days": null, "on_time": null }, "snapshot": { "open": 37, "new": 30, "progress": 4, "review": 3, "overdue": 35, "soon": 0, "no_deadline": 0 }, "trackedSince": "2026-10-08 17:07:00", "byPriority": [ { "key": 0, "label": "Urgent", "open": 1, "overdue": 1 } ], "byExecutor": [ { "id": 6323, "name": "Elena Morozova", "open": 14, "overdue": 12, "done": 5, "assigned": 19, "completion": 26, "close_days": 0.1, "on_time": 60 } ], "byLocation": [ { "id": 4637, "name": "Central", "open": 20, "overdue": 18, "done": 13 } ], "overdueList": [ { "uuid": "25180680-8ef5-a075-575b-cceed90f6bc0", "title": "Replace the broken fridge seal", "deadline": "2026-10-12", "days": 22, "priority": 1, "location": "Central", "executor": "Daria Kim" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/team": { "get": { "operationId": "analyticsTeam", "summary": "Get auditor statistics", "description": "Auditors for a period: number of audits, average score and deviation from the company average (strictness), locations, checklists, active days, photos / violations / comments per audit, last audit. Requires `analytics.team`; only audits of the token's locations are counted.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_team", "x-permissions": [ "analytics.team" ], "x-plan-feature": "analytics_pro", "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "company_avg": { "type": "integer" }, "auditors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "audits": { "type": "integer" }, "prev_audits": { "type": "integer" }, "avg": { "type": "number" }, "deviation": { "type": "number" }, "locations": { "type": "integer" }, "checklists": { "type": "integer" }, "active_days": { "type": "integer" }, "photos_per_audit": { "type": "number" }, "viol_per_audit": { "type": "number" }, "comments_per_audit": { "type": "number" }, "last": { "type": "string", "format": "date" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "company_avg": 80, "auditors": [ { "id": 6321, "name": "Marina Lebedeva", "audits": 10, "prev_audits": 19, "avg": 82.7, "deviation": 3.6, "locations": 5, "checklists": 3, "active_days": 7, "photos_per_audit": 0.6, "viol_per_audit": 1.4, "comments_per_audit": 1.4, "last": "2026-10-14" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/tests": { "get": { "operationId": "analyticsTests", "summary": "Get employee test statistics", "description": "Employee tests (Testing section): title, status, pass score, questions, attempts, average %, passed; assigned / passed / overdue assignments; answers waiting for manual review. Up to 40 tests, recently changed first.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_tests", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "query", "in": "query", "description": "Part of the test title", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "pass_score": { "type": "integer" }, "questions": { "type": "integer" }, "attempts": { "type": "integer" }, "avg_percent": { "type": "number" }, "passed_attempts": { "type": "integer" }, "assigned": { "type": "integer" }, "assigned_passed": { "type": "integer" }, "overdue": { "type": "integer" }, "pending_review": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "tests": [ { "id": 12, "title": "Barista standards", "status": "published", "category": "Barista", "pass_score": 80, "questions": 8, "attempts": 4, "avg_percent": 68.5, "passed_attempts": 2, "assigned": 7, "assigned_passed": 2, "overdue": 4, "pending_review": 1, "url": "https://app.jecheck.io/ui/testing/12/edit" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/analytics/violations": { "get": { "operationId": "analyticsViolations", "summary": "List top violations", "description": "The most frequent violations (checklist questions answered \"violation\") for a period: how many times, out of how many answers, rate %, on how many locations, checklist and section.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_violations", "x-permissions": [ "analytics.view" ], "x-plan-feature": "analytics_pro", "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "description": "Period; `custom` requires `from` and `to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "default": "30d" } }, { "name": "from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "description": "How many violations to return", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 30 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "bucket": { "type": "string" }, "restricted_to_user_locations": { "type": "boolean" } } }, "violations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question": { "type": "string" }, "checklist": { "type": "string" }, "section": { "type": "string" }, "fails": { "type": "integer" }, "answered": { "type": "integer" }, "rate": { "type": "integer" }, "locations": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03", "previous": { "from": "2026-09-04", "to": "2026-10-04" }, "bucket": "day", "restricted_to_user_locations": false }, "violations": [ { "id": 197426, "question": "Cleaning log is filled in", "checklist": "Daily dining room check", "section": "Restroom", "fails": 5, "answered": 10, "rate": 50, "locations": 4 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/audits": { "get": { "operationId": "auditsList", "summary": "List audits", "description": "The audit journal, newest first: checklist, location, auditor, result and status. `status`: `completed` — result 70% or higher, `failed` — below 70%, `in_progress` — not finished. Mystery-shopper audits have `mystery: true` and no auditor.", "tags": [ "Audits" ], "x-mcp-tool": "audits_list", "x-permissions": [ "audits.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "date_from", "in": "query", "description": "Conducted on or after this date", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Conducted on or before this date", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only audits by these users", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "status[]", "in": "query", "description": "Filter by status: completed, failed, in_progress", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "result_from", "in": "query", "description": "Result from, %", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "result_to", "in": "query", "description": "Result to, %", "schema": { "type": "number", "minimum": 0, "maximum": 100 } }, { "name": "search", "in": "query", "description": "Search by location, checklist or auditor name", "schema": { "type": "string", "maxLength": 200 } }, { "name": "created_since", "in": "query", "description": "Only audits received after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "date_desc", "date_asc", "result_asc", "result_desc" ], "default": "date_desc" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "mystery": { "type": "boolean" }, "status": { "type": "string" }, "result": { "type": "number" }, "report_status": { "type": "string" }, "conducted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "report_url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 99812, "uuid": "9a72f859-63a3-4046-9616-8aaf730073ff", "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "mystery": false, "status": "completed", "result": 82.4, "report_status": "ready", "conducted_at": "2026-11-03T09:40:00+05:00", "created_at": "2026-11-03T09:41:12+05:00", "report_url": "https://app.jecheck.io/api/reports/newVersionSavePdf/9a72f859-63a3-4046-9616-8aaf730073ff" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "auditsCreate", "summary": "Submit an audit", "description": "Submits a conducted audit for a checklist at a location — the same processing as the mobile app: the server scores every answer by the question type and settings, calculates the result, starts the PDF report and runs automation (corrective tasks for violations). The token user becomes the auditor; the checklist must be available to them and the location must be one where they work or may view audits. `yes_no` questions take `result` (`ok`, `violation`, `na`); `text` — `text`; other types — `value` (e.g. `{\"number\": 4.5}`, `{\"option\": \"a1\"}`, `{\"options\": [\"a1\",\"b2\"]}`, `{\"date\": \"2026-11-03\"}`, `{\"code\": \"4870001234567\"}`, `{\"user_id\": 311}`). Photos cannot be attached through the API yet.", "tags": [ "Audits" ], "x-mcp-tool": "audits_create", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checklist_id": { "type": "integer", "description": "Checklist id" }, "location_id": { "type": "integer", "description": "Location id" }, "conducted_at": { "type": "string", "format": "date-time", "description": "When the audit was conducted (ISO 8601); default — now" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer", "description": "Question id (from `checklists.get`)" }, "result": { "type": "string", "enum": [ "ok", "violation", "na" ], "description": "For `yes_no`: ok, violation or na; `na` also skips a question of another type" }, "text": { "type": "string", "description": "Text answer (`text` type)", "maxLength": 5000 }, "value": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Value for the other answer types" }, "comment": { "type": [ "string", "null" ], "description": "Auditor comment", "maxLength": 5000 } }, "required": [ "question_id" ] }, "description": "Answers; questions without an answer are not saved", "minItems": 1, "maxItems": 1000 }, "latitude": { "type": "number", "description": "Auditor geolocation" }, "longitude": { "type": "number", "description": "Auditor geolocation" } }, "required": [ "checklist_id", "location_id", "answers" ] }, "example": { "checklist_id": 42, "location_id": 12, "conducted_at": "2026-11-03T09:00:00+05:00", "answers": [ { "question_id": 42, "result": "ok", "text": "Seal on fridge #2 is torn, temperature rises to +9 °C." } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "mystery": { "type": "boolean" }, "status": { "type": "string" }, "result": { "type": "number" }, "report_status": { "type": "string" }, "conducted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "report_url": { "type": "string", "format": "uri" }, "scoring": { "type": "string" }, "target": { "type": "integer" }, "level": { "type": "string" }, "failed_by": { "type": "array" }, "counts": { "type": "object", "properties": { "checked": { "type": "integer" }, "ok": { "type": "integer" }, "violations": { "type": "integer" }, "na": { "type": "integer" }, "critical": { "type": "integer" }, "repeats": { "type": "integer" }, "photos": { "type": "integer" } } }, "previous": { "type": "object", "properties": { "result": { "type": "number" }, "date": { "type": "string", "format": "date" }, "delta": { "type": "number" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "result": { "type": "number" }, "checked": { "type": "integer" }, "ok": { "type": "integer" }, "violations": { "type": "integer" }, "na": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "number": { "type": "string" }, "text": { "type": "string" }, "result": { "type": "string" }, "answer": { "type": "string" }, "weight": { "type": "integer" }, "tier": { "type": "string" }, "repeat": { "type": "integer" }, "fail_all": { "type": "boolean" }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" } } } }, "files": { "type": "array" } } } } } } }, "violations": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "number": { "type": "string" }, "text": { "type": "string" }, "result": { "type": "string" }, "answer": { "type": "string" }, "weight": { "type": "integer" }, "tier": { "type": "string" }, "repeat": { "type": "integer" }, "fail_all": { "type": "boolean" }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" } } } }, "files": { "type": "array" }, "section": { "type": "string" } } } }, "ai": { "type": "object", "properties": { "summary": { "type": "string" }, "verdict": { "type": "string" }, "recommendations": { "type": "array", "items": { "type": "string" } }, "plan": { "type": "array", "items": { "type": "object", "properties": { "priority": { "type": "string" }, "action": { "type": "string" }, "owner": { "type": "string" }, "section": { "type": "string" } } } } } }, "signature_url": { "type": [ "string", "null" ] }, "geo": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "question_id": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 99812, "uuid": "9a72f859-63a3-4046-9616-8aaf730073ff", "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "mystery": false, "status": "completed", "result": 82.4, "report_status": "ready", "conducted_at": "2026-11-03T09:40:00+05:00", "created_at": "2026-11-03T09:41:12+05:00", "report_url": "https://app.jecheck.io/api/reports/newVersionSavePdf/9a72f859-63a3-4046-9616-8aaf730073ff", "scoring": "points", "target": 85, "level": "warn", "failed_by": [], "counts": { "checked": 18, "ok": 15, "violations": 3, "na": 1, "critical": 1, "repeats": 1, "photos": 6 }, "previous": { "result": 76.5, "date": "2026-10-27", "delta": 5.9 }, "sections": [ { "id": 21626, "name": "Kitchen", "result": 71.4, "checked": 7, "ok": 5, "violations": 2, "na": 0, "questions": [ { "question_id": 197426, "number": "1.2", "text": "Fridge temperature is within the norm", "result": "violation", "answer": "9.1 °C", "weight": 5, "tier": "critical", "repeat": 2, "fail_all": false, "comment": "Door seal is torn", "photos": [ { "url": "https://jecheck.s3.eu-west-1.amazonaws.com/audits/761/fridge.jpg", "name": "fridge.jpg" } ], "files": [] } ] } ], "violations": [ { "question_id": 197426, "number": "1.2", "text": "Fridge temperature is within the norm", "result": "violation", "answer": "9.1 °C", "weight": 5, "tier": "critical", "repeat": 2, "fail_all": false, "comment": "Door seal is torn", "photos": [ { "url": "https://jecheck.s3.eu-west-1.amazonaws.com/audits/761/fridge.jpg", "name": "fridge.jpg" } ], "files": [], "section": "Kitchen" } ], "ai": { "summary": "Cold chain is the main risk: two fridges out of range.", "verdict": "Needs attention", "recommendations": [ "Replace the door seal of fridge #2" ], "plan": [ { "priority": "high", "action": "Replace the seal", "owner": "Chef", "section": "Kitchen" } ] }, "signature_url": null, "geo": { "lat": 43.23811, "lon": 76.94572 }, "tasks": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Replace the broken fridge seal", "status": "in_progress", "due_date": "2026-11-04", "question_id": 197426 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/audits/{id}": { "get": { "operationId": "auditsGet", "summary": "Retrieve an audit result", "description": "The result card, calculated exactly like the PDF report: score, target and `level` (`bad` — not passed, `warn` — passed below target, `ok` — target reached / excellent), sections with their results, every answered question (`result`: `ok`, `violation`, `na`, `info` for unscored answers) with comments and photos, violations sorted by weight and repetition, previous audit of the same checklist at the location, the AI report if enabled, and corrective tasks created from this audit. Own audits are always visible; others need `audits.view` on the location.", "tags": [ "Audits" ], "x-mcp-tool": "audits_get", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Audit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "mystery": { "type": "boolean" }, "status": { "type": "string" }, "result": { "type": "number" }, "report_status": { "type": "string" }, "conducted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "report_url": { "type": "string", "format": "uri" }, "scoring": { "type": "string" }, "target": { "type": "integer" }, "level": { "type": "string" }, "failed_by": { "type": "array" }, "counts": { "type": "object", "properties": { "checked": { "type": "integer" }, "ok": { "type": "integer" }, "violations": { "type": "integer" }, "na": { "type": "integer" }, "critical": { "type": "integer" }, "repeats": { "type": "integer" }, "photos": { "type": "integer" } } }, "previous": { "type": "object", "properties": { "result": { "type": "number" }, "date": { "type": "string", "format": "date" }, "delta": { "type": "number" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "result": { "type": "number" }, "checked": { "type": "integer" }, "ok": { "type": "integer" }, "violations": { "type": "integer" }, "na": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "number": { "type": "string" }, "text": { "type": "string" }, "result": { "type": "string" }, "answer": { "type": "string" }, "weight": { "type": "integer" }, "tier": { "type": "string" }, "repeat": { "type": "integer" }, "fail_all": { "type": "boolean" }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" } } } }, "files": { "type": "array" } } } } } } }, "violations": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "number": { "type": "string" }, "text": { "type": "string" }, "result": { "type": "string" }, "answer": { "type": "string" }, "weight": { "type": "integer" }, "tier": { "type": "string" }, "repeat": { "type": "integer" }, "fail_all": { "type": "boolean" }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" } } } }, "files": { "type": "array" }, "section": { "type": "string" } } } }, "ai": { "type": "object", "properties": { "summary": { "type": "string" }, "verdict": { "type": "string" }, "recommendations": { "type": "array", "items": { "type": "string" } }, "plan": { "type": "array", "items": { "type": "object", "properties": { "priority": { "type": "string" }, "action": { "type": "string" }, "owner": { "type": "string" }, "section": { "type": "string" } } } } } }, "signature_url": { "type": [ "string", "null" ] }, "geo": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "question_id": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 99812, "uuid": "9a72f859-63a3-4046-9616-8aaf730073ff", "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "mystery": false, "status": "completed", "result": 82.4, "report_status": "ready", "conducted_at": "2026-11-03T09:40:00+05:00", "created_at": "2026-11-03T09:41:12+05:00", "report_url": "https://app.jecheck.io/api/reports/newVersionSavePdf/9a72f859-63a3-4046-9616-8aaf730073ff", "scoring": "points", "target": 85, "level": "warn", "failed_by": [], "counts": { "checked": 18, "ok": 15, "violations": 3, "na": 1, "critical": 1, "repeats": 1, "photos": 6 }, "previous": { "result": 76.5, "date": "2026-10-27", "delta": 5.9 }, "sections": [ { "id": 21626, "name": "Kitchen", "result": 71.4, "checked": 7, "ok": 5, "violations": 2, "na": 0, "questions": [ { "question_id": 197426, "number": "1.2", "text": "Fridge temperature is within the norm", "result": "violation", "answer": "9.1 °C", "weight": 5, "tier": "critical", "repeat": 2, "fail_all": false, "comment": "Door seal is torn", "photos": [ { "url": "https://jecheck.s3.eu-west-1.amazonaws.com/audits/761/fridge.jpg", "name": "fridge.jpg" } ], "files": [] } ] } ], "violations": [ { "question_id": 197426, "number": "1.2", "text": "Fridge temperature is within the norm", "result": "violation", "answer": "9.1 °C", "weight": 5, "tier": "critical", "repeat": 2, "fail_all": false, "comment": "Door seal is torn", "photos": [ { "url": "https://jecheck.s3.eu-west-1.amazonaws.com/audits/761/fridge.jpg", "name": "fridge.jpg" } ], "files": [], "section": "Kitchen" } ], "ai": { "summary": "Cold chain is the main risk: two fridges out of range.", "verdict": "Needs attention", "recommendations": [ "Replace the door seal of fridge #2" ], "plan": [ { "priority": "high", "action": "Replace the seal", "owner": "Chef", "section": "Kitchen" } ] }, "signature_url": null, "geo": { "lat": 43.23811, "lon": 76.94572 }, "tasks": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Replace the broken fridge seal", "status": "in_progress", "due_date": "2026-11-04", "question_id": 197426 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "auditsDelete", "summary": "Delete an audit", "description": "Permanently deletes the audit with its answers and attachments: it disappears from the journal, analytics and reports and cannot be restored. Corrective tasks created from it stay. Requires `audits.delete` on the audit location.", "tags": [ "Audits" ], "x-mcp-tool": "audits_delete", "x-permissions": [ "audits.delete" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Audit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/audits/{id}/pdf": { "get": { "operationId": "auditsPdf", "summary": "Get the PDF report link", "description": "Returns a public link to the PDF report (no login needed — share it carefully) and the online report link. `ready: false` — the PDF is still being generated, try again in a minute. Requires `audits.export` on the audit location; each call is recorded in the access log.", "tags": [ "Audits" ], "x-mcp-tool": "audits_pdf", "x-permissions": [ "audits.export" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Audit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ready": { "type": "boolean" }, "pdf_url": { "type": "string", "format": "uri" }, "online_url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "ready": true, "pdf_url": "https://app.jecheck.io/api/reports/pdf/9a72f859-63a3-4046-9616-8aaf730073ff", "online_url": "https://app.jecheck.io/api/reports/newVersionSavePdf/9a72f859-63a3-4046-9616-8aaf730073ff" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/loop/{uuid}": { "get": { "operationId": "automationLoopGet", "summary": "Get the corrective-action loop of a task", "description": "For a task created from an audit violation: the audit, deadline, whether a photo \"after\" and confirmation are required, photos before/after, whether the acting user may accept it, AI verdict and the loop history.", "tags": [ "Automation" ], "x-mcp-tool": "automation_loop_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "source": { "type": "string" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "confirmed_at": { "type": "string", "format": "date-time" } } }, "deadline_at": { "type": "string", "format": "date-time" }, "requires_photo": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "has_after_photo": { "type": "boolean" }, "can_confirm": { "type": "boolean" }, "is_repeat": { "type": "boolean" }, "reopen_count": { "type": "integer" }, "unassigned_role": { "type": "boolean" }, "seen_again": { "type": "integer" }, "before_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "after_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "ai_verdict": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "actor": { "type": "string" }, "user": { "type": "string" }, "payload": { "type": "object", "properties": { "comment": { "type": "string" } } }, "at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "status": "review", "source": "auto", "audit": { "id": 99812, "uuid": "0a9b8c7d-6e5f-4a3b-8c1d-2e3f4a5b6c7d", "checklist": "Kitchen daily check", "score": 82, "confirmed_at": "2026-11-03T09:40:00+05:00" }, "deadline_at": "2026-11-03T13:40:00+05:00", "requires_photo": true, "requires_confirmation": true, "has_after_photo": true, "can_confirm": true, "is_repeat": false, "reopen_count": 0, "unassigned_role": false, "seen_again": 0, "before_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/audits/before.jpg" ], "after_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/tasks/images/0001/after.jpg" ], "ai_verdict": null, "events": [ { "type": "submitted", "label": "Submitted for review", "actor": "user", "user": "Aigerim", "payload": { "comment": "Seal replaced" }, "at": "2026-11-03T12:30:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/loop/{uuid}/confirm": { "post": { "operationId": "automationLoopConfirm", "summary": "Accept the fix", "description": "A confirmer (location manager, auditor or the one set by the scenario — see `can_confirm`) accepts the fix; the task is completed.", "tags": [ "Automation" ], "x-mcp-tool": "automation_loop_confirm", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "source": { "type": "string" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "confirmed_at": { "type": "string", "format": "date-time" } } }, "deadline_at": { "type": "string", "format": "date-time" }, "requires_photo": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "has_after_photo": { "type": "boolean" }, "can_confirm": { "type": "boolean" }, "is_repeat": { "type": "boolean" }, "reopen_count": { "type": "integer" }, "unassigned_role": { "type": "boolean" }, "seen_again": { "type": "integer" }, "before_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "after_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "ai_verdict": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "actor": { "type": "string" }, "user": { "type": "string" }, "payload": { "type": "object", "properties": { "comment": { "type": "string" } } }, "at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "status": "review", "source": "auto", "audit": { "id": 99812, "uuid": "0a9b8c7d-6e5f-4a3b-8c1d-2e3f4a5b6c7d", "checklist": "Kitchen daily check", "score": 82, "confirmed_at": "2026-11-03T09:40:00+05:00" }, "deadline_at": "2026-11-03T13:40:00+05:00", "requires_photo": true, "requires_confirmation": true, "has_after_photo": true, "can_confirm": true, "is_repeat": false, "reopen_count": 0, "unassigned_role": false, "seen_again": 0, "before_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/audits/before.jpg" ], "after_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/tasks/images/0001/after.jpg" ], "ai_verdict": null, "events": [ { "type": "submitted", "label": "Submitted for review", "actor": "user", "user": "Aigerim", "payload": { "comment": "Seal replaced" }, "at": "2026-11-03T12:30:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/loop/{uuid}/photo": { "post": { "operationId": "automationLoopPhoto", "summary": "Upload a photo \"after\"", "description": "Attaches a photo of the fixed violation (JPEG/PNG/HEIC…, up to 15 MB; resized to 1920 px). Required before `submit` when `requires_photo` is true.", "tags": [ "Automation" ], "x-mcp-tool": "automation_loop_photo", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "photo": { "type": "string", "format": "binary", "description": "Image file (multipart; in MCP — object with `name` and `content_base64`)" } }, "required": [ "photo" ] } }, "application/json": { "schema": { "type": "object", "properties": { "photo": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "Image file (multipart; in MCP — object with `name` and `content_base64`)" } }, "required": [ "photo" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "source": { "type": "string" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "confirmed_at": { "type": "string", "format": "date-time" } } }, "deadline_at": { "type": "string", "format": "date-time" }, "requires_photo": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "has_after_photo": { "type": "boolean" }, "can_confirm": { "type": "boolean" }, "is_repeat": { "type": "boolean" }, "reopen_count": { "type": "integer" }, "unassigned_role": { "type": "boolean" }, "seen_again": { "type": "integer" }, "before_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "after_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "ai_verdict": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "actor": { "type": "string" }, "user": { "type": "string" }, "payload": { "type": "object", "properties": { "comment": { "type": "string" } } }, "at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "status": "review", "source": "auto", "audit": { "id": 99812, "uuid": "0a9b8c7d-6e5f-4a3b-8c1d-2e3f4a5b6c7d", "checklist": "Kitchen daily check", "score": 82, "confirmed_at": "2026-11-03T09:40:00+05:00" }, "deadline_at": "2026-11-03T13:40:00+05:00", "requires_photo": true, "requires_confirmation": true, "has_after_photo": true, "can_confirm": true, "is_repeat": false, "reopen_count": 0, "unassigned_role": false, "seen_again": 0, "before_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/audits/before.jpg" ], "after_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/tasks/images/0001/after.jpg" ], "ai_verdict": null, "events": [ { "type": "submitted", "label": "Submitted for review", "actor": "user", "user": "Aigerim", "payload": { "comment": "Seal replaced" }, "at": "2026-11-03T12:30:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/loop/{uuid}/reject": { "post": { "operationId": "automationLoopReject", "summary": "Return the fix for rework", "description": "A confirmer returns the task to the executor with a reason; reminders restart.", "tags": [ "Automation" ], "x-mcp-tool": "automation_loop_reject", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } }, "required": [ "reason" ] }, "example": { "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "source": { "type": "string" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "confirmed_at": { "type": "string", "format": "date-time" } } }, "deadline_at": { "type": "string", "format": "date-time" }, "requires_photo": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "has_after_photo": { "type": "boolean" }, "can_confirm": { "type": "boolean" }, "is_repeat": { "type": "boolean" }, "reopen_count": { "type": "integer" }, "unassigned_role": { "type": "boolean" }, "seen_again": { "type": "integer" }, "before_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "after_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "ai_verdict": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "actor": { "type": "string" }, "user": { "type": "string" }, "payload": { "type": "object", "properties": { "comment": { "type": "string" } } }, "at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "status": "review", "source": "auto", "audit": { "id": 99812, "uuid": "0a9b8c7d-6e5f-4a3b-8c1d-2e3f4a5b6c7d", "checklist": "Kitchen daily check", "score": 82, "confirmed_at": "2026-11-03T09:40:00+05:00" }, "deadline_at": "2026-11-03T13:40:00+05:00", "requires_photo": true, "requires_confirmation": true, "has_after_photo": true, "can_confirm": true, "is_repeat": false, "reopen_count": 0, "unassigned_role": false, "seen_again": 0, "before_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/audits/before.jpg" ], "after_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/tasks/images/0001/after.jpg" ], "ai_verdict": null, "events": [ { "type": "submitted", "label": "Submitted for review", "actor": "user", "user": "Aigerim", "payload": { "comment": "Seal replaced" }, "at": "2026-11-03T12:30:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/loop/{uuid}/submit": { "post": { "operationId": "automationLoopSubmit", "summary": "Mark the violation as fixed", "description": "The executor reports the fix: the task goes to review (if confirmation is required) or is completed. A queued team task becomes the acting user's.", "tags": [ "Automation" ], "x-mcp-tool": "automation_loop_submit", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 500 } } }, "example": { "comment": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "source": { "type": "string" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "confirmed_at": { "type": "string", "format": "date-time" } } }, "deadline_at": { "type": "string", "format": "date-time" }, "requires_photo": { "type": "boolean" }, "requires_confirmation": { "type": "boolean" }, "has_after_photo": { "type": "boolean" }, "can_confirm": { "type": "boolean" }, "is_repeat": { "type": "boolean" }, "reopen_count": { "type": "integer" }, "unassigned_role": { "type": "boolean" }, "seen_again": { "type": "integer" }, "before_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "after_photos": { "type": "array", "items": { "type": "string", "format": "uri" } }, "ai_verdict": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "actor": { "type": "string" }, "user": { "type": "string" }, "payload": { "type": "object", "properties": { "comment": { "type": "string" } } }, "at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "status": "review", "source": "auto", "audit": { "id": 99812, "uuid": "0a9b8c7d-6e5f-4a3b-8c1d-2e3f4a5b6c7d", "checklist": "Kitchen daily check", "score": 82, "confirmed_at": "2026-11-03T09:40:00+05:00" }, "deadline_at": "2026-11-03T13:40:00+05:00", "requires_photo": true, "requires_confirmation": true, "has_after_photo": true, "can_confirm": true, "is_repeat": false, "reopen_count": 0, "unassigned_role": false, "seen_again": 0, "before_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/audits/before.jpg" ], "after_photos": [ "https://bucket.s3.eu-central-1.amazonaws.com/tasks/images/0001/after.jpg" ], "ai_verdict": null, "events": [ { "type": "submitted", "label": "Submitted for review", "actor": "user", "user": "Aigerim", "payload": { "comment": "Seal replaced" }, "at": "2026-11-03T12:30:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/presets": { "get": { "operationId": "automationPresets", "summary": "List scenario templates", "description": "Ready-made scenarios with complete definitions, plus the catalog of block types the editor supports.", "tags": [ "Automation" ], "x-mcp-tool": "automation_presets", "x-permissions": [ "automation.manage" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "presets": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "definition": { "type": "object", "properties": { "v": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "string" }, "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "integer" }, "then": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" }, "by": { "type": "string" } } } }, "else": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" } } } } } } } } } } } }, "actions": { "type": "array", "items": { "type": "string" } }, "condition_fields": { "type": "array", "items": { "type": "string" } }, "assign_to": { "type": "array", "items": { "type": "string" } }, "escalate_to": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": { "presets": [ { "key": "standard", "name": "Standard", "description": "Critical — 4 hours, photo and confirmation; others — 24 hours and photo.", "definition": { "v": 1, "steps": [ { "type": "assign", "to": "responsible_role" }, { "type": "condition", "field": "weight", "op": "gte", "value": 3, "then": [ { "type": "deadline", "hours": 4 }, { "type": "require_photo" }, { "type": "require_confirmation", "by": "managers" } ], "else": [ { "type": "deadline", "hours": 24 }, { "type": "require_photo" } ] } ] } } ], "actions": [ "assign", "deadline", "require_photo", "require_confirmation", "remind", "escalate", "group", "ai_text", "ai_verify", "digest", "skip" ], "condition_fields": [ "weight", "section", "checklist_question", "department", "is_repeat", "audit_score" ], "assign_to": [ "responsible_role", "role", "managers", "auditor", "user", "team" ], "escalate_to": [ "managers", "role", "user", "admins" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/preview": { "post": { "operationId": "automationPreview", "summary": "Preview a scenario on an audit", "description": "Dry run: what the (possibly unsaved) definition would do with each violation of a completed audit — no tasks are created.", "tags": [ "Automation" ], "x-mcp-tool": "automation_preview", "x-permissions": [ "automation.manage" ], "x-plan-feature": "automation", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_id": { "type": "integer", "description": "Completed audit id" }, "definition": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "audit_id", "definition" ] }, "example": { "audit_id": 42, "definition": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "errors": { "type": "array" }, "items": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "assign": { "type": "object", "properties": { "to": { "type": "string" } } }, "deadline_hours": { "type": "integer" }, "require_photo": { "type": "boolean" }, "require_confirmation": { "type": "string" }, "question": { "type": "string" }, "section": { "type": "string" }, "weight": { "type": "integer" }, "assignees": { "type": "array", "items": { "type": "string" } }, "fallback": { "type": "boolean" }, "is_repeat": { "type": "boolean" }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "errors": [], "items": [ { "action": "task", "assign": { "to": "responsible_role" }, "deadline_hours": 4, "require_photo": true, "require_confirmation": "managers", "question": "Fridge temperature is within norm", "section": "Kitchen", "weight": 3, "assignees": [ "Aigerim" ], "fallback": false, "is_repeat": false, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/scenarios": { "get": { "operationId": "automationScenariosList", "summary": "List automation scenarios", "tags": [ "Automation" ], "x-mcp-tool": "automation_scenarios_list", "x-permissions": [ "automation.manage" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "definition": { "type": "object", "properties": { "v": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "string" }, "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "integer" }, "then": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" }, "by": { "type": "string" } } } }, "else": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" } } } } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 5, "name": "Standard", "is_default": true, "definition": { "v": 1, "steps": [ { "type": "assign", "to": "responsible_role" }, { "type": "condition", "field": "weight", "op": "gte", "value": 3, "then": [ { "type": "deadline", "hours": 4 }, { "type": "require_photo" }, { "type": "require_confirmation", "by": "managers" } ], "else": [ { "type": "deadline", "hours": 24 }, { "type": "require_photo" } ] } ] }, "checklists": [ { "id": 101, "name": "Kitchen daily check" } ], "created_at": "2026-09-01T10:00:00+05:00", "updated_at": "2026-10-20T09:00:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "automationScenariosCreate", "summary": "Create a scenario", "description": "The definition is validated by the same engine as in the web editor; errors come back as `validation_failed` on `definition`.", "tags": [ "Automation" ], "x-mcp-tool": "automation_scenarios_create", "x-permissions": [ "automation.manage" ], "x-plan-feature": "automation", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Scenario name", "maxLength": 255 }, "definition": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Block tree {\"steps\": [...]}. Action blocks: assign, deadline, require_photo, require_confirmation, remind, escalate, group, ai_text, ai_verify, digest, skip; `condition` blocks on weight, section, checklist_question, department, is_repeat, audit_score with `then` / `else` branches; assign targets: responsible_role, role, managers, auditor, user, team. See `automation.presets` for complete examples" }, "is_default": { "type": "boolean", "description": "Use for checklists without their own scenario" }, "checklist_ids": { "type": "array", "items": { "type": "integer" }, "description": "Checklists that use this scenario (replaces the list)" } }, "required": [ "name", "definition" ] }, "example": { "name": "Replace the broken fridge seal", "definition": [], "is_default": true, "checklist_ids": [ 12, 14 ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "definition": { "type": "object", "properties": { "v": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "string" }, "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "integer" }, "then": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" }, "by": { "type": "string" } } } }, "else": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" } } } } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5, "name": "Standard", "is_default": true, "definition": { "v": 1, "steps": [ { "type": "assign", "to": "responsible_role" }, { "type": "condition", "field": "weight", "op": "gte", "value": 3, "then": [ { "type": "deadline", "hours": 4 }, { "type": "require_photo" }, { "type": "require_confirmation", "by": "managers" } ], "else": [ { "type": "deadline", "hours": 24 }, { "type": "require_photo" } ] } ] }, "checklists": [ { "id": 101, "name": "Kitchen daily check" } ], "created_at": "2026-09-01T10:00:00+05:00", "updated_at": "2026-10-20T09:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation/scenarios/{id}": { "get": { "operationId": "automationScenariosGet", "summary": "Retrieve a scenario", "tags": [ "Automation" ], "x-mcp-tool": "automation_scenarios_get", "x-permissions": [ "automation.manage" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Scenario id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "definition": { "type": "object", "properties": { "v": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "string" }, "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "integer" }, "then": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" }, "by": { "type": "string" } } } }, "else": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" } } } } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5, "name": "Standard", "is_default": true, "definition": { "v": 1, "steps": [ { "type": "assign", "to": "responsible_role" }, { "type": "condition", "field": "weight", "op": "gte", "value": 3, "then": [ { "type": "deadline", "hours": 4 }, { "type": "require_photo" }, { "type": "require_confirmation", "by": "managers" } ], "else": [ { "type": "deadline", "hours": 24 }, { "type": "require_photo" } ] } ] }, "checklists": [ { "id": 101, "name": "Kitchen daily check" } ], "created_at": "2026-09-01T10:00:00+05:00", "updated_at": "2026-10-20T09:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "automationScenariosUpdate", "summary": "Update a scenario", "description": "Partial update; `definition` replaces the whole block tree.", "tags": [ "Automation" ], "x-mcp-tool": "automation_scenarios_update", "x-permissions": [ "automation.manage" ], "x-plan-feature": "automation", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Scenario id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Scenario name", "maxLength": 255 }, "definition": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Block tree {\"steps\": [...]}. Action blocks: assign, deadline, require_photo, require_confirmation, remind, escalate, group, ai_text, ai_verify, digest, skip; `condition` blocks on weight, section, checklist_question, department, is_repeat, audit_score with `then` / `else` branches; assign targets: responsible_role, role, managers, auditor, user, team. See `automation.presets` for complete examples" }, "is_default": { "type": "boolean", "description": "Use for checklists without their own scenario" }, "checklist_ids": { "type": "array", "items": { "type": "integer" }, "description": "Checklists that use this scenario (replaces the list)" } } }, "example": { "name": "Replace the broken fridge seal", "definition": [], "is_default": true, "checklist_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_default": { "type": "boolean" }, "definition": { "type": "object", "properties": { "v": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "string" }, "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "integer" }, "then": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" }, "by": { "type": "string" } } } }, "else": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "hours": { "type": "integer" } } } } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5, "name": "Standard", "is_default": true, "definition": { "v": 1, "steps": [ { "type": "assign", "to": "responsible_role" }, { "type": "condition", "field": "weight", "op": "gte", "value": 3, "then": [ { "type": "deadline", "hours": 4 }, { "type": "require_photo" }, { "type": "require_confirmation", "by": "managers" } ], "else": [ { "type": "deadline", "hours": 24 }, { "type": "require_photo" } ] } ] }, "checklists": [ { "id": 101, "name": "Kitchen daily check" } ], "created_at": "2026-09-01T10:00:00+05:00", "updated_at": "2026-10-20T09:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "automationScenariosDelete", "summary": "Delete a scenario", "description": "Checklists that used it fall back to the default scenario.", "tags": [ "Automation" ], "x-mcp-tool": "automation_scenarios_delete", "x-permissions": [ "automation.manage" ], "x-plan-feature": "automation", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Scenario id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists": { "get": { "operationId": "checklistsList", "summary": "List checklists", "description": "Checklists of the company, recently changed first, with structure size and usage over the last 30 days. Without `checklists.edit` only checklists available to the token user are returned (see \"who can run\" in the checklist). Deleted checklists (trash, last 30 days) — with `deleted=true` and the `checklists.delete` permission.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_list", "x-permissions": [ "checklists.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "folder_id", "in": "query", "description": "Only checklists of this folder; `0` — checklists without a folder", "schema": { "type": "integer", "minimum": 0 } }, { "name": "search", "in": "query", "description": "Search in name and description", "schema": { "type": "string", "maxLength": 200 } }, { "name": "updated_since", "in": "query", "description": "Only checklists changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } }, { "name": "deleted", "in": "query", "description": "Return deleted checklists (trash) instead of active ones; requires `checklists.delete`", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "scoring": { "type": "string" }, "sections_count": { "type": "integer" }, "questions_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "audits_30d": { "type": "integer" }, "avg_result_30d": { "type": "number" }, "last_audit_at": { "type": "string", "format": "date-time" }, "restricted": { "type": "boolean" }, "ai_summary": { "type": "boolean" }, "require_location": { "type": "boolean" }, "require_signature": { "type": "boolean" }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 5845, "name": "Daily dining room check", "description": "Opening check of the hall, restrooms and staff", "folder": { "id": 31, "name": "Front of house" }, "scoring": "points", "sections_count": 4, "questions_count": 18, "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "audits_30d": 12, "avg_result_30d": 81.4, "last_audit_at": "2026-11-02T18:40:00+05:00", "restricted": true, "ai_summary": false, "require_location": true, "require_signature": false, "deleted": false, "created_at": "2026-03-14T09:10:00+05:00", "updated_at": "2026-10-28T16:22:00+05:00", "url": "https://app.jecheck.io/ui/checklists/5845/edit" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "checklistsCreate", "summary": "Create a checklist", "description": "Creates a checklist with sections and questions in one call. Minimal question: `{\"text\": \"Floors are clean\"}` — a yes/no question with weight 1. Display conditions (`settings.show_if`) reference question ids, so add them later with `checklists.structure.update`.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_create", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Checklist name (at least 5 characters)", "minLength": 5, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Description", "maxLength": 5000 }, "folder_id": { "type": [ "integer", "null" ], "description": "Folder id (see `checklists.folders.list`)" }, "scoring": { "type": "string", "enum": [ "points", "percent" ], "default": "points", "description": "`points` — weighted score (default), `percent` — share of compliant answers" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Section name", "minLength": 2, "maxLength": 512 }, "questions": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Question wording (at least 5 characters)", "minLength": 5, "maxLength": 2000 }, "description": { "type": [ "string", "null" ], "description": "Hint for the auditor", "maxLength": 5000 }, "type": { "type": "string", "enum": [ "yes_no", "text", "choice", "multi", "number", "scale", "date", "signature", "photo", "instruction", "barcode", "employee" ], "default": "yes_no", "description": "Answer type. `yes_no` (default) — complies / violation / not applicable; `choice`/`multi` need `settings.options`; `number` may have a norm `settings.min`/`max`; see the Checklists guide" }, "weight": { "type": "integer", "default": 1, "description": "Weight (points) of the question, 1–100", "minimum": 1, "maximum": 100 }, "photo_required": { "type": "boolean", "default": false, "description": "The auditor must attach a photo" }, "can_skip": { "type": "boolean", "default": false, "description": "The question may be skipped" }, "fail_all": { "type": "boolean", "description": "A violation on this question sets the whole audit result to 0 (scored types only)" }, "settings": { "type": [ "object", "null" ], "properties": {}, "additionalProperties": true, "description": "Type settings, e.g. `{\"options\":[{\"id\":\"a1\",\"label\":\"Clean\",\"result\":1,\"score\":1},{\"id\":\"a2\",\"label\":\"Dirty\",\"result\":2,\"score\":0}]}` for `choice`, `{\"unit\":\"°C\",\"min\":2,\"max\":6}` for `number`, `{\"min\":1,\"max\":5,\"pass\":4}` for `scale`; common keys `fail_all`, `show_if`, `media`" } }, "required": [ "text" ] }, "description": "Questions of the section, in order" } }, "required": [ "name", "questions" ] }, "description": "Sections with questions, in order", "maxItems": 60 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "folder_id": 42, "scoring": "points" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "scoring": { "type": "string" }, "sections_count": { "type": "integer" }, "questions_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "audits_30d": { "type": "integer" }, "avg_result_30d": { "type": "number" }, "last_audit_at": { "type": "string", "format": "date-time" }, "restricted": { "type": "boolean" }, "ai_summary": { "type": "boolean" }, "require_location": { "type": "boolean" }, "require_signature": { "type": "boolean" }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "available_from": { "type": "string" }, "available_to": { "type": "string" }, "select_manager": { "type": "boolean" }, "send_to_location": { "type": "boolean" }, "scenario_id": { "type": [ "string", "null" ] }, "access": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "responsible": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "text": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo_required": { "type": "boolean" }, "settings": { "type": "object", "properties": { "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "decimals": { "type": "integer" }, "fail_all": { "type": "boolean" } } }, "responsible": { "type": "object", "properties": { "to": { "type": "string" }, "position_id": { "type": "integer" } } }, "auto_task": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "deadline_hours": { "type": "integer" } } } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5845, "name": "Daily dining room check", "description": "Opening check of the hall, restrooms and staff", "folder": { "id": 31, "name": "Front of house" }, "scoring": "points", "sections_count": 4, "questions_count": 18, "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "audits_30d": 12, "avg_result_30d": 81.4, "last_audit_at": "2026-11-02T18:40:00+05:00", "restricted": true, "ai_summary": false, "require_location": true, "require_signature": false, "deleted": false, "created_at": "2026-03-14T09:10:00+05:00", "updated_at": "2026-10-28T16:22:00+05:00", "url": "https://app.jecheck.io/ui/checklists/5845/edit", "available_from": "00:01", "available_to": "23:59", "select_manager": false, "send_to_location": false, "scenario_id": null, "access": [ { "type": "position", "id": 14 }, { "type": "department", "id": 12 } ], "sections": [ { "id": 21626, "name": "Kitchen", "responsible": null, "questions": [ { "id": 197426, "number": 1, "text": "Fridge temperature is within the norm", "description": "Check the display of fridge #2", "type": "number", "weight": 5, "can_skip": false, "photo_required": true, "settings": { "unit": "°C", "min": 2, "max": 6, "decimals": 1, "fail_all": true }, "responsible": { "to": "role", "position_id": 14 }, "auto_task": { "enabled": true, "deadline_hours": 24 } } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/folders": { "get": { "operationId": "checklistsFoldersList", "summary": "List checklist folders", "description": "Folders are flat and shared with the mobile app.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_folders_list", "x-permissions": [ "checklists.view" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "checklists_count": { "type": "integer" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 31, "name": "Front of house", "color": "blue", "checklists_count": 7 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "checklistsFoldersCreate", "summary": "Create a checklist folder", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_folders_create", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Folder name, unique in the company", "minLength": 1, "maxLength": 100 }, "color": { "type": [ "string", "null" ], "enum": [ "blue", "green", "amber", "red", "violet", "teal", "gray" ], "description": "Color label" }, "checklist_ids": { "type": "array", "items": { "type": "integer" }, "description": "Checklists to move into the new folder", "maxItems": 500 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "color": "blue", "checklist_ids": [ 12, 14 ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "checklists_count": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 31, "name": "Front of house", "color": "blue", "checklists_count": 7 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/folders/{id}": { "patch": { "operationId": "checklistsFoldersUpdate", "summary": "Rename or recolor a checklist folder", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_folders_update", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Folder id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name", "minLength": 1, "maxLength": 100 }, "color": { "type": [ "string", "null" ], "enum": [ "blue", "green", "amber", "red", "violet", "teal", "gray" ], "description": "Color label" } } }, "example": { "name": "Replace the broken fridge seal", "color": "blue" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "checklists_count": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 31, "name": "Front of house", "color": "blue", "checklists_count": 7 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "checklistsFoldersDelete", "summary": "Delete a checklist folder", "description": "Deletes the folder; its checklists are not deleted and move to \"no folder\".", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_folders_delete", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Folder id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/move": { "post": { "operationId": "checklistsMove", "summary": "Move checklists to a folder", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_move", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "Checklist ids", "minItems": 1, "maxItems": 500 }, "folder_id": { "type": [ "integer", "null" ], "description": "Target folder id; `null` — no folder" } }, "required": [ "ids", "folder_id" ] }, "example": { "ids": [ 12, 14 ], "folder_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "moved": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "moved": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/{id}": { "get": { "operationId": "checklistsGet", "summary": "Retrieve a checklist with its structure", "description": "Settings, who may run it (`access`; empty — everyone) and the full structure: sections in order, questions with answer type, weight, photo requirement, type settings (options, norms, `show_if` display conditions, `fail_all`), responsible for fixing violations and auto-task settings. `scoring`: `points` — result is the share of earned weight, `percent` — share of compliant answers.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_get", "x-permissions": [ "checklists.view" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "scoring": { "type": "string" }, "sections_count": { "type": "integer" }, "questions_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "audits_30d": { "type": "integer" }, "avg_result_30d": { "type": "number" }, "last_audit_at": { "type": "string", "format": "date-time" }, "restricted": { "type": "boolean" }, "ai_summary": { "type": "boolean" }, "require_location": { "type": "boolean" }, "require_signature": { "type": "boolean" }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "available_from": { "type": "string" }, "available_to": { "type": "string" }, "select_manager": { "type": "boolean" }, "send_to_location": { "type": "boolean" }, "scenario_id": { "type": [ "string", "null" ] }, "access": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "responsible": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "text": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo_required": { "type": "boolean" }, "settings": { "type": "object", "properties": { "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "decimals": { "type": "integer" }, "fail_all": { "type": "boolean" } } }, "responsible": { "type": "object", "properties": { "to": { "type": "string" }, "position_id": { "type": "integer" } } }, "auto_task": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "deadline_hours": { "type": "integer" } } } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5845, "name": "Daily dining room check", "description": "Opening check of the hall, restrooms and staff", "folder": { "id": 31, "name": "Front of house" }, "scoring": "points", "sections_count": 4, "questions_count": 18, "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "audits_30d": 12, "avg_result_30d": 81.4, "last_audit_at": "2026-11-02T18:40:00+05:00", "restricted": true, "ai_summary": false, "require_location": true, "require_signature": false, "deleted": false, "created_at": "2026-03-14T09:10:00+05:00", "updated_at": "2026-10-28T16:22:00+05:00", "url": "https://app.jecheck.io/ui/checklists/5845/edit", "available_from": "00:01", "available_to": "23:59", "select_manager": false, "send_to_location": false, "scenario_id": null, "access": [ { "type": "position", "id": 14 }, { "type": "department", "id": 12 } ], "sections": [ { "id": 21626, "name": "Kitchen", "responsible": null, "questions": [ { "id": 197426, "number": 1, "text": "Fridge temperature is within the norm", "description": "Check the display of fridge #2", "type": "number", "weight": 5, "can_skip": false, "photo_required": true, "settings": { "unit": "°C", "min": 2, "max": 6, "decimals": 1, "fail_all": true }, "responsible": { "to": "role", "position_id": 14 }, "auto_task": { "enabled": true, "deadline_hours": 24 } } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "checklistsUpdate", "summary": "Update checklist settings", "description": "Partial update of the checklist settings: send only the fields to change. The structure is changed with `checklists.structure.update`. `ai_summary` (AI report on each audit) requires the AI feature of the plan.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_update", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name", "minLength": 5, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Description", "maxLength": 5000 }, "folder_id": { "type": [ "integer", "null" ], "description": "Folder id; `null` — no folder" }, "scoring": { "type": "string", "enum": [ "points", "percent" ], "description": "Scoring mode" }, "ai_summary": { "type": "boolean", "description": "Generate an AI report for each audit" }, "require_location": { "type": "boolean", "description": "The app records the auditor geolocation" }, "require_signature": { "type": "boolean", "description": "The audit must be signed" }, "select_manager": { "type": "boolean", "description": "The auditor picks the location manager at the end of the audit" }, "send_to_location": { "type": "boolean", "description": "Send the report to the location managers" }, "available_from": { "type": "string", "description": "The checklist can be started from this time of day, `HH:MM`" }, "available_to": { "type": "string", "description": "…and until this time of day, `HH:MM`" }, "scenario_id": { "type": [ "integer", "null" ], "description": "Automation scenario for violations; `null` — the company default" } } }, "example": { "name": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "folder_id": 42, "scoring": "points" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "scoring": { "type": "string" }, "sections_count": { "type": "integer" }, "questions_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "audits_30d": { "type": "integer" }, "avg_result_30d": { "type": "number" }, "last_audit_at": { "type": "string", "format": "date-time" }, "restricted": { "type": "boolean" }, "ai_summary": { "type": "boolean" }, "require_location": { "type": "boolean" }, "require_signature": { "type": "boolean" }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "available_from": { "type": "string" }, "available_to": { "type": "string" }, "select_manager": { "type": "boolean" }, "send_to_location": { "type": "boolean" }, "scenario_id": { "type": [ "string", "null" ] }, "access": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "responsible": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "text": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo_required": { "type": "boolean" }, "settings": { "type": "object", "properties": { "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "decimals": { "type": "integer" }, "fail_all": { "type": "boolean" } } }, "responsible": { "type": "object", "properties": { "to": { "type": "string" }, "position_id": { "type": "integer" } } }, "auto_task": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "deadline_hours": { "type": "integer" } } } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5845, "name": "Daily dining room check", "description": "Opening check of the hall, restrooms and staff", "folder": { "id": 31, "name": "Front of house" }, "scoring": "points", "sections_count": 4, "questions_count": 18, "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "audits_30d": 12, "avg_result_30d": 81.4, "last_audit_at": "2026-11-02T18:40:00+05:00", "restricted": true, "ai_summary": false, "require_location": true, "require_signature": false, "deleted": false, "created_at": "2026-03-14T09:10:00+05:00", "updated_at": "2026-10-28T16:22:00+05:00", "url": "https://app.jecheck.io/ui/checklists/5845/edit", "available_from": "00:01", "available_to": "23:59", "select_manager": false, "send_to_location": false, "scenario_id": null, "access": [ { "type": "position", "id": 14 }, { "type": "department", "id": 12 } ], "sections": [ { "id": 21626, "name": "Kitchen", "responsible": null, "questions": [ { "id": 197426, "number": 1, "text": "Fridge temperature is within the norm", "description": "Check the display of fridge #2", "type": "number", "weight": 5, "can_skip": false, "photo_required": true, "settings": { "unit": "°C", "min": 2, "max": 6, "decimals": 1, "fail_all": true }, "responsible": { "to": "role", "position_id": 14 }, "auto_task": { "enabled": true, "deadline_hours": 24 } } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "checklistsDelete", "summary": "Delete a checklist", "description": "Moves the checklist to the trash for 30 days (restore with `checklists.restore`). Audits already conducted stay in the journal and analytics.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_delete", "x-permissions": [ "checklists.delete" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/{id}/access": { "get": { "operationId": "checklistsAccessGet", "summary": "Get who can run a checklist", "description": "Rules of \"who can run\" the checklist in the mobile app: employees (`user`), positions (`position`), locations (`department`) and teams (`team`). An empty list means everyone; administrators can always run any checklist.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_access_get", "x-permissions": [ "checklists.view" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "rules": [ { "type": "position", "id": 14 }, { "type": "user", "id": 311 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "checklistsAccessSet", "summary": "Set who can run a checklist", "description": "Replaces the access rules. Subjects of another company are ignored. An empty `rules` list makes the checklist available to everyone. The planner only lets you assign audits of a checklist to people who can run it.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_access_set", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "position", "department", "team" ], "description": "Subject type" }, "id": { "type": "integer", "description": "Id of the employee, position, location or team" } }, "required": [ "type", "id" ] }, "description": "Rules; empty — available to everyone", "maxItems": 500 } }, "required": [ "rules" ] }, "example": { "rules": [ { "type": "user", "id": 42 } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "rules": [ { "type": "position", "id": 14 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/{id}/duplicate": { "post": { "operationId": "checklistsDuplicate", "summary": "Duplicate a checklist", "description": "Copies the checklist with all sections, questions, settings and access rules. The copy gets the original name with a fixed \"copy\" suffix (written in Russian, as in the web app) — rename it with `checklists.update`.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_duplicate", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "scoring": { "type": "string" }, "sections_count": { "type": "integer" }, "questions_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "audits_30d": { "type": "integer" }, "avg_result_30d": { "type": "number" }, "last_audit_at": { "type": "string", "format": "date-time" }, "restricted": { "type": "boolean" }, "ai_summary": { "type": "boolean" }, "require_location": { "type": "boolean" }, "require_signature": { "type": "boolean" }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "available_from": { "type": "string" }, "available_to": { "type": "string" }, "select_manager": { "type": "boolean" }, "send_to_location": { "type": "boolean" }, "scenario_id": { "type": [ "string", "null" ] }, "access": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "responsible": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "text": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo_required": { "type": "boolean" }, "settings": { "type": "object", "properties": { "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "decimals": { "type": "integer" }, "fail_all": { "type": "boolean" } } }, "responsible": { "type": "object", "properties": { "to": { "type": "string" }, "position_id": { "type": "integer" } } }, "auto_task": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "deadline_hours": { "type": "integer" } } } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5845, "name": "Daily dining room check", "description": "Opening check of the hall, restrooms and staff", "folder": { "id": 31, "name": "Front of house" }, "scoring": "points", "sections_count": 4, "questions_count": 18, "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "audits_30d": 12, "avg_result_30d": 81.4, "last_audit_at": "2026-11-02T18:40:00+05:00", "restricted": true, "ai_summary": false, "require_location": true, "require_signature": false, "deleted": false, "created_at": "2026-03-14T09:10:00+05:00", "updated_at": "2026-10-28T16:22:00+05:00", "url": "https://app.jecheck.io/ui/checklists/5845/edit", "available_from": "00:01", "available_to": "23:59", "select_manager": false, "send_to_location": false, "scenario_id": null, "access": [ { "type": "position", "id": 14 }, { "type": "department", "id": 12 } ], "sections": [ { "id": 21626, "name": "Kitchen", "responsible": null, "questions": [ { "id": 197426, "number": 1, "text": "Fridge temperature is within the norm", "description": "Check the display of fridge #2", "type": "number", "weight": 5, "can_skip": false, "photo_required": true, "settings": { "unit": "°C", "min": 2, "max": 6, "decimals": 1, "fail_all": true }, "responsible": { "to": "role", "position_id": 14 }, "auto_task": { "enabled": true, "deadline_hours": 24 } } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/{id}/media": { "post": { "operationId": "checklistsMediaUpload", "summary": "Upload a reference photo", "description": "Uploads a reference image (\"how it should look\") and returns its public URL. Put the URL into `settings.media` of a question with `checklists.structure.update` (up to 5 per question).", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_media_upload", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "Image file, up to 10 MB" } }, "required": [ "image" ] } }, "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "Image file, up to 10 MB" } }, "required": [ "image" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "url": "https://jecheck.s3.eu-west-1.amazonaws.com/checklists/761/reference/9f1c2b.jpg" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/{id}/responsible": { "put": { "operationId": "checklistsResponsibleSet", "summary": "Set who fixes violations of a section or question", "description": "\"Who fixes\" a violation: `managers` — location managers, `role` — employees of a position (`position_id`), `team` — a team queue (`team_id`), `user` — a specific employee (`user_id`). `null` — default (a question inherits its section, a section — location managers). Automation scenarios and auto-tasks assign violations by this setting.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_responsible_set", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "section", "question" ], "description": "What to configure" }, "target_id": { "type": "integer", "description": "Section or question id of this checklist" }, "responsible": { "type": [ "object", "null" ], "properties": { "to": { "type": "string", "enum": [ "managers", "role", "team", "user" ], "description": "Who fixes: managers, role, team or user" }, "position_id": { "type": "integer" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" } }, "description": "Target, or `null` to reset to the default" } }, "required": [ "target", "target_id", "responsible" ] }, "example": { "target": "section", "target_id": 42, "responsible": { "to": "managers", "position_id": 42, "team_id": 42 } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "target": { "type": "string" }, "target_id": { "type": "integer" }, "responsible": { "type": "object", "properties": { "to": { "type": "string" }, "position_id": { "type": "integer" } } } } } }, "required": [ "data" ] }, "example": { "data": { "target": "question", "target_id": 197426, "responsible": { "to": "role", "position_id": 14 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/{id}/restore": { "post": { "operationId": "checklistsRestore", "summary": "Restore a deleted checklist", "description": "Returns a checklist from the trash: it is available again in the list, the planner and the app.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_restore", "x-permissions": [ "checklists.delete" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "scoring": { "type": "string" }, "sections_count": { "type": "integer" }, "questions_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "audits_30d": { "type": "integer" }, "avg_result_30d": { "type": "number" }, "last_audit_at": { "type": "string", "format": "date-time" }, "restricted": { "type": "boolean" }, "ai_summary": { "type": "boolean" }, "require_location": { "type": "boolean" }, "require_signature": { "type": "boolean" }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "available_from": { "type": "string" }, "available_to": { "type": "string" }, "select_manager": { "type": "boolean" }, "send_to_location": { "type": "boolean" }, "scenario_id": { "type": [ "string", "null" ] }, "access": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "responsible": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "text": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo_required": { "type": "boolean" }, "settings": { "type": "object", "properties": { "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "decimals": { "type": "integer" }, "fail_all": { "type": "boolean" } } }, "responsible": { "type": "object", "properties": { "to": { "type": "string" }, "position_id": { "type": "integer" } } }, "auto_task": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "deadline_hours": { "type": "integer" } } } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5845, "name": "Daily dining room check", "description": "Opening check of the hall, restrooms and staff", "folder": { "id": 31, "name": "Front of house" }, "scoring": "points", "sections_count": 4, "questions_count": 18, "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "audits_30d": 12, "avg_result_30d": 81.4, "last_audit_at": "2026-11-02T18:40:00+05:00", "restricted": true, "ai_summary": false, "require_location": true, "require_signature": false, "deleted": false, "created_at": "2026-03-14T09:10:00+05:00", "updated_at": "2026-10-28T16:22:00+05:00", "url": "https://app.jecheck.io/ui/checklists/5845/edit", "available_from": "00:01", "available_to": "23:59", "select_manager": false, "send_to_location": false, "scenario_id": null, "access": [ { "type": "position", "id": 14 }, { "type": "department", "id": 12 } ], "sections": [ { "id": 21626, "name": "Kitchen", "responsible": null, "questions": [ { "id": 197426, "number": 1, "text": "Fridge temperature is within the norm", "description": "Check the display of fridge #2", "type": "number", "weight": 5, "can_skip": false, "photo_required": true, "settings": { "unit": "°C", "min": 2, "max": 6, "decimals": 1, "fail_all": true }, "responsible": { "to": "role", "position_id": 14 }, "auto_task": { "enabled": true, "deadline_hours": 24 } } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/checklists/{id}/structure": { "put": { "operationId": "checklistsStructureUpdate", "summary": "Replace the checklist structure", "description": "Sends the whole structure at once (as in `checklists.get`). Pass `id` for sections and questions you keep — their audit history stays linked; items without `id` are created, items not listed are removed. Existing sections cannot be reordered (new ones are appended at the end); questions can be reordered and moved between sections. For an existing question without `settings` the current settings are kept.", "tags": [ "Checklists" ], "x-mcp-tool": "checklists_structure_update", "x-permissions": [ "checklists.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name (kept if omitted)", "minLength": 5, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "New description (kept if omitted)", "maxLength": 5000 }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Existing section id to keep; omit for a new section" }, "name": { "type": "string", "description": "Section name", "minLength": 2, "maxLength": 512 }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Existing question id to keep (its audit history stays linked); omit for a new question" }, "text": { "type": "string", "description": "Question wording (at least 5 characters)", "minLength": 5, "maxLength": 2000 }, "description": { "type": [ "string", "null" ], "description": "Hint for the auditor", "maxLength": 5000 }, "type": { "type": "string", "enum": [ "yes_no", "text", "choice", "multi", "number", "scale", "date", "signature", "photo", "instruction", "barcode", "employee" ], "default": "yes_no", "description": "Answer type. `yes_no` (default) — complies / violation / not applicable; `choice`/`multi` need `settings.options`; `number` may have a norm `settings.min`/`max`; see the Checklists guide" }, "weight": { "type": "integer", "default": 1, "description": "Weight (points) of the question, 1–100", "minimum": 1, "maximum": 100 }, "photo_required": { "type": "boolean", "default": false, "description": "The auditor must attach a photo" }, "can_skip": { "type": "boolean", "default": false, "description": "The question may be skipped" }, "fail_all": { "type": "boolean", "description": "A violation on this question sets the whole audit result to 0 (scored types only)" }, "settings": { "type": [ "object", "null" ], "properties": {}, "additionalProperties": true, "description": "Type settings, e.g. `{\"options\":[{\"id\":\"a1\",\"label\":\"Clean\",\"result\":1,\"score\":1},{\"id\":\"a2\",\"label\":\"Dirty\",\"result\":2,\"score\":0}]}` for `choice`, `{\"unit\":\"°C\",\"min\":2,\"max\":6}` for `number`, `{\"min\":1,\"max\":5,\"pass\":4}` for `scale`; common keys `fail_all`, `show_if`, `media`" } }, "required": [ "text" ] }, "description": "Questions of the section, in order" } }, "required": [ "name", "questions" ] }, "description": "The complete new structure. Existing sections keep their order (new sections can only be appended); sections and questions not listed are removed", "maxItems": 60 } }, "required": [ "sections" ] }, "example": { "name": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "sections": [ { "id": 42, "name": "Replace the broken fridge seal", "questions": [ { "id": 42, "text": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C." } ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "scoring": { "type": "string" }, "sections_count": { "type": "integer" }, "questions_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "audits_30d": { "type": "integer" }, "avg_result_30d": { "type": "number" }, "last_audit_at": { "type": "string", "format": "date-time" }, "restricted": { "type": "boolean" }, "ai_summary": { "type": "boolean" }, "require_location": { "type": "boolean" }, "require_signature": { "type": "boolean" }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "available_from": { "type": "string" }, "available_to": { "type": "string" }, "select_manager": { "type": "boolean" }, "send_to_location": { "type": "boolean" }, "scenario_id": { "type": [ "string", "null" ] }, "access": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "responsible": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "text": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo_required": { "type": "boolean" }, "settings": { "type": "object", "properties": { "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "decimals": { "type": "integer" }, "fail_all": { "type": "boolean" } } }, "responsible": { "type": "object", "properties": { "to": { "type": "string" }, "position_id": { "type": "integer" } } }, "auto_task": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "deadline_hours": { "type": "integer" } } } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5845, "name": "Daily dining room check", "description": "Opening check of the hall, restrooms and staff", "folder": { "id": 31, "name": "Front of house" }, "scoring": "points", "sections_count": 4, "questions_count": 18, "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "audits_30d": 12, "avg_result_30d": 81.4, "last_audit_at": "2026-11-02T18:40:00+05:00", "restricted": true, "ai_summary": false, "require_location": true, "require_signature": false, "deleted": false, "created_at": "2026-03-14T09:10:00+05:00", "updated_at": "2026-10-28T16:22:00+05:00", "url": "https://app.jecheck.io/ui/checklists/5845/edit", "available_from": "00:01", "available_to": "23:59", "select_manager": false, "send_to_location": false, "scenario_id": null, "access": [ { "type": "position", "id": 14 }, { "type": "department", "id": 12 } ], "sections": [ { "id": 21626, "name": "Kitchen", "responsible": null, "questions": [ { "id": 197426, "number": 1, "text": "Fridge temperature is within the norm", "description": "Check the display of fridge #2", "type": "number", "weight": 5, "can_skip": false, "photo_required": true, "settings": { "unit": "°C", "min": 2, "max": 6, "decimals": 1, "fail_all": true }, "responsible": { "to": "role", "position_id": 14 }, "auto_task": { "enabled": true, "deadline_hours": 24 } } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/company": { "get": { "operationId": "accountCompany", "summary": "Get the company profile", "description": "Company settings that matter for integrations: name, country, language of reports, time zone, plan and its paid features, number of locations.", "tags": [ "Account" ], "x-mcp-tool": "account_company", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "plan": { "type": "object", "properties": { "key": { "type": "string" }, "until": { "type": [ "string", "null" ] }, "features": { "type": "array", "items": { "type": "string" } } } }, "locations_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 761, "name": "Coffee Lab", "country": "KZ", "locale": "ru", "timezone": "Asia/Almaty", "plan": { "key": "enterprise", "until": null, "features": [ "automation", "ai", "testing", "haccp", "api" ] }, "locations_count": 14, "created_at": "2024-03-02T09:15:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards": { "get": { "operationId": "dashboardsList", "summary": "List dashboards", "description": "Dashboards visible to the acting user: own, shared with them and published to the whole company, in the user's tab order.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_list", "x-scope": "read", "parameters": [ { "name": "include_hidden", "in": "query", "description": "Include dashboards the user hid from tabs", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "filters": { "type": "object", "properties": { "period": { "type": "string" }, "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "checklist_ids": { "type": "array" }, "auditor_ids": { "type": "array" } } }, "visibility": { "type": "string" }, "company_can_edit": { "type": "boolean" }, "refresh_sec": { "type": "integer" }, "template": { "type": "string" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_owner": { "type": "boolean" }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "share": { "type": "boolean" }, "delete": { "type": "boolean" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "hidden": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "title": "Location overview", "icon": "dashboard", "description": "Weekly picture of all coffee shops", "filters": { "period": "30d", "date_from": null, "date_to": null, "location_ids": [ 12, 14 ], "checklist_ids": [], "auditor_ids": [] }, "visibility": "company", "company_can_edit": false, "refresh_sec": 0, "template": "location", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "is_owner": false, "permissions": { "edit": false, "share": false, "delete": false }, "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/dashboards/2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "hidden": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "dashboardsCreate", "summary": "Create a dashboard", "description": "Creates a private dashboard of the acting user — empty, from a template (`dashboards.catalog` → templates) and/or with the given cards. Publish it with `dashboards.share`.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_create", "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title", "maxLength": 120 }, "icon": { "type": "string", "description": "Material Symbols icon name", "maxLength": 40 }, "description": { "type": "string", "maxLength": 500 }, "template": { "type": "string", "enum": [ "network", "quality", "operations", "location", "haccp", "training", "mystery" ], "description": "Template key" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "spec": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Card definition" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "preset": { "type": "string", "description": "Ready-made card key", "maxLength": 60 } }, "required": [ "spec" ] }, "description": "Cards to add (layout is packed automatically when x/y are omitted)", "maxItems": 60 } } }, "example": { "title": "Replace the broken fridge seal", "icon": "string", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "template": "network" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "filters": { "type": "object", "properties": { "period": { "type": "string" }, "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "checklist_ids": { "type": "array" }, "auditor_ids": { "type": "array" } } }, "visibility": { "type": "string" }, "company_can_edit": { "type": "boolean" }, "refresh_sec": { "type": "integer" }, "template": { "type": "string" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_owner": { "type": "boolean" }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "share": { "type": "boolean" }, "delete": { "type": "boolean" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "title": "Location overview", "icon": "dashboard", "description": "Weekly picture of all coffee shops", "filters": { "period": "30d", "date_from": null, "date_to": null, "location_ids": [ 12, 14 ], "checklist_ids": [], "auditor_ids": [] }, "visibility": "company", "company_can_edit": false, "refresh_sec": 0, "template": "location", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "is_owner": false, "permissions": { "edit": false, "share": false, "delete": false }, "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/dashboards/2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "widgets": [ { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/ai/card": { "post": { "operationId": "dashboardsAiCard", "summary": "Build a card from a description (AI)", "description": "AI turns a request in plain words (\"average score by location for 90 days\") into a card definition and computes it. Nothing is saved — add it with `dashboards.widgets.create`. Daily AI limits apply.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_ai_card", "x-plan-feature": "ai", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 1000 }, "spec": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Current card to adjust" }, "period": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "description": "Period; `custom` needs `date_from` and `date_to`" }, "date_from": { "type": "string", "format": "date", "description": "Start of a custom period" }, "date_to": { "type": "string", "format": "date", "description": "End of a custom period" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these locations (within the viewer's permissions)" }, "checklist_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these checklists" }, "auditor_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these auditors" } }, "required": [ "prompt" ] }, "example": { "prompt": "string", "spec": [], "period": "7d", "date_from": "2026-11-01" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "explanation": { "type": "string" }, "size": { "type": "object", "properties": { "w": { "type": "integer" }, "h": { "type": "integer" } } }, "data": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "number" }, "previous": { "type": "number" }, "unit": { "type": "string" }, "meta": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "explanation": "Average audit score with comparison to the previous period", "size": { "w": 3, "h": 2 }, "data": { "kind": "value", "value": 82.4, "previous": 79.1, "unit": "%", "meta": { "from": "2026-10-04", "to": "2026-11-03" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/ai/dashboard": { "post": { "operationId": "dashboardsAiDashboard", "summary": "Draft a dashboard from a description (AI)", "description": "Returns a draft (title, cards and layout) — nothing is saved; pass `widgets` to `dashboards.create`.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_ai_dashboard", "x-plan-feature": "ai", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 2000 } }, "required": [ "prompt" ] }, "example": { "prompt": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "title": { "type": "string" }, "icon": { "type": "string" }, "explanation": { "type": "string" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "title": "Kitchen quality", "icon": "restaurant", "explanation": "Scores, failed questions and overdue tasks", "widgets": [ { "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "ai" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/catalog": { "get": { "operationId": "dashboardsCatalog", "summary": "Get the metrics catalog", "description": "Everything a card can be built from: metric groups, metrics (unit, which direction is better, allowed dimensions, availability for the acting user), dimensions, card types and their rules, lists, periods, ready-made cards (`presets`) and dashboard templates.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_catalog", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" } } } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string" } } } }, "types": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "integer" } }, "dimension": { "type": "boolean" } } } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "group": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "unit": { "type": "string" }, "better": { "type": "string" }, "dimensions": { "type": "array", "items": { "type": "string" } }, "snapshot": { "type": "boolean" }, "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } } } }, "lists": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "group": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } } } }, "periods": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } } } }, "presets": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "group": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" } } }, "w": { "type": "integer" }, "h": { "type": "integer" }, "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } } } }, "templates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "presets": { "type": "array", "items": { "type": "string" } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "groups": [ { "key": "audits", "label": "Audits", "icon": "fact_check" } ], "dimensions": [ { "key": "location", "label": "Location", "kind": "category" } ], "types": [ { "key": "kpi", "label": "Number", "icon": "pin", "metrics": [ 1, 1 ], "dimension": false } ], "metrics": [ { "key": "audits.avg_result", "group": "audits", "label": "Average score", "description": "Average audit result", "unit": "%", "better": "up", "dimensions": [ "time", "location", "checklist" ], "snapshot": false, "available": true, "reason": null } ], "lists": [ { "key": "tasks.overdue", "group": "tasks", "label": "Overdue tasks", "description": "Open tasks past due", "available": true, "reason": null } ], "periods": [ { "key": "30d", "label": "30 days" } ], "presets": [ { "key": "kpi_avg", "group": "audits", "label": "Average score", "description": "Average audit result with trend", "type": "kpi", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true }, "w": 3, "h": 2, "available": true, "reason": null } ], "templates": [ { "key": "location", "label": "Location overview", "description": "Key figures of locations", "icon": "storefront", "presets": [ "kpi_avg" ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/order": { "put": { "operationId": "dashboardsReorder", "summary": "Reorder and hide dashboard tabs", "description": "Personal tab order of the acting user; `hidden` — dashboards to hide from the tabs.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_reorder", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Dashboard UUIDs in the new order", "maxItems": 200 }, "hidden": { "type": "array", "items": { "type": "string" }, "description": "Hidden dashboard UUIDs", "maxItems": 200 } }, "required": [ "uuids" ] }, "example": { "uuids": [ "example" ], "hidden": [ "example" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "ok": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/preview": { "post": { "operationId": "dashboardsPreview", "summary": "Compute a card without saving it", "description": "Runs a card definition with the given filters — use it to try a `spec` before adding the card.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_preview", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Card definition: {\"type\", \"metrics\", \"dimension\", \"dimension2\", \"list\", \"period\", \"title\", \"target\", \"compare\", \"limit\", \"color\", \"text\"} — see `dashboards.catalog` for metric, dimension, list and type keys" }, "period": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "description": "Period; `custom` needs `date_from` and `date_to`" }, "date_from": { "type": "string", "format": "date", "description": "Start of a custom period" }, "date_to": { "type": "string", "format": "date", "description": "End of a custom period" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these locations (within the viewer's permissions)" }, "checklist_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these checklists" }, "auditor_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these auditors" } }, "required": [ "spec" ] }, "example": { "spec": [], "period": "7d", "date_from": "2026-11-01", "date_to": "2026-11-30" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "number" }, "previous": { "type": "number" }, "unit": { "type": "string" }, "meta": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "kind": "value", "value": 82.4, "previous": 79.1, "unit": "%", "meta": { "from": "2026-10-04", "to": "2026-11-03" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}": { "get": { "operationId": "dashboardsGet", "summary": "Retrieve a dashboard", "description": "Dashboard settings, saved filters, the acting user's permissions and the cards with their layout on a 12-column grid. Card values — `dashboards.data`.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "filters": { "type": "object", "properties": { "period": { "type": "string" }, "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "checklist_ids": { "type": "array" }, "auditor_ids": { "type": "array" } } }, "visibility": { "type": "string" }, "company_can_edit": { "type": "boolean" }, "refresh_sec": { "type": "integer" }, "template": { "type": "string" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_owner": { "type": "boolean" }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "share": { "type": "boolean" }, "delete": { "type": "boolean" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "title": "Location overview", "icon": "dashboard", "description": "Weekly picture of all coffee shops", "filters": { "period": "30d", "date_from": null, "date_to": null, "location_ids": [ 12, 14 ], "checklist_ids": [], "auditor_ids": [] }, "visibility": "company", "company_can_edit": false, "refresh_sec": 0, "template": "location", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "is_owner": false, "permissions": { "edit": false, "share": false, "delete": false }, "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/dashboards/2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "widgets": [ { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "dashboardsUpdate", "summary": "Update a dashboard", "description": "Title, icon, description, saved filters and auto-refresh. Requires edit access.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "icon": { "type": [ "string", "null" ], "maxLength": 40 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "filters": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "description": "Period; `custom` needs `date_from` and `date_to`" }, "date_from": { "type": "string", "format": "date", "description": "Start of a custom period" }, "date_to": { "type": "string", "format": "date", "description": "End of a custom period" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these locations (within the viewer's permissions)" }, "checklist_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these checklists" }, "auditor_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these auditors" } }, "description": "Saved filters: period, date_from, date_to, location_ids, checklist_ids, auditor_ids" }, "refresh_sec": { "type": "integer", "description": "Auto-refresh in the web app, seconds (0 — off, minimum 60)", "minimum": 0, "maximum": 3600 } } }, "example": { "title": "Replace the broken fridge seal", "icon": "string", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "filters": { "period": "7d", "date_from": "2026-11-01", "date_to": "2026-11-30" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "filters": { "type": "object", "properties": { "period": { "type": "string" }, "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "checklist_ids": { "type": "array" }, "auditor_ids": { "type": "array" } } }, "visibility": { "type": "string" }, "company_can_edit": { "type": "boolean" }, "refresh_sec": { "type": "integer" }, "template": { "type": "string" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_owner": { "type": "boolean" }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "share": { "type": "boolean" }, "delete": { "type": "boolean" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "title": "Location overview", "icon": "dashboard", "description": "Weekly picture of all coffee shops", "filters": { "period": "30d", "date_from": null, "date_to": null, "location_ids": [ 12, 14 ], "checklist_ids": [], "auditor_ids": [] }, "visibility": "company", "company_can_edit": false, "refresh_sec": 0, "template": "location", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "is_owner": false, "permissions": { "edit": false, "share": false, "delete": false }, "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/dashboards/2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "widgets": [ { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "dashboardsDelete", "summary": "Delete a dashboard", "description": "Allowed to the owner; a company dashboard — also with `dashboards.company`.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/data": { "get": { "operationId": "dashboardsData", "summary": "Get computed data of all cards", "description": "Values of every card (or of `widget_uuids`), keyed by card UUID. Computed with the dashboard filters, or with the filters passed here (temporary, not saved). Data is always limited by the acting user's permissions; a card the user may not see returns `{\"error\": \"...\", \"message\": \"...\"}`.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_data", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "widget_uuids[]", "in": "query", "description": "Only these cards", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 60 }, "style": "form", "explode": true }, { "name": "period", "in": "query", "description": "Period; `custom` needs `date_from` and `date_to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ] } }, { "name": "date_from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations (within the viewer's permissions)", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only these auditors", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "number" }, "previous": { "type": "number" }, "unit": { "type": "string" }, "meta": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d": { "kind": "value", "value": 82.4, "previous": 79.1, "unit": "%", "meta": { "from": "2026-10-04", "to": "2026-11-03" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/duplicate": { "post": { "operationId": "dashboardsDuplicate", "summary": "Duplicate a dashboard", "description": "Creates a private copy owned by the acting user.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_duplicate", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "filters": { "type": "object", "properties": { "period": { "type": "string" }, "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "checklist_ids": { "type": "array" }, "auditor_ids": { "type": "array" } } }, "visibility": { "type": "string" }, "company_can_edit": { "type": "boolean" }, "refresh_sec": { "type": "integer" }, "template": { "type": "string" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_owner": { "type": "boolean" }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "share": { "type": "boolean" }, "delete": { "type": "boolean" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "title": "Location overview", "icon": "dashboard", "description": "Weekly picture of all coffee shops", "filters": { "period": "30d", "date_from": null, "date_to": null, "location_ids": [ 12, 14 ], "checklist_ids": [], "auditor_ids": [] }, "visibility": "company", "company_can_edit": false, "refresh_sec": 0, "template": "location", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "is_owner": false, "permissions": { "edit": false, "share": false, "delete": false }, "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/dashboards/2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "widgets": [ { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/layout": { "put": { "operationId": "dashboardsLayout", "summary": "Change the card layout", "description": "Positions and sizes of cards on the 12-column grid. Requires edit access.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_layout", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Card UUID" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" } }, "required": [ "uuid", "x", "y", "w", "h" ] }, "maxItems": 60 } }, "required": [ "items" ] }, "example": { "items": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "x": 42, "y": 42, "w": 42, "h": 42 } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/share": { "get": { "operationId": "dashboardsSharing", "summary": "Get dashboard sharing", "description": "Who has access: visibility (`private` / `company`), whether everyone may edit a company dashboard, and colleagues with personal access. For the owner (and `dashboards.company` on company dashboards).", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_sharing", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "visibility": { "type": "string" }, "company_can_edit": { "type": "boolean" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "shares": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "can_edit": { "type": "boolean" } } } }, "can_publish_to_company": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "visibility": "private", "company_can_edit": false, "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "shares": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "can_edit": true } ], "can_publish_to_company": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "dashboardsShare", "summary": "Share a dashboard", "description": "Replaces the sharing settings. Publishing to the whole company requires `dashboards.company`.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_share", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "company" ] }, "company_can_edit": { "type": "boolean", "default": false, "description": "Everyone in the company may edit (company dashboards)" }, "users": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer" }, "can_edit": { "type": "boolean" } }, "required": [ "user_id" ] }, "description": "Personal access (replaces the list)", "maxItems": 500 } }, "required": [ "visibility" ] }, "example": { "visibility": "private", "company_can_edit": false, "users": [ { "user_id": 42, "can_edit": true } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "visibility": { "type": "string" }, "company_can_edit": { "type": "boolean" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "shares": { "type": "array" }, "can_publish_to_company": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "visibility": "company", "company_can_edit": false, "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "shares": [], "can_publish_to_company": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/widgets": { "post": { "operationId": "dashboardsWidgetsCreate", "summary": "Add a card", "description": "Adds a card (custom `spec` or a ready-made `preset` spec from the catalog). Without x/y it goes below the existing cards. Up to 60 cards per dashboard. Requires edit access.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_widgets_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Card definition: {\"type\", \"metrics\", \"dimension\", \"dimension2\", \"list\", \"period\", \"title\", \"target\", \"compare\", \"limit\", \"color\", \"text\"} — see `dashboards.catalog` for metric, dimension, list and type keys" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "preset": { "type": "string", "description": "Ready-made card key (for reference)", "maxLength": 60 } }, "required": [ "spec" ] }, "example": { "spec": [], "x": 42, "y": 42, "w": 42 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/widgets/{widget_uuid}": { "put": { "operationId": "dashboardsWidgetsUpdate", "summary": "Replace a card definition", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_widgets_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "widget_uuid", "in": "path", "required": true, "description": "Card UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Card definition: {\"type\", \"metrics\", \"dimension\", \"dimension2\", \"list\", \"period\", \"title\", \"target\", \"compare\", \"limit\", \"color\", \"text\"} — see `dashboards.catalog` for metric, dimension, list and type keys" } }, "required": [ "spec" ] }, "example": { "spec": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "dashboardsWidgetsDelete", "summary": "Delete a card", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_widgets_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "widget_uuid", "in": "path", "required": true, "description": "Card UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/widgets/{widget_uuid}/copy": { "post": { "operationId": "dashboardsWidgetsCopy", "summary": "Copy a card to another dashboard", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_widgets_copy", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "widget_uuid", "in": "path", "required": true, "description": "Card UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_uuid": { "type": "string", "format": "uuid", "description": "Target dashboard (edit access required)" } }, "required": [ "target_uuid" ] }, "example": { "target_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "spec": { "type": "object", "properties": { "v": { "type": "integer" }, "type": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "compare": { "type": "boolean" }, "title": { "type": "string" } } }, "x": { "type": "integer" }, "y": { "type": "integer" }, "w": { "type": "integer" }, "h": { "type": "integer" }, "source": { "type": "string" }, "preset": { "type": "string" }, "dashboard_uuid": { "type": "string", "format": "uuid" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "7c6b5a4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "spec": { "v": 1, "type": "kpi", "metrics": [ "audits.avg_result" ], "compare": true, "title": "Average score" }, "x": 0, "y": 0, "w": 3, "h": 2, "source": "library", "preset": "kpi_avg", "dashboard_uuid": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/widgets/{widget_uuid}/data": { "get": { "operationId": "dashboardsWidgetsData", "summary": "Get computed data of a card", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_widgets_data", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "widget_uuid", "in": "path", "required": true, "description": "Card UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "query", "description": "Period; `custom` needs `date_from` and `date_to`", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ] } }, { "name": "date_from", "in": "query", "description": "Start of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "End of a custom period", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations (within the viewer's permissions)", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only these auditors", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "number" }, "previous": { "type": "number" }, "unit": { "type": "string" }, "meta": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "kind": "value", "value": 82.4, "previous": 79.1, "unit": "%", "meta": { "from": "2026-10-04", "to": "2026-11-03" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboards/{uuid}/widgets/{widget_uuid}/explain": { "post": { "operationId": "dashboardsAiExplain", "summary": "Explain card data (AI)", "description": "A short explanation of what the card shows for the acting user's data and filters.", "tags": [ "Dashboards" ], "x-mcp-tool": "dashboards_ai_explain", "x-plan-feature": "ai", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Dashboard UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "widget_uuid", "in": "path", "required": true, "description": "Card UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "7d", "30d", "90d", "12m", "custom" ], "description": "Period; `custom` needs `date_from` and `date_to`" }, "date_from": { "type": "string", "format": "date", "description": "Start of a custom period" }, "date_to": { "type": "string", "format": "date", "description": "End of a custom period" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these locations (within the viewer's permissions)" }, "checklist_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these checklists" }, "auditor_ids": { "type": "array", "items": { "type": "integer" }, "description": "Only these auditors" } } }, "example": { "period": "7d", "date_from": "2026-11-01", "date_to": "2026-11-30", "location_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "text": "The average score grew from 79% to 82%, mostly thanks to Abay Ave." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/feedback/appeals": { "get": { "operationId": "feedbackAppealsList", "summary": "List customer appeals", "description": "Conversations started by customers in the company Telegram or WhatsApp bot, newest first, with the last message. Contains customer contacts, so `appeals.view` is required.", "tags": [ "Guest feedback" ], "x-mcp-tool": "feedback_appeals_list", "x-permissions": [ "appeals.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "open", "closed" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "channel": { "type": "string" } } }, "assignee": { "type": [ "string", "null" ] }, "last_message": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "uuid": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "type": { "type": "string" }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 340, "title": "Lost umbrella", "status": "open", "contact": { "id": 77, "name": "Marat", "phone": null, "email": null, "channel": "telegram" }, "assignee": null, "last_message": { "id": 5521, "author": { "type": "customer", "id": 77, "uuid": null, "name": "Marat" }, "type": "text", "text": "Hello! I left my umbrella at Abay Ave yesterday.", "file": null, "created_at": "2026-11-03T09:12:00+05:00" }, "created_at": "2026-11-03T09:12:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/feedback/appeals/{id}": { "get": { "operationId": "feedbackAppealsGet", "summary": "Retrieve a customer appeal", "description": "The appeal with the whole conversation, oldest message first.", "tags": [ "Guest feedback" ], "x-mcp-tool": "feedback_appeals_get", "x-permissions": [ "appeals.view" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Appeal id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "channel": { "type": "string" } } }, "assignee": { "type": [ "string", "null" ] }, "last_message": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "uuid": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "type": { "type": "string" }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "uuid": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "type": { "type": "string" }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 340, "title": "Lost umbrella", "status": "open", "contact": { "id": 77, "name": "Marat", "phone": null, "email": null, "channel": "telegram" }, "assignee": null, "last_message": { "id": 5521, "author": { "type": "customer", "id": 77, "uuid": null, "name": "Marat" }, "type": "text", "text": "Hello! I left my umbrella at Abay Ave yesterday.", "file": null, "created_at": "2026-11-03T09:12:00+05:00" }, "created_at": "2026-11-03T09:12:00+05:00", "messages": [ { "id": 5521, "author": { "type": "customer", "id": 77, "uuid": null, "name": "Marat" }, "type": "text", "text": "Hello! I left my umbrella at Abay Ave yesterday.", "file": null, "created_at": "2026-11-03T09:12:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/feedback/appeals/{id}/messages": { "post": { "operationId": "feedbackAppealsReply", "summary": "Reply to a customer appeal", "description": "Sends a text message to the customer through the channel of the appeal (Telegram bot or WhatsApp) on behalf of the acting user. Returns the updated conversation.", "tags": [ "Guest feedback" ], "x-mcp-tool": "feedback_appeals_reply", "x-permissions": [ "appeals.view" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Appeal id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Message text", "minLength": 1, "maxLength": 4000 } }, "required": [ "text" ] }, "example": { "text": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "channel": { "type": "string" } } }, "assignee": { "type": [ "string", "null" ] }, "last_message": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "uuid": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "type": { "type": "string" }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "created_at": { "type": "string", "format": "date-time" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "uuid": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "type": { "type": "string" }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 340, "title": "Lost umbrella", "status": "open", "contact": { "id": 77, "name": "Marat", "phone": null, "email": null, "channel": "telegram" }, "assignee": null, "last_message": { "id": 5521, "author": { "type": "customer", "id": 77, "uuid": null, "name": "Marat" }, "type": "text", "text": "Hello! I left my umbrella at Abay Ave yesterday.", "file": null, "created_at": "2026-11-03T09:12:00+05:00" }, "created_at": "2026-11-03T09:12:00+05:00", "messages": [ { "id": 5521, "author": { "type": "customer", "id": 77, "uuid": null, "name": "Marat" }, "type": "text", "text": "Hello! I left my umbrella at Abay Ave yesterday.", "file": null, "created_at": "2026-11-03T09:12:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/feedback/reviews": { "get": { "operationId": "feedbackReviewsList", "summary": "List guest reviews", "description": "Reviews of the locations where `reviews.view` applies, newest first, with stars and sentiment (`positive`, `neutral`, `negative`, `mixed`).", "tags": [ "Guest feedback" ], "x-mcp-tool": "feedback_reviews_list", "x-permissions": [ "reviews.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "date_from", "in": "query", "description": "Created from (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Created to (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "source", "in": "query", "description": "Review source: YandexMaps, TwoGis, TripAdvisor, DeliveryClub, GoogleMaps", "schema": { "type": "string", "maxLength": 64 } }, { "name": "stars_min", "in": "query", "description": "Minimum stars", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "stars_max", "in": "query", "description": "Maximum stars", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "sentiment", "in": "query", "description": "Overall sentiment", "schema": { "type": "string", "enum": [ "positive", "neutral", "negative", "mixed" ] } }, { "name": "search", "in": "query", "description": "Search in review text and author name", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "stars": { "type": "integer" }, "text": { "type": "string" }, "author_name": { "type": "string" }, "source": { "type": "string" }, "sentiment": { "type": "string" }, "sentiment_scores": { "type": "object", "properties": { "positive": { "type": "number" }, "neutral": { "type": "number" }, "negative": { "type": "number" } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 1683, "location": { "id": 12, "name": "Abay Ave" }, "stars": 2, "text": "Coffee was great but we waited 25 minutes for a table.", "author_name": "Olga V.", "source": "TwoGis", "sentiment": "mixed", "sentiment_scores": { "positive": 0.41, "neutral": 0.05, "negative": 0.54 }, "created_at": "2026-11-02T19:01:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/feedback/reviews/stats": { "get": { "operationId": "feedbackReviewsStats", "summary": "Get review statistics by location", "description": "Number of reviews, average stars and sentiment split per location for the period, plus the total.", "tags": [ "Guest feedback" ], "x-mcp-tool": "feedback_reviews_stats", "x-permissions": [ "reviews.view" ], "x-scope": "read", "parameters": [ { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "date_from", "in": "query", "description": "Created from (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Created to (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "source", "in": "query", "description": "Review source: YandexMaps, TwoGis, TripAdvisor, DeliveryClub, GoogleMaps", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "object", "properties": { "reviews": { "type": "integer" }, "avg_stars": { "type": "number" }, "positive": { "type": "integer" }, "neutral": { "type": "integer" }, "negative": { "type": "integer" }, "mixed": { "type": "integer" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "reviews": { "type": "integer" }, "avg_stars": { "type": "number" }, "positive": { "type": "integer" }, "neutral": { "type": "integer" }, "negative": { "type": "integer" }, "mixed": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "total": { "reviews": 132, "avg_stars": 4.3, "positive": 88, "neutral": 12, "negative": 21, "mixed": 11 }, "locations": [ { "location": { "id": 12, "name": "Abay Ave" }, "reviews": 70, "avg_stars": 4.5, "positive": 51, "neutral": 6, "negative": 8, "mixed": 5 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/feedback/reviews/{id}": { "get": { "operationId": "feedbackReviewsGet", "summary": "Retrieve a guest review", "description": "Review with sentence-level sentiment.", "tags": [ "Guest feedback" ], "x-mcp-tool": "feedback_reviews_get", "x-permissions": [ "reviews.view" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Review id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "stars": { "type": "integer" }, "text": { "type": "string" }, "author_name": { "type": "string" }, "source": { "type": "string" }, "sentiment": { "type": "string" }, "sentiment_scores": { "type": "object", "properties": { "positive": { "type": "number" }, "neutral": { "type": "number" }, "negative": { "type": "number" } } }, "created_at": { "type": "string", "format": "date-time" }, "sentences": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "sentiment": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 1683, "location": { "id": 12, "name": "Abay Ave" }, "stars": 2, "text": "Coffee was great but we waited 25 minutes for a table.", "author_name": "Olga V.", "source": "TwoGis", "sentiment": "mixed", "sentiment_scores": { "positive": 0.41, "neutral": 0.05, "negative": 0.54 }, "created_at": "2026-11-02T19:01:00+05:00", "sentences": [ { "text": "Coffee was great", "sentiment": "positive" }, { "text": "but we waited 25 minutes for a table.", "sentiment": "negative" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/deviations": { "get": { "operationId": "haccpDeviationsList", "summary": "List HACCP deviations", "description": "Deviations at the visible locations: reviews first, then newest. `status=open` (default) — all unresolved (stages `open`, `correcting`, `review`); `closed`; `all`. Use `stage` for an exact stage.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_deviations_list", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "all" ], "default": "open" } }, { "name": "stage", "in": "query", "description": "Exact stage", "schema": { "type": "string", "enum": [ "open", "correcting", "review", "closed" ] } }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "critical", "major", "minor" ] } }, { "name": "journal_id", "in": "query", "schema": { "type": "integer" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "overdue", "in": "query", "description": "Only unresolved deviations past their due time", "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "description": "Opened from (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Opened to (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "updated_since", "in": "query", "description": "Only deviations changed after this moment", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "severity": { "type": "string" }, "status": { "type": "string" }, "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 5120, "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "location": { "id": 4609, "name": "Abay Ave" }, "object": { "id": 301, "name": "Fridge #1" }, "severity": "major", "status": "correcting", "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "responsible": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "created_at": "2026-11-03T09:02:05+05:00", "closed_at": null, "updated_at": "2026-11-03T09:40:00+05:00", "url": "https://app.jecheck.io/ui/haccp/deviations?open=0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/deviations/{uuid}": { "get": { "operationId": "haccpDeviationsGet", "summary": "Retrieve a HACCP deviation", "description": "Deviation card: breached limits, the original entry and the re-check, corrective actions, required fields before submitting, the follow-up task and whether the token can work on / verify it.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_deviations_get", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Deviation UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "severity": { "type": "string" }, "status": { "type": "string" }, "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "correction": { "type": "string" }, "product_disposition": { "type": "string" }, "product_note": { "type": [ "string", "null" ] }, "root_cause": { "type": [ "string", "null" ] }, "preventive_action": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" } } }, "recheck": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" } } }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "closed_by": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "verify_note": { "type": [ "string", "null" ] }, "can_work": { "type": "boolean" }, "can_verify": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5120, "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "location": { "id": 4609, "name": "Abay Ave" }, "object": { "id": 301, "name": "Fridge #1" }, "severity": "major", "status": "correcting", "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "responsible": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "created_at": "2026-11-03T09:02:05+05:00", "closed_at": null, "updated_at": "2026-11-03T09:40:00+05:00", "url": "https://app.jecheck.io/ui/haccp/deviations?open=0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "correction": "Products moved to the backup fridge, door seal replaced", "product_disposition": "released", "product_note": null, "root_cause": null, "preventive_action": null, "photos": [ { "path": "haccp/761/photos/2026/11/c3d4.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/c3d4.jpg?X-Amz-Signature=…" } ], "required": [ "correction", "product_disposition" ], "entry": { "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "values": { "temperature": 8.4 }, "recorded_at": "2026-11-03T09:02:00+05:00", "comment": "Door was left open" }, "recheck": { "uuid": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b", "status": "ok", "values": { "temperature": 4.1 }, "recorded_at": "2026-11-03T11:00:00+05:00" }, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Fix the deviation: Storage temperature", "status": "in_progress" }, "closed_by": null, "verified_by": null, "verified_at": null, "verify_note": null, "can_work": true, "can_verify": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "haccpDeviationsUpdate", "summary": "Update corrective actions", "description": "Saves corrective actions as a draft (stage moves to `correcting`). Allowed to the responsible person or with `haccp.resolve` at the location; `responsible_user_id` — with `haccp.resolve` only.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_deviations_update", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Deviation UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "correction": { "type": [ "string", "null" ], "description": "What was done to fix it", "maxLength": 5000 }, "product_disposition": { "type": [ "string", "null" ], "enum": [ "released", "reworked", "destroyed", "returned", "quarantine", "not_applicable" ], "description": "What happened to the product" }, "product_note": { "type": [ "string", "null" ], "maxLength": 500 }, "root_cause": { "type": [ "string", "null" ], "description": "Root cause (required for critical deviations)", "maxLength": 5000 }, "preventive_action": { "type": [ "string", "null" ], "description": "Preventive action (required for critical deviations)", "maxLength": 5000 }, "photos": { "type": "array", "items": { "type": "string" }, "description": "Paths from `haccp.media.upload`", "maxItems": 10 }, "responsible_user_id": { "type": [ "integer", "null" ] } } }, "example": { "correction": "string", "product_disposition": "released", "product_note": "string", "root_cause": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "severity": { "type": "string" }, "status": { "type": "string" }, "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "correction": { "type": "string" }, "product_disposition": { "type": "string" }, "product_note": { "type": [ "string", "null" ] }, "root_cause": { "type": [ "string", "null" ] }, "preventive_action": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" } } }, "recheck": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" } } }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "closed_by": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "verify_note": { "type": [ "string", "null" ] }, "can_work": { "type": "boolean" }, "can_verify": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5120, "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "location": { "id": 4609, "name": "Abay Ave" }, "object": { "id": 301, "name": "Fridge #1" }, "severity": "major", "status": "correcting", "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "responsible": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "created_at": "2026-11-03T09:02:05+05:00", "closed_at": null, "updated_at": "2026-11-03T09:40:00+05:00", "url": "https://app.jecheck.io/ui/haccp/deviations?open=0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "correction": "Products moved to the backup fridge, door seal replaced", "product_disposition": "released", "product_note": null, "root_cause": null, "preventive_action": null, "photos": [ { "path": "haccp/761/photos/2026/11/c3d4.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/c3d4.jpg?X-Amz-Signature=…" } ], "required": [ "correction", "product_disposition" ], "entry": { "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "values": { "temperature": 8.4 }, "recorded_at": "2026-11-03T09:02:00+05:00", "comment": "Door was left open" }, "recheck": { "uuid": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b", "status": "ok", "values": { "temperature": 4.1 }, "recorded_at": "2026-11-03T11:00:00+05:00" }, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Fix the deviation: Storage temperature", "status": "in_progress" }, "closed_by": null, "verified_by": null, "verified_at": null, "verify_note": null, "can_work": true, "can_verify": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/deviations/{uuid}/close": { "post": { "operationId": "haccpDeviationsClose", "summary": "Close a HACCP deviation", "description": "Verifies corrective actions and closes the deviation. Requires `haccp.resolve` at the location; critical deviations — `haccp.close_critical`.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_deviations_close", "x-permissions": [ "haccp.resolve", "haccp.close_critical" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Deviation UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Verification note", "maxLength": 2000 } } }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "severity": { "type": "string" }, "status": { "type": "string" }, "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "correction": { "type": "string" }, "product_disposition": { "type": "string" }, "product_note": { "type": [ "string", "null" ] }, "root_cause": { "type": [ "string", "null" ] }, "preventive_action": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" } } }, "recheck": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" } } }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "closed_by": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "verify_note": { "type": [ "string", "null" ] }, "can_work": { "type": "boolean" }, "can_verify": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5120, "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "location": { "id": 4609, "name": "Abay Ave" }, "object": { "id": 301, "name": "Fridge #1" }, "severity": "major", "status": "correcting", "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "responsible": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "created_at": "2026-11-03T09:02:05+05:00", "closed_at": null, "updated_at": "2026-11-03T09:40:00+05:00", "url": "https://app.jecheck.io/ui/haccp/deviations?open=0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "correction": "Products moved to the backup fridge, door seal replaced", "product_disposition": "released", "product_note": null, "root_cause": null, "preventive_action": null, "photos": [ { "path": "haccp/761/photos/2026/11/c3d4.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/c3d4.jpg?X-Amz-Signature=…" } ], "required": [ "correction", "product_disposition" ], "entry": { "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "values": { "temperature": 8.4 }, "recorded_at": "2026-11-03T09:02:00+05:00", "comment": "Door was left open" }, "recheck": { "uuid": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b", "status": "ok", "values": { "temperature": 4.1 }, "recorded_at": "2026-11-03T11:00:00+05:00" }, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Fix the deviation: Storage temperature", "status": "in_progress" }, "closed_by": null, "verified_by": null, "verified_at": null, "verify_note": null, "can_work": true, "can_verify": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/deviations/{uuid}/reject": { "post": { "operationId": "haccpDeviationsReject", "summary": "Return a HACCP deviation for rework", "description": "Returns a deviation in `review` back to correction with a note. Same permissions as closing.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_deviations_reject", "x-permissions": [ "haccp.resolve", "haccp.close_critical" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Deviation UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "note" ] }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "severity": { "type": "string" }, "status": { "type": "string" }, "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "correction": { "type": "string" }, "product_disposition": { "type": "string" }, "product_note": { "type": [ "string", "null" ] }, "root_cause": { "type": [ "string", "null" ] }, "preventive_action": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" } } }, "recheck": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" } } }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "closed_by": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "verify_note": { "type": [ "string", "null" ] }, "can_work": { "type": "boolean" }, "can_verify": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5120, "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "location": { "id": 4609, "name": "Abay Ave" }, "object": { "id": 301, "name": "Fridge #1" }, "severity": "major", "status": "correcting", "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "responsible": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "created_at": "2026-11-03T09:02:05+05:00", "closed_at": null, "updated_at": "2026-11-03T09:40:00+05:00", "url": "https://app.jecheck.io/ui/haccp/deviations?open=0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "correction": "Products moved to the backup fridge, door seal replaced", "product_disposition": "released", "product_note": null, "root_cause": null, "preventive_action": null, "photos": [ { "path": "haccp/761/photos/2026/11/c3d4.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/c3d4.jpg?X-Amz-Signature=…" } ], "required": [ "correction", "product_disposition" ], "entry": { "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "values": { "temperature": 8.4 }, "recorded_at": "2026-11-03T09:02:00+05:00", "comment": "Door was left open" }, "recheck": { "uuid": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b", "status": "ok", "values": { "temperature": 4.1 }, "recorded_at": "2026-11-03T11:00:00+05:00" }, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Fix the deviation: Storage temperature", "status": "in_progress" }, "closed_by": null, "verified_by": null, "verified_at": null, "verify_note": null, "can_work": true, "can_verify": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/deviations/{uuid}/submit": { "post": { "operationId": "haccpDeviationsSubmit", "summary": "Submit corrective actions for review", "description": "Sends the deviation to review when the required fields are filled. If the token itself may close it (`haccp.resolve`, or `haccp.close_critical` for critical ones), it is closed right away.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_deviations_submit", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Deviation UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "severity": { "type": "string" }, "status": { "type": "string" }, "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "correction": { "type": "string" }, "product_disposition": { "type": "string" }, "product_note": { "type": [ "string", "null" ] }, "root_cause": { "type": [ "string", "null" ] }, "preventive_action": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" } } }, "recheck": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" } } }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "closed_by": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "verify_note": { "type": [ "string", "null" ] }, "can_work": { "type": "boolean" }, "can_verify": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5120, "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "location": { "id": 4609, "name": "Abay Ave" }, "object": { "id": 301, "name": "Fridge #1" }, "severity": "major", "status": "correcting", "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "responsible": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "created_at": "2026-11-03T09:02:05+05:00", "closed_at": null, "updated_at": "2026-11-03T09:40:00+05:00", "url": "https://app.jecheck.io/ui/haccp/deviations?open=0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "correction": "Products moved to the backup fridge, door seal replaced", "product_disposition": "released", "product_note": null, "root_cause": null, "preventive_action": null, "photos": [ { "path": "haccp/761/photos/2026/11/c3d4.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/c3d4.jpg?X-Amz-Signature=…" } ], "required": [ "correction", "product_disposition" ], "entry": { "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "values": { "temperature": 8.4 }, "recorded_at": "2026-11-03T09:02:00+05:00", "comment": "Door was left open" }, "recheck": { "uuid": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b", "status": "ok", "values": { "temperature": 4.1 }, "recorded_at": "2026-11-03T11:00:00+05:00" }, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Fix the deviation: Storage temperature", "status": "in_progress" }, "closed_by": null, "verified_by": null, "verified_at": null, "verify_note": null, "can_work": true, "can_verify": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/deviations/{uuid}/task": { "post": { "operationId": "haccpDeviationsTask", "summary": "Create a task for a HACCP deviation", "description": "Creates a task when the fix needs work (repair, deep cleaning). Assign to a user (`assignee_id`) or a team queue (`team_id`). Requires `haccp.resolve` at the location.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_deviations_task", "x-permissions": [ "haccp.resolve" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Deviation UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignee_id": { "type": "integer", "description": "Executor (user id)" }, "team_id": { "type": "integer", "description": "Team id instead of a user" }, "title": { "type": "string", "description": "Default: \"Fix the deviation: \"", "maxLength": 500 }, "description": { "type": "string", "maxLength": 5000 }, "due_at": { "type": "string", "format": "date-time", "description": "Default: +4 h for critical, +24 h otherwise" } } }, "example": { "assignee_id": 42, "team_id": 42, "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "severity": { "type": "string" }, "status": { "type": "string" }, "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "correction": { "type": "string" }, "product_disposition": { "type": "string" }, "product_note": { "type": [ "string", "null" ] }, "root_cause": { "type": [ "string", "null" ] }, "preventive_action": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": { "type": "array", "items": { "type": "string" } }, "entry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" } } }, "recheck": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "recorded_at": { "type": "string", "format": "date-time" } } }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "closed_by": { "type": [ "string", "null" ] }, "verified_by": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "verify_note": { "type": [ "string", "null" ] }, "can_work": { "type": "boolean" }, "can_verify": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 5120, "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "location": { "id": 4609, "name": "Abay Ave" }, "object": { "id": 301, "name": "Fridge #1" }, "severity": "major", "status": "correcting", "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "responsible": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "created_at": "2026-11-03T09:02:05+05:00", "closed_at": null, "updated_at": "2026-11-03T09:40:00+05:00", "url": "https://app.jecheck.io/ui/haccp/deviations?open=0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "correction": "Products moved to the backup fridge, door seal replaced", "product_disposition": "released", "product_note": null, "root_cause": null, "preventive_action": null, "photos": [ { "path": "haccp/761/photos/2026/11/c3d4.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/c3d4.jpg?X-Amz-Signature=…" } ], "required": [ "correction", "product_disposition" ], "entry": { "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "values": { "temperature": 8.4 }, "recorded_at": "2026-11-03T09:02:00+05:00", "comment": "Door was left open" }, "recheck": { "uuid": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b", "status": "ok", "values": { "temperature": 4.1 }, "recorded_at": "2026-11-03T11:00:00+05:00" }, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Fix the deviation: Storage temperature", "status": "in_progress" }, "closed_by": null, "verified_by": null, "verified_at": null, "verify_note": null, "can_work": true, "can_verify": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/entries": { "get": { "operationId": "haccpEntriesList", "summary": "List HACCP journal entries", "description": "Entries at the visible locations, newest first. Archived entries (past the retention period) are not returned; voided entries are included only with `voided=true`.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_entries_list", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "journal_id", "in": "query", "description": "Only this journal", "schema": { "type": "integer" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "object_id", "in": "query", "description": "Only this object (fridge, freezer, …)", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ok", "warning", "deviation" ] } }, { "name": "late", "in": "query", "description": "Only entries recorded late", "schema": { "type": "boolean" } }, { "name": "voided", "in": "query", "description": "`true` — only voided entries", "schema": { "type": "boolean" } }, { "name": "recorded_from", "in": "query", "description": "Measurement time from", "schema": { "type": "string", "format": "date-time" } }, { "name": "recorded_to", "in": "query", "description": "Measurement time to", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_since", "in": "query", "description": "Only entries changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal_id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object_id": { "type": "integer" }, "subject_user": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "flags": { "type": "object", "properties": { "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "warnings": { "type": "array" } } }, "late": { "type": "boolean" }, "late_reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "deviation_uuid": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "revision": { "type": "integer" }, "voided": { "type": "boolean" }, "void_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 88231, "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "journal_id": 14, "location": { "id": 4609, "name": "Abay Ave" }, "object_id": 301, "subject_user": null, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recorded_at": "2026-11-03T09:02:00+05:00", "values": { "temperature": 8.4 }, "status": "deviation", "flags": { "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "warnings": [] }, "late": false, "late_reason": null, "comment": "Door was left open", "photos": [ { "path": "haccp/761/photos/2026/11/a1b2.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/a1b2.jpg?X-Amz-Signature=…" } ], "deviation_uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "source": "app", "revision": 0, "voided": false, "void_reason": null, "updated_at": "2026-11-03T09:02:05+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/entries/{id}/revise": { "post": { "operationId": "haccpEntriesRevise", "summary": "Correct a HACCP journal entry", "description": "Corrects values of an entry with a reason; previous values stay in the revision history. Allowed to the author or with `haccp.resolve` at the location.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_entries_revise", "x-permissions": [ "haccp.fill", "haccp.resolve" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entry id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "properties": {}, "additionalProperties": true }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "values", "reason" ] }, "example": { "values": [], "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal_id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object_id": { "type": "integer" }, "subject_user": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "flags": { "type": "object", "properties": { "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "warnings": { "type": "array" } } }, "late": { "type": "boolean" }, "late_reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "deviation_uuid": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "revision": { "type": "integer" }, "voided": { "type": "boolean" }, "void_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 88231, "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "journal_id": 14, "location": { "id": 4609, "name": "Abay Ave" }, "object_id": 301, "subject_user": null, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recorded_at": "2026-11-03T09:02:00+05:00", "values": { "temperature": 8.4 }, "status": "deviation", "flags": { "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "warnings": [] }, "late": false, "late_reason": null, "comment": "Door was left open", "photos": [ { "path": "haccp/761/photos/2026/11/a1b2.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/a1b2.jpg?X-Amz-Signature=…" } ], "deviation_uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "source": "app", "revision": 0, "voided": false, "void_reason": null, "updated_at": "2026-11-03T09:02:05+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/entries/{id}/void": { "post": { "operationId": "haccpEntriesVoid", "summary": "Void a HACCP journal entry", "description": "Marks an entry as void with a reason (`haccp.resolve` at the location). The entry stays in the journal for the record.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_entries_void", "x-permissions": [ "haccp.resolve" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entry id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ] }, "example": { "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal_id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object_id": { "type": "integer" }, "subject_user": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "flags": { "type": "object", "properties": { "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "warnings": { "type": "array" } } }, "late": { "type": "boolean" }, "late_reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "deviation_uuid": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "revision": { "type": "integer" }, "voided": { "type": "boolean" }, "void_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 88231, "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "journal_id": 14, "location": { "id": 4609, "name": "Abay Ave" }, "object_id": 301, "subject_user": null, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recorded_at": "2026-11-03T09:02:00+05:00", "values": { "temperature": 8.4 }, "status": "deviation", "flags": { "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "warnings": [] }, "late": false, "late_reason": null, "comment": "Door was left open", "photos": [ { "path": "haccp/761/photos/2026/11/a1b2.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/a1b2.jpg?X-Amz-Signature=…" } ], "deviation_uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "source": "app", "revision": 0, "voided": false, "void_reason": null, "updated_at": "2026-11-03T09:02:05+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/equipment": { "get": { "operationId": "haccpEquipmentList", "summary": "List HACCP equipment", "description": "Controlled objects (fridges, freezers, thermometers, …) at the visible locations with limits, calibration dates and the last measurement.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_equipment_list", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "parameters": [ { "name": "location_id", "in": "query", "description": "Only this location", "schema": { "type": "integer" } }, { "name": "type", "in": "query", "description": "Object type key, e.g. `fridge`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "serial": { "type": "string" }, "limits": { "type": "object", "properties": { "temperature": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } } } }, "calibrated_at": { "type": [ "string", "null" ] }, "calibration_due_at": { "type": [ "string", "null" ] }, "calibration_overdue": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "last": { "type": "object", "properties": { "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 301, "location": { "id": 4609, "name": "Abay Ave" }, "type": "fridge", "type_label": "Fridge", "name": "Fridge #1", "serial": "LG-2231", "limits": { "temperature": { "min": 2, "max": 6 } }, "calibrated_at": null, "calibration_due_at": null, "calibration_overdue": false, "note": null, "active": true, "last": { "values": { "temperature": 4.1 }, "status": "ok", "recorded_at": "2026-11-03T11:00:00+05:00" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "haccpEquipmentCreate", "summary": "Add HACCP equipment", "description": "Adds a controlled object at a HACCP location. Without `limits` the country profile defaults for the type are used. Requires `haccp.registries`.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_equipment_create", "x-permissions": [ "haccp.registries" ], "x-plan-feature": "haccp", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer", "description": "HACCP location id" }, "type": { "type": "string", "description": "Object type key of the country profile (`fridge`, `freezer`, …); unknown — `other`", "maxLength": 60 }, "name": { "type": "string", "maxLength": 190 }, "serial": { "type": [ "string", "null" ], "maxLength": 120 }, "limits": { "type": "object", "properties": {}, "additionalProperties": true, "description": "`{\"temperature\": {\"min\": 2, \"max\": 6}, \"humidity\": {\"min\": 40, \"max\": 70}}`" }, "calibrated_at": { "type": [ "string", "null" ], "format": "date" }, "calibration_due_at": { "type": [ "string", "null" ], "format": "date" }, "note": { "type": [ "string", "null" ], "maxLength": 2000 }, "active": { "type": "boolean" } }, "required": [ "location_id", "name" ] }, "example": { "location_id": 12, "type": "string", "name": "Replace the broken fridge seal", "serial": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "serial": { "type": "string" }, "limits": { "type": "object", "properties": { "temperature": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } } } }, "calibrated_at": { "type": [ "string", "null" ] }, "calibration_due_at": { "type": [ "string", "null" ] }, "calibration_overdue": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "last": { "type": "object", "properties": { "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 301, "location": { "id": 4609, "name": "Abay Ave" }, "type": "fridge", "type_label": "Fridge", "name": "Fridge #1", "serial": "LG-2231", "limits": { "temperature": { "min": 2, "max": 6 } }, "calibrated_at": null, "calibration_due_at": null, "calibration_overdue": false, "note": null, "active": true, "last": { "values": { "temperature": 4.1 }, "status": "ok", "recorded_at": "2026-11-03T11:00:00+05:00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/equipment/{id}": { "patch": { "operationId": "haccpEquipmentUpdate", "summary": "Update HACCP equipment", "description": "Partial update of a controlled object. Requires `haccp.registries`.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_equipment_update", "x-permissions": [ "haccp.registries" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Object id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer", "description": "HACCP location id" }, "type": { "type": "string", "description": "Object type key of the country profile (`fridge`, `freezer`, …); unknown — `other`", "maxLength": 60 }, "name": { "type": "string", "maxLength": 190 }, "serial": { "type": [ "string", "null" ], "maxLength": 120 }, "limits": { "type": "object", "properties": {}, "additionalProperties": true, "description": "`{\"temperature\": {\"min\": 2, \"max\": 6}, \"humidity\": {\"min\": 40, \"max\": 70}}`" }, "calibrated_at": { "type": [ "string", "null" ], "format": "date" }, "calibration_due_at": { "type": [ "string", "null" ], "format": "date" }, "note": { "type": [ "string", "null" ], "maxLength": 2000 }, "active": { "type": "boolean" } } }, "example": { "location_id": 12, "type": "string", "name": "Replace the broken fridge seal", "serial": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "type_label": { "type": "string" }, "name": { "type": "string" }, "serial": { "type": "string" }, "limits": { "type": "object", "properties": { "temperature": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } } } }, "calibrated_at": { "type": [ "string", "null" ] }, "calibration_due_at": { "type": [ "string", "null" ] }, "calibration_overdue": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "last": { "type": "object", "properties": { "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 301, "location": { "id": 4609, "name": "Abay Ave" }, "type": "fridge", "type_label": "Fridge", "name": "Fridge #1", "serial": "LG-2231", "limits": { "temperature": { "min": 2, "max": 6 } }, "calibrated_at": null, "calibration_due_at": null, "calibration_overdue": false, "note": null, "active": true, "last": { "values": { "temperature": 4.1 }, "status": "ok", "recorded_at": "2026-11-03T11:00:00+05:00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "haccpEquipmentDelete", "summary": "Delete HACCP equipment", "description": "Removes a controlled object; its entries are kept. Requires `haccp.registries`.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_equipment_delete", "x-permissions": [ "haccp.registries" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Object id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/journals": { "get": { "operationId": "haccpJournalsList", "summary": "List HACCP journals", "description": "Journals of the company with their field structure and schedule.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_journals_list", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "parameters": [ { "name": "active", "in": "query", "description": "Only enabled (`true`) or disabled (`false`) journals", "schema": { "type": "boolean" } }, { "name": "location_id", "in": "query", "description": "Only journals kept at this location", "schema": { "type": "integer" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "monitoring", "prp", "receiving", "personnel", "cleaning", "other" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "subject": { "type": "string" }, "event_based": { "type": "boolean" }, "schedule": { "type": "object", "properties": { "type": { "type": "string" }, "times": { "type": "array", "items": { "type": "string" } } } }, "schedule_text": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "required": { "type": "boolean" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "object_types": { "type": "array", "items": { "type": "string" } }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "ccp_id": { "type": [ "string", "null" ] }, "requires_photo_on_deviation": { "type": "boolean" }, "template_key": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 14, "uuid": "4c3b2a1f-0e9d-4c8b-9a7f-6e5d4c3b2a1f", "title": "Storage temperature", "description": "Fridges and freezers, twice per shift", "category": "monitoring", "icon": "kitchen", "color": "#0e9aa7", "active": true, "subject": "object", "event_based": false, "schedule": { "type": "times", "times": [ "09:00", "17:00" ] }, "schedule_text": "Daily at 09:00, 17:00", "fields": [ { "key": "temperature", "label": "Temperature", "type": "temperature", "unit": "°C", "required": true, "min": 2, "max": 6 } ], "object_types": [ "fridge", "freezer" ], "location_ids": null, "position_ids": [], "ccp_id": null, "requires_photo_on_deviation": false, "template_key": "storage_temperature", "updated_at": "2026-10-20T10:00:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/journals/{id}": { "get": { "operationId": "haccpJournalsGet", "summary": "Retrieve a HACCP journal", "description": "Journal structure: fields (types, units, limits), schedule, subject (`site`, `object`, `employee`), object types, locations and positions, plus objects at the visible locations.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_journals_get", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Journal id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "subject": { "type": "string" }, "event_based": { "type": "boolean" }, "schedule": { "type": "object", "properties": { "type": { "type": "string" }, "times": { "type": "array", "items": { "type": "string" } } } }, "schedule_text": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "required": { "type": "boolean" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "object_types": { "type": "array", "items": { "type": "string" } }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "ccp_id": { "type": [ "string", "null" ] }, "requires_photo_on_deviation": { "type": "boolean" }, "template_key": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "objects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "limits": { "type": "object", "properties": { "temperature": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } } } }, "active": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 14, "uuid": "4c3b2a1f-0e9d-4c8b-9a7f-6e5d4c3b2a1f", "title": "Storage temperature", "description": "Fridges and freezers, twice per shift", "category": "monitoring", "icon": "kitchen", "color": "#0e9aa7", "active": true, "subject": "object", "event_based": false, "schedule": { "type": "times", "times": [ "09:00", "17:00" ] }, "schedule_text": "Daily at 09:00, 17:00", "fields": [ { "key": "temperature", "label": "Temperature", "type": "temperature", "unit": "°C", "required": true, "min": 2, "max": 6 } ], "object_types": [ "fridge", "freezer" ], "location_ids": null, "position_ids": [], "ccp_id": null, "requires_photo_on_deviation": false, "template_key": "storage_temperature", "updated_at": "2026-10-20T10:00:00+05:00", "objects": [ { "id": 301, "name": "Fridge #1", "type": "fridge", "location": { "id": 4609, "name": "Abay Ave" }, "limits": { "temperature": { "min": 2, "max": 6 } }, "active": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/journals/{id}/entries": { "post": { "operationId": "haccpEntriesCreate", "summary": "Record a HACCP journal entry", "description": "Records a measurement/check. Values are checked against the field and object limits: out of limits — the entry gets status `deviation` and a deviation is opened (notifications as in the app). Idempotent with `uuid`: repeating the same `uuid` returns the existing entry. With `deviation_id` — a re-check after correction.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_entries_create", "x-permissions": [ "haccp.fill" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Journal id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer", "description": "Location id" }, "values": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Field values by field `key`, e.g. `{\"temperature\": 4.2}`" }, "object_id": { "type": "integer", "description": "Object (journals with subject `object`)" }, "subject_user_id": { "type": "integer", "description": "Employee the entry is about (journals with subject `employee`, e.g. health check)" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Measurement time (device time for offline sync), default — now" }, "uuid": { "type": "string", "format": "uuid", "description": "Client-generated UUID for safe retries" }, "comment": { "type": "string", "maxLength": 2000 }, "photos": { "type": "array", "items": { "type": "string" }, "description": "Paths from `haccp.media.upload`", "maxItems": 10 }, "deviation_id": { "type": "integer", "description": "Re-check measurement for this deviation" }, "late_reason": { "type": "string", "description": "Why the entry is recorded later than the measurement", "maxLength": 255 }, "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [ "location_id", "values" ] }, "example": { "location_id": 12, "values": [], "object_id": 42, "subject_user_id": 42 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "journal_id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "object_id": { "type": "integer" }, "subject_user": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recorded_at": { "type": "string", "format": "date-time" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "flags": { "type": "object", "properties": { "breaches": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "warnings": { "type": "array" } } }, "late": { "type": "boolean" }, "late_reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "deviation_uuid": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "revision": { "type": "integer" }, "voided": { "type": "boolean" }, "void_reason": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 88231, "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "journal_id": 14, "location": { "id": 4609, "name": "Abay Ave" }, "object_id": 301, "subject_user": null, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recorded_at": "2026-11-03T09:02:00+05:00", "values": { "temperature": 8.4 }, "status": "deviation", "flags": { "breaches": [ { "key": "temperature", "label": "Temperature", "value": 8.4, "unit": "°C", "min": 2, "max": 6 } ], "warnings": [] }, "late": false, "late_reason": null, "comment": "Door was left open", "photos": [ { "path": "haccp/761/photos/2026/11/a1b2.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/a1b2.jpg?X-Amz-Signature=…" } ], "deviation_uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "source": "app", "revision": 0, "voided": false, "void_reason": null, "updated_at": "2026-11-03T09:02:05+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/media": { "post": { "operationId": "haccpMediaUpload", "summary": "Upload a HACCP photo or document", "description": "Uploads an image (jpg, png, webp, heic) or PDF and returns its `path` for `photos` of an entry or deviation, photo fields, staff documents and verification records.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_media_upload", "x-permissions": [ "haccp.view" ], "x-scope": "write", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File (multipart; in MCP — object with `name` and `content_base64`)" }, "folder": { "type": "string", "enum": [ "photos", "docs" ], "default": "photos" } }, "required": [ "file" ] } }, "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "File (multipart; in MCP — object with `name` and `content_base64`)" }, "folder": { "type": "string", "enum": [ "photos", "docs" ], "default": "photos" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "path": "haccp/761/photos/2026/11/a1b2.jpg", "url": "https://storage.example.com/haccp/761/photos/2026/11/a1b2.jpg?X-Amz-Signature=…" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/medical-books": { "get": { "operationId": "haccpMedicalList", "summary": "List staff medical books", "description": "Employees of locations where the token has the sensitive `haccp.medical` permission, with the latest document of each type (medical book, hygiene training, …) and its status (`valid`, `expiring`, `expired`, `missing`). Each call is written to the access log.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_medical_list", "x-permissions": [ "haccp.medical" ], "x-plan-feature": "haccp", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "string" }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "problems": { "type": "integer" }, "docs": { "type": "object", "properties": { "medical_book": { "type": "object", "properties": { "doc_id": { "type": "integer" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date" }, "status": { "type": "string" } } } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date" }, "issuer": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "file": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 311, "name": "Aigerim Sadykova", "position": "Cook", "location_ids": [ 4609 ], "problems": 0, "docs": { "medical_book": { "doc_id": 77, "number": "MB-1022", "issued_at": "2026-03-01", "expires_at": "2027-03-01", "status": "valid" } }, "history": [ { "id": 77, "type": "medical_book", "number": "MB-1022", "issued_at": "2026-03-01", "expires_at": "2027-03-01", "issuer": "City clinic #4", "note": null, "file": { "path": "haccp/761/docs/2026/03/mb.pdf", "url": "https://storage.example.com/haccp/761/docs/2026/03/mb.pdf?X-Amz-Signature=…" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "haccpMedicalCreate", "summary": "Add a staff medical document", "description": "Records a medical book / health document of an employee. Requires `haccp.registries` and `haccp.medical` for the employee's location. `expires_at` defaults from the document type validity.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_medical_create", "x-permissions": [ "haccp.registries" ], "x-plan-feature": "haccp", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "type": { "type": "string", "description": "Document type key of the country profile, e.g. `medical_book`", "maxLength": 60 }, "number": { "type": "string", "maxLength": 120 }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date" }, "issuer": { "type": "string", "maxLength": 255 }, "note": { "type": "string", "maxLength": 500 }, "file": { "type": "string", "description": "Scan path from `haccp.media.upload` (folder `docs`)" } }, "required": [ "user_id", "type" ] }, "example": { "user_id": 42, "type": "string", "number": "string", "issued_at": "2026-11-01" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "type": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date" }, "issuer": { "type": "string" }, "note": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "id": 77, "user_id": 311, "type": "medical_book", "number": "MB-1022", "issued_at": "2026-03-01", "expires_at": "2027-03-01", "issuer": "City clinic #4", "note": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/plans": { "get": { "operationId": "haccpPlansList", "summary": "List HACCP plans", "description": "HACCP plans with status, version, review date and completion of the 12 Codex steps.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_plans_list", "x-permissions": [ "haccp.plan" ], "x-plan-feature": "haccp", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "progress": { "type": "object", "properties": { "1": { "type": "boolean" }, "2": { "type": "boolean" }, "3": { "type": "boolean" }, "4": { "type": "boolean" }, "5": { "type": "boolean" }, "6": { "type": "boolean" }, "7": { "type": "boolean" }, "8": { "type": "boolean" }, "9": { "type": "boolean" }, "10": { "type": "boolean" }, "11": { "type": "boolean" }, "12": { "type": "boolean" } } }, "problems": { "type": "integer" }, "has_changes": { "type": "boolean" }, "counts": { "type": "object", "properties": { "steps": { "type": "integer" }, "hazards": { "type": "integer" }, "ccps": { "type": "integer" } } }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 3, "uuid": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "title": "Hot kitchen", "status": "approved", "version": 2, "review_due_at": "2027-05-01", "location_ids": [ 4609 ], "progress": { "1": true, "2": true, "3": true, "4": true, "5": true, "6": true, "7": true, "8": true, "9": true, "10": true, "11": false, "12": true }, "problems": 1, "has_changes": false, "counts": { "steps": 9, "hazards": 14, "ccps": 2 }, "updated_at": "2026-10-28T15:00:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/plans/{id}": { "get": { "operationId": "haccpPlansGet", "summary": "Retrieve a HACCP plan", "description": "Full plan by the 12 Codex steps: team, products, process flow steps, hazard analysis, critical control points with limits, monitoring and corrective actions; open problems per step.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_plans_get", "x-permissions": [ "haccp.plan" ], "x-plan-feature": "haccp", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Plan id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "scope": { "type": "string" }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "status": { "type": "string" }, "intended_use": { "type": "string" }, "consumer_groups": { "type": "array", "items": { "type": "string" } }, "prerequisites": { "type": "array" }, "flow_confirmed_at": { "type": "string", "format": "date" }, "flow_confirmed_by": { "type": "integer" }, "documentation": { "type": "object", "properties": { "records": { "type": "array" } } }, "validation": { "type": [ "string", "null" ] }, "risk_threshold": { "type": "integer" }, "version": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "updated_at": { "type": "string", "format": "date-time" }, "team": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string" }, "role": { "type": "string" }, "job_title": { "type": "string" }, "competence": { "type": "string" }, "responsibilities": { "type": "string" } } } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "group": { "type": "string" }, "composition": { "type": "string" }, "characteristics": { "type": [ "string", "null" ] }, "processing": { "type": "string" }, "packaging": { "type": [ "string", "null" ] }, "storage": { "type": "string" }, "shelf_life": { "type": "string" }, "distribution": { "type": [ "string", "null" ] }, "allergens": { "type": "array", "items": { "type": "string" } }, "labeling": { "type": [ "string", "null" ] }, "intended_use": { "type": [ "string", "null" ] } } } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "parameters": { "type": "string" }, "inputs": { "type": [ "string", "null" ] }, "outsourced": { "type": "boolean" }, "rework": { "type": "boolean" }, "analyzed": { "type": "boolean" }, "next": { "type": "array", "items": { "type": "integer" } }, "products": { "type": "array", "items": { "type": "integer" } }, "position": { "type": "integer" } } } }, "hazards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "likelihood": { "type": "integer" }, "severity": { "type": "integer" }, "significant": { "type": "boolean" }, "justification": { "type": [ "string", "null" ] }, "control_measures": { "type": "string" }, "decision": { "type": "object", "properties": { "q1": { "type": "boolean" } } }, "outcome": { "type": "string" } } } }, "ccps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "step_id": { "type": "integer" }, "hazard_id": { "type": "integer" }, "kind": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "limits": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "min": { "type": "integer" } } } }, "limits_justification": { "type": [ "string", "null" ] }, "monitoring_what": { "type": "string" }, "monitoring_how": { "type": "string" }, "monitoring_frequency": { "type": "string" }, "monitoring_positions": { "type": "array" }, "journal_id": { "type": "integer" }, "corrective_actions": { "type": "string" }, "corrective_positions": { "type": "array" }, "verification": { "type": "string" }, "verification_frequency": { "type": "string" }, "validation": { "type": [ "string", "null" ] }, "records": { "type": [ "string", "null" ] } } } }, "problems": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer" }, "message": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 3, "uuid": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "title": "Hot kitchen", "scope": "Hot dishes of the main menu", "location_ids": [ 4609 ], "status": "approved", "intended_use": "Served hot within 2 hours", "consumer_groups": [ "general" ], "prerequisites": [], "flow_confirmed_at": "2026-10-10", "flow_confirmed_by": 120, "documentation": { "records": [] }, "validation": null, "risk_threshold": 6, "version": 2, "review_due_at": "2027-05-01", "updated_at": "2026-10-28T15:00:00+05:00", "team": [ { "id": 1, "user_id": 120, "name": "Daniyar Omarov", "role": "leader", "job_title": "Chef", "competence": "HACCP course 2025", "responsibilities": "Plan owner" } ], "products": [ { "id": 4, "name": "Chicken soup", "group": "hot", "composition": "Chicken, vegetables", "characteristics": null, "processing": "Boiling", "packaging": null, "storage": "+2…+6 °C", "shelf_life": "24 h", "distribution": null, "allergens": [ "celery" ], "labeling": null, "intended_use": null } ], "steps": [ { "id": 21, "name": "Cooking", "type": "process", "description": null, "parameters": "≥ 75 °C in the core", "inputs": null, "outsourced": false, "rework": false, "analyzed": true, "next": [ 22 ], "products": [ 4 ], "position": 3 } ], "hazards": [ { "id": 51, "step_id": 21, "type": "biological", "name": "Salmonella survival", "source": "Raw chicken", "likelihood": 3, "severity": 3, "significant": true, "justification": null, "control_measures": "Core temperature control", "decision": { "q1": true }, "outcome": "ccp" } ], "ccps": [ { "id": 7, "step_id": 21, "hazard_id": 51, "kind": "ccp", "code": "CCP-1", "name": "Core temperature", "limits": [ { "field": "temperature", "min": 75 } ], "limits_justification": null, "monitoring_what": "Core temperature", "monitoring_how": "Probe thermometer", "monitoring_frequency": "Each batch", "monitoring_positions": [], "journal_id": 15, "corrective_actions": "Continue cooking", "corrective_positions": [], "verification": "Weekly journal review", "verification_frequency": "weekly", "validation": null, "records": null } ], "problems": [ { "step": 11, "message": "Describe verification procedures" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/settings": { "get": { "operationId": "haccpSettingsGet", "summary": "Get HACCP settings", "description": "Module settings: country profile of norms, timezone, shift start, HACCP leader, retention and grace periods, options and HACCP locations. Requires `haccp.settings`.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_settings_get", "x-permissions": [ "haccp.settings" ], "x-plan-feature": "haccp", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "profile": { "type": "string" }, "profile_name": { "type": "string" }, "timezone": { "type": "string" }, "shift_start": { "type": "string" }, "leader": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "retention_months": { "type": "integer" }, "grace_minutes": { "type": "integer" }, "options": { "type": "object", "properties": { "late_minutes": { "type": "integer" }, "expiry_warning_days": { "type": "integer" } } }, "onboarded_at": { "type": "string", "format": "date-time" }, "sites": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "kind": { "type": "string" }, "seats": { "type": "integer" }, "shift_start": { "type": [ "string", "null" ] }, "work_days": { "type": "array", "items": { "type": "integer" } }, "active": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "profile": "kz", "profile_name": "Kazakhstan", "timezone": "Asia/Almaty", "shift_start": "08:00", "leader": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "retention_months": 12, "grace_minutes": 30, "options": { "late_minutes": 60, "expiry_warning_days": 30 }, "onboarded_at": "2026-10-17T12:00:00+05:00", "sites": [ { "location": { "id": 4609, "name": "Abay Ave" }, "kind": "cafe", "seats": 40, "shift_start": null, "work_days": [ 1, 2, 3, 4, 5, 6, 7 ], "active": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/sites": { "get": { "operationId": "haccpSites", "summary": "List HACCP locations", "description": "HACCP status of the company (enabled, country profile, timezone) and the HACCP locations visible to the token.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_sites", "x-permissions": [ "haccp.view" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "profile": { "type": "string" }, "timezone": { "type": "string" }, "sites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "kind": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "enabled": true, "profile": "kz", "timezone": "Asia/Almaty", "sites": [ { "id": 4609, "name": "Abay Ave", "address": "10 Abay Ave", "kind": "cafe" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/slots/{id}/skip": { "post": { "operationId": "haccpSlotsSkip", "summary": "Skip a scheduled HACCP check", "description": "Marks a time slot as not required today (location closed, equipment off) with a reason. Requires `haccp.resolve` at the location.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_slots_skip", "x-permissions": [ "haccp.resolve" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Slot id from `haccp.today`", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "reason" ] }, "example": { "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "skipped": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "skipped": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/suppliers": { "get": { "operationId": "haccpSuppliersList", "summary": "List HACCP suppliers", "description": "Approved suppliers with their documents (certificates, declarations) and expiry status.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_suppliers_list", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "tax_id": { "type": "string" }, "contact": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "products": { "type": "string" }, "status": { "type": "string" }, "rating": { "type": "integer" }, "note": { "type": [ "string", "null" ] }, "evaluated_at": { "type": "string", "format": "date" }, "expired": { "type": "integer" }, "expiring": { "type": "integer" }, "docs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "number": { "type": "string" }, "product": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date" }, "status": { "type": "string" }, "file": { "type": [ "string", "null" ] } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 12, "name": "Fresh Farm LLP", "tax_id": "123456789012", "contact": "Arman", "phone": "+7 701 000 00 00", "email": "sales@freshfarm.kz", "products": "Poultry", "status": "approved", "rating": 5, "note": null, "evaluated_at": "2026-09-01", "expired": 0, "expiring": 1, "docs": [ { "id": 30, "type": "certificate", "number": "KZ-77", "product": "Chicken", "issued_at": "2026-01-10", "valid_until": "2026-11-20", "status": "expiring", "file": null } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/today": { "get": { "operationId": "haccpToday", "summary": "Get today's HACCP checks", "description": "What must be recorded today: journals with time slots (status `pending`, `overdue`, `done`, `late`, `missed`, `skipped`), objects with limits, today's entries, staff on shift and open deviations. Without `location_id` — all HACCP locations visible to the token.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_today", "x-permissions": [ "haccp.view" ], "x-scope": "read", "parameters": [ { "name": "location_id", "in": "query", "description": "One location; omitted — all visible locations", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "late_minutes": { "type": "integer" }, "sites": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "can_resolve": { "type": "boolean" }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "pending": { "type": "integer" }, "overdue": { "type": "integer" }, "deviations": { "type": "integer" } } }, "journals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "category": { "type": "string" }, "subject": { "type": "string" }, "event_based": { "type": "boolean" }, "schedule_text": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "required": { "type": "boolean" }, "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "can_fill": { "type": "boolean" }, "objects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "limits": { "type": "object", "properties": { "temperature": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } } } } } } }, "slots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "object_id": { "type": "integer" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "open": { "type": "boolean" }, "entry_id": { "type": "integer" }, "skip_reason": { "type": [ "string", "null" ] } } } }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "object_id": { "type": "integer" }, "subject_user": { "type": [ "string", "null" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "values": { "type": "object", "properties": { "temperature": { "type": "number" } } }, "status": { "type": "string" }, "late": { "type": "boolean" } } } }, "done": { "type": "integer" }, "pending": { "type": "integer" }, "total": { "type": "integer" } } } }, "staff": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "on_shift": { "type": "boolean" } } } }, "deviations": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "object_id": { "type": "integer" }, "severity": { "type": "string" }, "status": { "type": "string" }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "recheck": { "type": "boolean" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "day": "2026-11-03", "timezone": "Asia/Almaty", "late_minutes": 60, "sites": [ { "location": { "id": 4609, "name": "Abay Ave" }, "can_resolve": false, "summary": { "total": 9, "done": 4, "pending": 5, "overdue": 1, "deviations": 1 }, "journals": [ { "id": 14, "uuid": "4c3b2a1f-0e9d-4c8b-9a7f-6e5d4c3b2a1f", "title": "Storage temperature", "category": "monitoring", "subject": "object", "event_based": false, "schedule_text": "Daily at 09:00, 17:00", "fields": [ { "key": "temperature", "label": "Temperature", "type": "temperature", "unit": "°C", "required": true, "min": 2, "max": 6 } ], "can_fill": true, "objects": [ { "id": 301, "name": "Fridge #1", "type": "fridge", "type_label": "Fridge", "limits": { "temperature": { "min": 2, "max": 6 } } } ], "slots": [ { "id": 99120, "object_id": 301, "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "done", "open": true, "entry_id": 88231, "skip_reason": null } ], "entries": [ { "id": 88231, "uuid": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "object_id": 301, "subject_user": null, "recorded_at": "2026-11-03T09:02:00+05:00", "values": { "temperature": 8.4 }, "status": "deviation", "late": false } ], "done": 1, "pending": 1, "total": 2 } ], "staff": [ { "id": 311, "name": "Aigerim Sadykova", "on_shift": true } ], "deviations": [ { "uuid": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "journal": { "id": 14, "title": "Storage temperature" }, "object_id": 301, "severity": "major", "status": "open", "due_at": "2026-11-04T09:02:00+05:00", "overdue": false, "recheck": false } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/verifications": { "get": { "operationId": "haccpVerificationsList", "summary": "List HACCP verification activities", "description": "Scheduled verification activities (internal audits, lab tests, swabs, calibration) with next due date and the latest records.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_verifications_list", "x-permissions": [ "haccp.view" ], "x-plan-feature": "haccp", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "every_days": { "type": "integer" }, "next_due_at": { "type": "string", "format": "date" }, "last_done_at": { "type": "string", "format": "date" }, "responsible": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "plan_id": { "type": "integer" }, "active": { "type": "boolean" }, "overdue": { "type": "boolean" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "done_at": { "type": "string", "format": "date" }, "user": { "type": "string" }, "result": { "type": "string" }, "findings": { "type": [ "string", "null" ] }, "actions": { "type": [ "string", "null" ] }, "files": { "type": "array" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 5, "type": "internal_audit", "title": "Quarterly HACCP audit", "description": null, "every_days": 90, "next_due_at": "2026-12-01", "last_done_at": "2026-09-01", "responsible": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "plan_id": 3, "active": true, "overdue": false, "records": [ { "id": 41, "done_at": "2026-09-01", "user": "Daniyar Omarov", "result": "ok", "findings": null, "actions": null, "files": [] } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/haccp/verifications/{id}/records": { "post": { "operationId": "haccpVerificationsRecord", "summary": "Record a verification result", "description": "Records that a verification activity was done; the next due date moves by its interval. Findings are required when `result` is `issues`. Requires `haccp.registries`.", "tags": [ "HACCP" ], "x-mcp-tool": "haccp_verifications_record", "x-permissions": [ "haccp.registries" ], "x-plan-feature": "haccp", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Verification activity id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "done_at": { "type": "string", "format": "date", "description": "Default — today" }, "result": { "type": "string", "enum": [ "ok", "issues" ], "default": "ok" }, "findings": { "type": "string", "maxLength": 5000 }, "actions": { "type": "string", "maxLength": 5000 }, "files": { "type": "array", "items": { "type": "string" }, "description": "Paths from `haccp.media.upload`", "maxItems": 10 } } }, "example": { "done_at": "2026-11-01", "result": "ok", "findings": "string", "actions": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "verification_id": { "type": "integer" }, "done_at": { "type": "string", "format": "date" }, "result": { "type": "string" }, "findings": { "type": [ "string", "null" ] }, "actions": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "id": 42, "verification_id": 5, "done_at": "2026-11-03", "result": "ok", "findings": null, "actions": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/help/articles/{section}/{slug}": { "get": { "operationId": "helpArticle", "summary": "Read a help article", "description": "Full article in Markdown. `section` and `slug` come from `help.sections` or `help.search` results.", "tags": [ "Help center" ], "x-mcp-tool": "help_article", "x-scope": "read", "parameters": [ { "name": "section", "in": "path", "required": true, "description": "Section key, e.g. `tasks`", "schema": { "type": "string", "maxLength": 64 } }, { "name": "slug", "in": "path", "required": true, "description": "Article slug, e.g. `statuses`", "schema": { "type": "string", "maxLength": 128 } }, { "name": "locale", "in": "query", "description": "Language of the articles; falls back to English when the language has no articles", "schema": { "type": "string", "enum": [ "en", "ru", "kk", "uz", "ka", "hy", "sr", "de" ], "default": "en" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "section": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "updated": { "type": "string", "format": "date" }, "reading_time_minutes": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "markdown": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "section": "tasks", "slug": "statuses", "title": "Task statuses", "description": "What each task status means and who can move a task.", "updated": "2026-10-17", "reading_time_minutes": 3, "url": "https://jecheck.io/en/docs/tasks/statuses", "markdown": "Every task moves through statuses…\n\n## New\n\nThe task is created…" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/help/search": { "get": { "operationId": "helpSearch", "summary": "Search the help center", "description": "Hybrid keyword and semantic search over help articles. Returns the best matching fragments (at most two per article) with a link to the exact section of the article.", "tags": [ "Help center" ], "x-mcp-tool": "help_search", "x-scope": "read", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Question or keywords, e.g. \"how to require a photo after fixing a violation\"", "schema": { "type": "string", "minLength": 2, "maxLength": 500 } }, { "name": "limit", "in": "query", "description": "Number of fragments", "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 20 } }, { "name": "locale", "in": "query", "description": "Language of the articles; falls back to English when the language has no articles", "schema": { "type": "string", "enum": [ "en", "ru", "kk", "uz", "ka", "hy", "sr", "de" ], "default": "en" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "article": { "type": "string" }, "section": { "type": "string" }, "slug": { "type": "string" }, "heading": { "type": "string" }, "excerpt": { "type": "string" }, "content": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "score": { "type": "number" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "article": "Corrective-action loop", "section": "automation", "slug": "closed-loop", "heading": "Photo after the fix", "excerpt": "…turn on \"Photo after\" so the assignee must attach a photo before sending the task for review…", "content": "## Photo after the fix\n\nTurn on 'Photo after'…", "url": "https://jecheck.io/en/docs/automation/closed-loop#photo-after-the-fix", "score": 0.03226 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/help/sections": { "get": { "operationId": "helpSections", "summary": "List help sections and articles", "description": "The table of contents of the help center: sections in display order with their articles.", "tags": [ "Help center" ], "x-mcp-tool": "help_sections", "x-scope": "read", "parameters": [ { "name": "locale", "in": "query", "description": "Language of the articles; falls back to English when the language has no articles", "schema": { "type": "string", "enum": [ "en", "ru", "kk", "uz", "ka", "hy", "sr", "de" ], "default": "en" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "app_url": { "type": "string", "format": "uri" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "updated": { "type": "string", "format": "date" }, "reading_time_minutes": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "key": "tasks", "title": "Tasks", "app_url": "https://app.jecheck.io/ui/tasks", "articles": [ { "section": "tasks", "slug": "statuses", "title": "Task statuses", "description": "What each task status means and who can move a task.", "updated": "2026-10-17", "reading_time_minutes": 3, "url": "https://jecheck.io/en/docs/tasks/statuses" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/absences": { "get": { "operationId": "hrAbsencesList", "summary": "List absences", "description": "Vacations, sick leave and other absences of employees of the locations of `hr.absences` (the same records as in the shift schedule). Overlapping the period when `date_from`/`date_to` are given.", "tags": [ "HR" ], "x-mcp-tool": "hr_absences_list", "x-permissions": [ "hr.absences" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "date_from", "in": "query", "description": "Period start", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Period end", "schema": { "type": "string", "format": "date" } }, { "name": "status[]", "in": "query", "description": "pending, approved, rejected, cancelled (default — pending and approved)", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "type[]", "in": "query", "description": "Absence types: vacation, sick, day_off, unpaid, business_trip, study, maternity, truancy, other", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "user_id", "in": "query", "description": "Only this employee", "schema": { "type": "integer" } }, { "name": "location_ids[]", "in": "query", "description": "Only employees of these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "updated_since", "in": "query", "description": "Only records changed after this moment", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "hrAbsencesCreate", "summary": "Add an absence", "description": "Records a vacation, sick leave etc. for an employee — approved immediately (requires `hr.absences` and `schedule.requests` on the employee's locations). With `release_shifts` the employee's shifts on those days become open shifts.", "tags": [ "HR" ], "x-mcp-tool": "hr_absences_create", "x-permissions": [ "hr.absences" ], "x-scope": "write", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Employee" }, "type": { "type": "string", "enum": [ "vacation", "sick", "day_off", "unpaid", "business_trip", "study", "maternity", "truancy", "other" ] }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "paid": { "type": "boolean", "description": "Default — depends on the type" }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 }, "release_shifts": { "type": "boolean" }, "file": { "type": "string", "format": "binary", "description": "Sick note or order: PDF or image up to 10 MB" } }, "required": [ "user_id", "type", "date_from", "date_to" ] } }, "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Employee" }, "type": { "type": "string", "enum": [ "vacation", "sick", "day_off", "unpaid", "business_trip", "study", "maternity", "truancy", "other" ] }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "paid": { "type": "boolean", "description": "Default — depends on the type" }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 }, "release_shifts": { "type": "boolean" }, "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "Sick note or order: PDF or image up to 10 MB" } }, "required": [ "user_id", "type", "date_from", "date_to" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/absences/balances": { "get": { "operationId": "hrAbsencesBalances", "summary": "Get vacation balances", "description": "Annual vacation balance of each active employee of the locations of `hr.absences`: accrued since the hire date, used, planned, pending and available days.", "tags": [ "HR" ], "x-mcp-tool": "hr_absences_balances", "x-permissions": [ "hr.absences" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "location_ids[]", "in": "query", "description": "Only employees of these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "hired_at": { "type": "string", "format": "date" }, "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "hired_at": "2026-03-01", "per_year": 24, "accrued": 16.4, "adjust": 0, "used": 7, "planned": 14, "pending": 0, "balance": 9.4, "available": -4.6 } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/absences/{uuid}": { "patch": { "operationId": "hrAbsencesUpdate", "summary": "Update an absence", "tags": [ "HR" ], "x-mcp-tool": "hr_absences_update", "x-permissions": [ "hr.absences" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Absence UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vacation", "sick", "day_off", "unpaid", "business_trip", "study", "maternity", "truancy", "other" ] }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 }, "release_shifts": { "type": "boolean" }, "file": { "type": "string", "format": "binary" } } } }, "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vacation", "sick", "day_off", "unpaid", "business_trip", "study", "maternity", "truancy", "other" ] }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 }, "release_shifts": { "type": "boolean" }, "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/absences/{uuid}/cancel": { "post": { "operationId": "hrAbsencesCancel", "summary": "Cancel an absence", "tags": [ "HR" ], "x-mcp-tool": "hr_absences_cancel", "x-permissions": [ "hr.absences" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Absence UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/absences/{uuid}/decide": { "post": { "operationId": "hrAbsencesDecide", "summary": "Approve or reject an absence request", "description": "Decision on a pending request submitted by an employee; the employee is notified.", "tags": [ "HR" ], "x-mcp-tool": "hr_absences_decide", "x-permissions": [ "hr.absences" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Absence UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean" }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "release_shifts": { "type": "boolean", "description": "Open the employee's shifts on those days" } }, "required": [ "approve" ] }, "example": { "approve": true, "note": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "release_shifts": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/checklist-items/{id}": { "patch": { "operationId": "hrChecklistsItemsUpdate", "summary": "Update a checklist item", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_items_update", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "assignee_id": { "type": [ "integer", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "section_key": { "type": "string", "maxLength": 16 }, "requires": { "type": "string", "enum": [ "none", "comment", "file" ] } } }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "assignee_id": 42, "due_date": "2026-11-01" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "hrChecklistsItemsDelete", "summary": "Delete a checklist item", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_items_delete", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/checklist-items/{id}/status": { "post": { "operationId": "hrChecklistsItemsStatus", "summary": "Complete, skip or reopen a checklist item", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_items_status", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "complete", "skip", "reopen" ] }, "comment": { "type": [ "string", "null" ], "maxLength": 2000 }, "file": { "type": "string", "format": "binary", "description": "Attachment when completing (if the item requires a file)" } }, "required": [ "action" ] } }, "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "complete", "skip", "reopen" ] }, "comment": { "type": [ "string", "null" ], "maxLength": 2000 }, "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "Attachment when completing (if the item requires a file)" } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/checklists": { "get": { "operationId": "hrChecklistsList", "summary": "List onboarding and offboarding checklists", "description": "Active checklists and those finished in the last 90 days, for employees of the locations of `hr.hire`.", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_list", "x-permissions": [ "hr.hire" ], "x-scope": "read", "parameters": [ { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "onboarding", "offboarding" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "completed", "cancelled" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/checklists/{uuid}": { "get": { "operationId": "hrChecklistsGet", "summary": "Retrieve a checklist", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_get", "x-permissions": [ "hr.hire" ], "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Checklist UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/checklists/{uuid}/cancel": { "post": { "operationId": "hrChecklistsCancel", "summary": "Cancel a checklist", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_cancel", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Checklist UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/checklists/{uuid}/items": { "post": { "operationId": "hrChecklistsItemsCreate", "summary": "Add a checklist item", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_items_create", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Checklist UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "assignee_id": { "type": [ "integer", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "section_key": { "type": [ "string", "null" ], "maxLength": 16 }, "requires": { "type": "string", "enum": [ "none", "comment", "file" ], "description": "What is required to complete the item" }, "create_task": { "type": "boolean", "description": "Create a task for the assignee" } }, "required": [ "title" ] }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "assignee_id": 42, "due_date": "2026-11-01" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/checklists/{uuid}/reschedule": { "post": { "operationId": "hrChecklistsReschedule", "summary": "Move the start date of a checklist", "description": "Moves the first working day / last day; due dates of open items shift by the same number of days.", "tags": [ "HR" ], "x-mcp-tool": "hr_checklists_reschedule", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Checklist UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" } }, "required": [ "date" ] }, "example": { "date": "2026-11-01" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}": { "get": { "operationId": "hrEmployeesGet", "summary": "Retrieve an employee HR card", "description": "Work data, HR history, vacation balance, absences, documents and onboarding / offboarding checklists of an employee. Sections the token has no permission for are empty or `null` on the employee's locations: HR data — `hr.card`, personal data — `hr.personal`, documents — `hr.documents`, pay — `pay.rates.view`, contacts — `users.contacts`. Each view of sensitive data is written to the access log.", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_get", "x-permissions": [ "users.view" ], "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/cancel-dismissal": { "post": { "operationId": "hrEmployeesCancelDismissal", "summary": "Cancel a dismissal", "description": "The employee stays: dismissal dates and the offboarding checklist are removed, access is restored.", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_cancel_dismissal", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/checklists": { "post": { "operationId": "hrEmployeesChecklistsStart", "summary": "Start a checklist for an employee", "description": "Starts an onboarding or offboarding checklist from a template manually (tasks are created for the responsible people).", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_checklists_start", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "type": "integer" }, "date": { "type": "string", "format": "date", "description": "First working day / last day" } }, "required": [ "template_id", "date" ] }, "example": { "template_id": 42, "date": "2026-11-01" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/dismiss": { "post": { "operationId": "hrEmployeesDismiss", "summary": "Dismiss an employee", "description": "Registers the dismissal with the last working day and reason, cancels future absences and the active onboarding, starts the offboarding checklist. The account is closed the day after the last day (or now with `block_now`).", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_dismiss", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "last_day": { "type": "string", "format": "date" }, "reason": { "type": "string", "enum": [ "own", "agreement", "contract_end", "employer", "probation", "discipline", "relocation", "other" ] }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 }, "rehire": { "type": "boolean", "description": "Can be hired again, default true" }, "template_id": { "type": [ "integer", "null" ], "description": "Offboarding template; 0 — no checklist" }, "block_now": { "type": "boolean", "description": "Close the account immediately" } }, "required": [ "last_day", "reason" ] }, "example": { "last_day": "2026-11-01", "reason": "own", "comment": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "rehire": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/documents": { "get": { "operationId": "hrDocumentsList", "summary": "List HR documents of an employee", "description": "Contracts, orders, IDs, certificates (plus medical books from HACCP, read-only). Each view is written to the access log.", "tags": [ "HR" ], "x-mcp-tool": "hr_documents_list", "x-permissions": [ "hr.documents" ], "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "hrDocumentsCreate", "summary": "Add an HR document", "tags": [ "HR" ], "x-mcp-tool": "hr_documents_create", "x-permissions": [ "hr.documents" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contract", "addendum", "order", "id", "medical", "certificate", "diploma", "nda", "consent", "other" ] }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "number": { "type": [ "string", "null" ], "maxLength": 120 }, "issued_at": { "type": [ "string", "null" ], "format": "date" }, "expires_at": { "type": [ "string", "null" ], "format": "date" }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "file": { "type": "string", "format": "binary", "description": "Scan: PDF, image, Office or TXT, up to 20 MB" } }, "required": [ "type" ] } }, "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contract", "addendum", "order", "id", "medical", "certificate", "diploma", "nda", "consent", "other" ] }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "number": { "type": [ "string", "null" ], "maxLength": 120 }, "issued_at": { "type": [ "string", "null" ], "format": "date" }, "expires_at": { "type": [ "string", "null" ], "format": "date" }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "Scan: PDF, image, Office or TXT, up to 20 MB" } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/documents/{id}": { "patch": { "operationId": "hrDocumentsUpdate", "summary": "Update an HR document", "tags": [ "HR" ], "x-mcp-tool": "hr_documents_update", "x-permissions": [ "hr.documents" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Document id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contract", "addendum", "order", "id", "medical", "certificate", "diploma", "nda", "consent", "other" ] }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "number": { "type": [ "string", "null" ], "maxLength": 120 }, "issued_at": { "type": [ "string", "null" ], "format": "date" }, "expires_at": { "type": [ "string", "null" ], "format": "date" }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "file": { "type": "string", "format": "binary", "description": "Replace the scan" } } } }, "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contract", "addendum", "order", "id", "medical", "certificate", "diploma", "nda", "consent", "other" ] }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "number": { "type": [ "string", "null" ], "maxLength": 120 }, "issued_at": { "type": [ "string", "null" ], "format": "date" }, "expires_at": { "type": [ "string", "null" ], "format": "date" }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "Replace the scan" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "hrDocumentsDelete", "summary": "Delete an HR document", "tags": [ "HR" ], "x-mcp-tool": "hr_documents_delete", "x-permissions": [ "hr.documents" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Document id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/documents/{id}/file": { "get": { "operationId": "hrDocumentsDownload", "summary": "Download an HR document file", "description": "Returns the file itself (REST only, not available as an MCP tool). The download is written to the access log.", "tags": [ "HR" ], "x-permissions": [ "hr.documents" ], "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Document id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "file": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "file": "binary" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/notes": { "post": { "operationId": "hrEmployeesNotesCreate", "summary": "Add a note to the HR history", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_notes_create", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "comment": { "type": "string", "minLength": 1, "maxLength": 1000 }, "title": { "type": [ "string", "null" ], "maxLength": 120 } }, "required": [ "date", "comment" ] }, "example": { "date": "2026-11-01", "comment": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "title": "Replace the broken fridge seal" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "title": { "type": "string" } } }, "comment": { "type": "string" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 502, "type": "note", "date": "2026-11-03", "data": { "title": "Warning" }, "comment": "Late three times this month", "created_by": "Daniyar Omarov", "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/notes/{id}": { "delete": { "operationId": "hrEmployeesNotesDelete", "summary": "Delete a note from the HR history", "description": "Only notes can be deleted; hiring and dismissal are undone by their own operations.", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_notes_delete", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Event id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/profile": { "patch": { "operationId": "hrEmployeesProfileUpdate", "summary": "Update personal data", "description": "Partial update of the employee profile. Name and other fields require `users.edit`, phone — `users.contacts`, personal data (documents, addresses, tax id, bank, emergency contact, family, custom fields) — `hr.personal`, all on the employee's locations.", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_profile_update", "x-permissions": [ "users.view" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "First name (`users.edit`)", "minLength": 2, "maxLength": 255 }, "lastname": { "type": "string", "description": "Last name (`users.edit`)", "minLength": 2, "maxLength": 512 }, "phone": { "type": [ "string", "null" ], "description": "Phone (`users.contacts`)", "maxLength": 64 }, "middle_name": { "type": [ "string", "null" ], "maxLength": 120 }, "work_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "education": { "type": [ "string", "null" ], "maxLength": 500 }, "languages": { "type": [ "string", "null" ], "maxLength": 255 }, "clothing_size": { "type": [ "string", "null" ], "maxLength": 16 }, "shoe_size": { "type": [ "string", "null" ], "maxLength": 8 }, "note": { "type": [ "string", "null" ], "maxLength": 5000 }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female" ], "description": "Personal data (`hr.personal`)" }, "birth_date": { "type": [ "string", "null" ], "format": "date", "description": "Personal data (`hr.personal`)" }, "birth_place": { "type": [ "string", "null" ], "maxLength": 255 }, "citizenship": { "type": [ "string", "null" ], "maxLength": 120 }, "marital_status": { "type": [ "string", "null" ], "enum": [ "single", "married", "divorced", "widowed" ] }, "children": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30 }, "personal_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "personal_email": { "type": [ "string", "null" ], "maxLength": 255 }, "address_actual": { "type": [ "string", "null" ], "maxLength": 500 }, "address_registered": { "type": [ "string", "null" ], "maxLength": 500 }, "tax_id": { "type": [ "string", "null" ], "maxLength": 64 }, "insurance_no": { "type": [ "string", "null" ], "maxLength": 64 }, "id_doc_type": { "type": [ "string", "null" ], "enum": [ "id_card", "passport", "foreign", "residence" ] }, "id_doc_number": { "type": [ "string", "null" ], "maxLength": 64 }, "id_doc_issuer": { "type": [ "string", "null" ], "maxLength": 255 }, "id_doc_issued_at": { "type": [ "string", "null" ], "format": "date" }, "id_doc_expires_at": { "type": [ "string", "null" ], "format": "date" }, "emergency_name": { "type": [ "string", "null" ], "maxLength": 255 }, "emergency_relation": { "type": [ "string", "null" ], "maxLength": 64 }, "emergency_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "bank_name": { "type": [ "string", "null" ], "maxLength": 255 }, "bank_account": { "type": [ "string", "null" ], "maxLength": 64 }, "custom": { "type": [ "object", "null" ], "properties": {}, "additionalProperties": true, "description": "Company custom fields: {key: value} (see `hr.settings.get`)" } } }, "example": { "name": "Replace the broken fridge seal", "lastname": "string", "phone": "+77010000000", "middle_name": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/rehire": { "post": { "operationId": "hrEmployeesRehire", "summary": "Rehire a former employee", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_rehire", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "position_id": { "type": [ "integer", "null" ] }, "home_location_id": { "type": [ "integer", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "work_anywhere": { "type": "boolean" }, "manager_id": { "type": [ "integer", "null" ] }, "template_id": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "hired_at" ] }, "example": { "hired_at": "2026-11-01", "position_id": 42, "home_location_id": 12, "location_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/transfer": { "post": { "operationId": "hrEmployeesTransfer", "summary": "Transfer an employee", "description": "Changes position, locations or manager; the change is recorded in the HR history with the before/after values.", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_transfer", "x-permissions": [ "hr.hire" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Effective date" }, "position_id": { "type": [ "integer", "null" ] }, "home_location_id": { "type": [ "integer", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "work_anywhere": { "type": "boolean" }, "manager_id": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "date" ] }, "example": { "date": "2026-11-01", "position_id": 42, "home_location_id": 12, "location_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/employees/{uuid}/work": { "patch": { "operationId": "hrEmployeesWorkUpdate", "summary": "Update work data", "description": "Hire date, personnel number, employment type, probation, manager, contract, vacation entitlement (`hr.hire`) and pay (`pay.rates.edit`; a new rate with `rate_from` goes to the rate history used by payroll).", "tags": [ "HR" ], "x-mcp-tool": "hr_employees_work_update", "x-permissions": [ "hr.hire", "pay.rates.edit" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Employee UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "hired_at": { "type": [ "string", "null" ], "format": "date" }, "personnel_no": { "type": [ "string", "null" ], "maxLength": 32 }, "employment": { "type": [ "string", "null" ], "enum": [ "full", "part", "contract", "intern" ] }, "probation_until": { "type": [ "string", "null" ], "format": "date" }, "manager_id": { "type": [ "integer", "null" ], "description": "Line manager (user id)" }, "contract_type": { "type": [ "string", "null" ], "enum": [ "permanent", "fixed", "civil", "self" ] }, "contract_number": { "type": [ "string", "null" ], "maxLength": 64 }, "contract_date": { "type": [ "string", "null" ], "format": "date" }, "contract_until": { "type": [ "string", "null" ], "format": "date" }, "vacation_days": { "type": [ "integer", "null" ], "description": "Personal annual vacation days (null — company default)", "minimum": 0, "maximum": 120 }, "vacation_adjust": { "type": [ "number", "null" ], "description": "Manual vacation balance correction, days", "minimum": -365, "maximum": 365 }, "pay_type": { "type": "string", "enum": [ "hourly", "salary", "shift" ] }, "rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000 }, "rate_from": { "type": [ "string", "null" ], "format": "date", "description": "Rate effective from" }, "kpi_bonus": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100000000 }, "kpi_bonus_type": { "type": "string", "enum": [ "fixed", "percent" ] } } }, "example": { "hired_at": "2026-11-01", "personnel_no": "string", "employment": "full", "probation_until": "2026-11-01" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/hire": { "post": { "operationId": "hrHire", "summary": "Hire an employee", "description": "Creates the employee account (or hires an existing user by `uuid`), sets position, locations, manager and work data, and starts an onboarding checklist (`template_id`; default — the template for the position, 0 — none). Requires `hr.hire` and, for a new account, `users.create`; with a location-scoped `hr.hire` only your locations can be chosen.", "tags": [ "HR" ], "x-mcp-tool": "hr_hire", "x-permissions": [ "hr.hire" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Existing user of the company to hire (instead of creating a new account)" }, "name": { "type": "string", "description": "First name (new account)", "maxLength": 255 }, "lastname": { "type": "string", "description": "Last name (new account)", "maxLength": 512 }, "email": { "type": "string", "description": "Login email (new account)", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 64 }, "middle_name": { "type": [ "string", "null" ], "maxLength": 120 }, "gender": { "type": [ "string", "null" ], "enum": [ "male", "female" ] }, "birth_date": { "type": [ "string", "null" ], "format": "date" }, "personal_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "position_id": { "type": [ "integer", "null" ] }, "home_location_id": { "type": [ "integer", "null" ], "description": "Main location" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Additional locations" }, "work_anywhere": { "type": "boolean", "description": "Works at all locations (requires `hr.hire` for all locations)" }, "team_id": { "type": [ "integer", "null" ] }, "manager_id": { "type": [ "integer", "null" ] }, "hired_at": { "type": "string", "format": "date", "description": "First working day" }, "probation_until": { "type": [ "string", "null" ], "format": "date" }, "employment": { "type": [ "string", "null" ], "enum": [ "full", "part", "contract", "intern" ] }, "personnel_no": { "type": [ "string", "null" ], "maxLength": 32 }, "contract_type": { "type": [ "string", "null" ], "enum": [ "permanent", "fixed", "civil", "self" ] }, "contract_number": { "type": [ "string", "null" ], "maxLength": 64 }, "contract_until": { "type": [ "string", "null" ], "format": "date" }, "web_access": { "type": "boolean", "description": "Access to the web cabinet (requires `users.access`)" }, "role_ids": { "type": "array", "items": { "type": "integer" }, "description": "Access roles for the new account (only roles you may assign)" }, "invite": { "type": "string", "enum": [ "now", "start", "none" ], "description": "Send the invitation now, on the first working day or never (default `now`)" }, "template_id": { "type": [ "integer", "null" ], "description": "Onboarding checklist template; 0 — no checklist" }, "comment": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "hired_at" ] }, "example": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "name": "Replace the broken fridge seal", "lastname": "string", "email": "anna@example.com", "hired_at": "2026-11-01" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_admin": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ] }, "web_access": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" } } } }, "home_location_id": { "type": "integer" }, "work_anywhere": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "until": { "type": "string", "format": "date" }, "absence_type": { "type": [ "string", "null" ] }, "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "onboarding": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } } } }, "profile": { "type": "object", "properties": { "middle_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "birth_place": { "type": [ "string", "null" ] }, "citizenship": { "type": [ "string", "null" ] }, "marital_status": { "type": [ "string", "null" ] }, "children": { "type": [ "string", "null" ] }, "work_phone": { "type": [ "string", "null" ] }, "personal_phone": { "type": "string" }, "personal_email": { "type": [ "string", "null" ] }, "address_actual": { "type": [ "string", "null" ] }, "address_registered": { "type": [ "string", "null" ] }, "tax_id": { "type": [ "string", "null" ] }, "insurance_no": { "type": [ "string", "null" ] }, "id_doc_type": { "type": [ "string", "null" ] }, "id_doc_number": { "type": [ "string", "null" ] }, "id_doc_issuer": { "type": [ "string", "null" ] }, "id_doc_issued_at": { "type": [ "string", "null" ] }, "id_doc_expires_at": { "type": [ "string", "null" ] }, "emergency_name": { "type": [ "string", "null" ] }, "emergency_relation": { "type": [ "string", "null" ] }, "emergency_phone": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "education": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "clothing_size": { "type": [ "string", "null" ] }, "shoe_size": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "custom": { "type": "object" } } }, "work": { "type": "object", "properties": { "hired_at": { "type": "string", "format": "date" }, "fired_at": { "type": [ "string", "null" ] }, "personnel_no": { "type": "string" }, "employment": { "type": "string" }, "probation_until": { "type": "string", "format": "date" }, "contract_type": { "type": "string" }, "contract_number": { "type": "string" }, "contract_date": { "type": "string", "format": "date" }, "contract_until": { "type": [ "string", "null" ] }, "vacation_days": { "type": [ "string", "null" ] }, "vacation_adjust": { "type": "integer" }, "manager": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "team_managers": { "type": "array" }, "reports": { "type": "array" } } }, "pay": { "type": "object", "properties": { "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "kpi_bonus": { "type": [ "string", "null" ] }, "kpi_bonus_type": { "type": "string" }, "currency": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" } } } } } }, "vacation": { "type": "object", "properties": { "per_year": { "type": "integer" }, "accrued": { "type": "number" }, "adjust": { "type": "integer" }, "used": { "type": "integer" }, "planned": { "type": "integer" }, "pending": { "type": "integer" }, "balance": { "type": "number" }, "available": { "type": "number" } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "decided_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decided_at": { "type": "string", "format": "date-time" }, "has_file": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "format": "date" }, "data": { "type": "object", "properties": { "position": { "type": "string" } } }, "comment": { "type": [ "string", "null" ] }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } } } } } }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "overdue": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "overdue": { "type": "boolean" }, "status": { "type": "string" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "has_file": { "type": "boolean" }, "done_by": { "type": [ "string", "null" ] }, "done_at": { "type": [ "string", "null" ] }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] } } } }, "can": { "type": "object", "properties": { "contacts": { "type": "boolean" }, "edit": { "type": "boolean" }, "card": { "type": "boolean" }, "personal": { "type": "boolean" }, "documents": { "type": "boolean" }, "hire": { "type": "boolean" }, "absences": { "type": "boolean" }, "pay_view": { "type": "boolean" }, "pay_edit": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim", "lastname": "Sadykova", "email": "aigerim@example.com", "phone": "+7 701 111 22 33", "is_admin": false, "deleted": false, "deleted_at": null, "web_access": false, "position": { "id": 7, "name": "Barista" }, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home" } ], "home_location_id": 12, "work_anywhere": false, "teams": [ { "id": 3, "name": "Bar", "is_head": false } ], "created_at": "2026-03-01T09:00:00+05:00", "last_seen_at": "2026-11-03T08:12:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" }, "status": { "status": "probation", "until": "2026-12-01", "absence_type": null, "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "onboarding": { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "done": 3, "total": 9, "overdue": 1 } }, "profile": { "middle_name": "Nurlanovna", "gender": "female", "birth_date": "1998-04-12", "birth_place": null, "citizenship": null, "marital_status": null, "children": null, "work_phone": null, "personal_phone": "+7 701 000 00 00", "personal_email": null, "address_actual": null, "address_registered": null, "tax_id": null, "insurance_no": null, "id_doc_type": null, "id_doc_number": null, "id_doc_issuer": null, "id_doc_issued_at": null, "id_doc_expires_at": null, "emergency_name": null, "emergency_relation": null, "emergency_phone": null, "bank_name": null, "bank_account": null, "education": null, "languages": null, "clothing_size": null, "shoe_size": null, "note": null, "custom": {} }, "work": { "hired_at": "2026-09-01", "fired_at": null, "personnel_no": "0114", "employment": "full", "probation_until": "2026-12-01", "contract_type": "permanent", "contract_number": "TD-2026/114", "contract_date": "2026-09-01", "contract_until": null, "vacation_days": null, "vacation_adjust": 0, "manager": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "team_managers": [], "reports": [] }, "pay": { "pay_type": "hourly", "rate": 1500, "kpi_bonus": null, "kpi_bonus_type": "fixed", "currency": "KZT", "history": [ { "from": "2026-09-01", "pay_type": "hourly", "rate": 1500 } ] }, "vacation": { "per_year": 24, "accrued": 4.1, "adjust": 0, "used": 0, "planned": 0, "pending": 0, "balance": 4.1, "available": 4.1 }, "absences": [ { "uuid": "2b3c4d5e-6f70-4a81-92b3-c4d5e6f7a8b9", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "approved", "paid": true, "comment": null, "decision_note": null, "decided_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "decided_at": "2026-11-03T10:00:00+05:00", "has_file": false, "created_at": "2026-11-03T09:55:00+05:00" } ], "events": [ { "id": 501, "type": "hire", "date": "2026-09-01", "data": { "position": "Barista" }, "comment": null, "created_by": "Daniyar Omarov", "created_at": "2026-08-28T10:00:00+05:00" } ], "documents": [ { "id": 88, "type": "contract", "title": "Employment contract", "number": "TD-2026/114", "issued_at": "2026-03-01", "expires_at": null, "note": null, "source": "hr", "file": { "name": "contract.pdf", "download_url": "https://app.jecheck.io/api/ext/v1/hr/employees/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b/documents/88/file" } } ], "checklists": [ { "uuid": "4d5e6f70-8192-4a3b-8c4d-5e6f708192a3", "kind": "onboarding", "title": "Onboarding: Aigerim Sadykova", "start_date": "2026-11-04", "status": "active", "employee": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "sections": [ { "key": "s1", "title": "Before the first day" } ], "progress": { "done": 3, "total": 9, "overdue": 1 }, "items": [ { "id": 7001, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "due_date": "2026-11-03", "overdue": true, "status": "open", "requires": "none", "required": true, "comment": null, "has_file": false, "done_by": null, "done_at": null, "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "created_at": "2026-10-30T12:00:00+05:00", "completed_at": null } ], "can": { "contacts": true, "edit": true, "card": true, "personal": true, "documents": true, "hire": true, "absences": true, "pay_view": true, "pay_edit": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/settings": { "get": { "operationId": "hrSettingsGet", "summary": "Get HR settings", "description": "Company defaults: annual vacation days, probation months, closing the account on dismissal, custom profile fields.", "tags": [ "HR" ], "x-mcp-tool": "hr_settings_get", "x-permissions": [ "hr.card", "hr.onboarding" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "vacation_days": { "type": "integer" }, "probation_months": { "type": "integer" }, "block_on_dismissal": { "type": "boolean" }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "vacation_days": 24, "probation_months": 3, "block_on_dismissal": true, "custom_fields": [ { "key": "locker", "label": "Locker no.", "type": "text", "options": [] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "hrSettingsUpdate", "summary": "Update HR settings", "tags": [ "HR" ], "x-mcp-tool": "hr_settings_update", "x-permissions": [ "hr.onboarding" ], "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "vacation_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 120 }, "probation_months": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 12 }, "block_on_dismissal": { "type": "boolean" }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 24 }, "label": { "type": "string", "maxLength": 80 }, "type": { "type": "string", "enum": [ "text", "date", "number", "select" ] }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "label", "type" ] }, "description": "Replaces the custom field list", "maxItems": 30 } } }, "example": { "vacation_days": 42, "probation_months": 42, "block_on_dismissal": true, "custom_fields": [ { "key": "string", "label": "string", "type": "text" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "vacation_days": { "type": "integer" }, "probation_months": { "type": "integer" }, "block_on_dismissal": { "type": "boolean" }, "custom_fields": { "type": "array" } } } }, "required": [ "data" ] }, "example": { "data": { "vacation_days": 24, "probation_months": 3, "block_on_dismissal": true, "custom_fields": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/templates": { "get": { "operationId": "hrTemplatesList", "summary": "List checklist templates", "tags": [ "HR" ], "x-mcp-tool": "hr_templates_list", "x-permissions": [ "hr.hire", "hr.onboarding" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "position_ids": { "type": "array", "items": { "type": "integer" } }, "is_default": { "type": "boolean" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "items": { "type": "array" }, "items_count": { "type": "integer" }, "used": { "type": "integer" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 4, "kind": "onboarding", "name": "Barista onboarding", "description": null, "color": "#1f9d63", "position_ids": [ 7 ], "is_default": true, "sections": [ { "key": "s1", "title": "Before the first day" } ], "items": [], "items_count": 9, "used": 14 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "hrTemplatesCreate", "summary": "Create a checklist template", "description": "Sections are stages (\"Before the first day\", \"First week\"…); items reference a section by `section_key`. Assignee types: `user` (assignee_id — user id), `position` (assignee_id — position id), `manager` (line manager), `location_manager`, `employee` (the employee themselves), `initiator` (who starts the checklist); `due_offset` — days from the start date (negative — before).", "tags": [ "HR" ], "x-mcp-tool": "hr_templates_create", "x-permissions": [ "hr.onboarding" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 160 }, "kind": { "type": "string", "enum": [ "onboarding", "offboarding" ] }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "color": { "type": [ "string", "null" ], "maxLength": 9 }, "position_ids": { "type": "array", "items": { "type": "integer" }, "description": "Used by default for these positions" }, "is_default": { "type": "boolean", "description": "Default template of its kind" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 16 }, "title": { "type": "string", "maxLength": 120 } }, "required": [ "key", "title" ] }, "minItems": 1, "maxItems": 20 }, "items": { "type": "array", "items": { "type": "object", "properties": { "section_key": { "type": "string", "maxLength": 16 }, "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "assignee_type": { "type": "string", "enum": [ "user", "position", "manager", "location_manager", "employee", "initiator" ] }, "assignee_id": { "type": [ "integer", "null" ] }, "due_offset": { "type": "integer", "minimum": -365, "maximum": 365 }, "requires": { "type": "string", "enum": [ "none", "comment", "file" ] }, "required": { "type": "boolean" }, "create_task": { "type": "boolean" }, "position_ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "section_key", "title" ] }, "maxItems": 200 } }, "required": [ "name", "kind", "sections" ] }, "example": { "name": "Replace the broken fridge seal", "kind": "onboarding", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "color": "string", "sections": [ { "key": "string", "title": "Replace the broken fridge seal" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "position_ids": { "type": "array", "items": { "type": "integer" } }, "is_default": { "type": "boolean" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee_type": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_offset": { "type": "integer" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "create_task": { "type": "boolean" }, "position_ids": { "type": "array" } } } }, "items_count": { "type": "integer" }, "used": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 4, "kind": "onboarding", "name": "Barista onboarding", "description": null, "color": "#1f9d63", "position_ids": [ 7 ], "is_default": true, "sections": [ { "key": "s1", "title": "Before the first day" } ], "items": [ { "id": 31, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee_type": "location_manager", "assignee_id": null, "due_offset": -1, "requires": "none", "required": true, "create_task": true, "position_ids": [] } ], "items_count": 1, "used": 14 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/templates/{id}": { "get": { "operationId": "hrTemplatesGet", "summary": "Retrieve a checklist template", "tags": [ "HR" ], "x-mcp-tool": "hr_templates_get", "x-permissions": [ "hr.onboarding" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "position_ids": { "type": "array", "items": { "type": "integer" } }, "is_default": { "type": "boolean" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee_type": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_offset": { "type": "integer" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "create_task": { "type": "boolean" }, "position_ids": { "type": "array" } } } }, "items_count": { "type": "integer" }, "used": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 4, "kind": "onboarding", "name": "Barista onboarding", "description": null, "color": "#1f9d63", "position_ids": [ 7 ], "is_default": true, "sections": [ { "key": "s1", "title": "Before the first day" } ], "items": [ { "id": 31, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee_type": "location_manager", "assignee_id": null, "due_offset": -1, "requires": "none", "required": true, "create_task": true, "position_ids": [] } ], "items_count": 1, "used": 14 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "hrTemplatesUpdate", "summary": "Replace a checklist template", "description": "Saves the whole template (sections and all items). Running checklists keep their own copy of items.", "tags": [ "HR" ], "x-mcp-tool": "hr_templates_update", "x-permissions": [ "hr.onboarding" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 160 }, "kind": { "type": "string", "enum": [ "onboarding", "offboarding" ] }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "color": { "type": [ "string", "null" ], "maxLength": 9 }, "position_ids": { "type": "array", "items": { "type": "integer" }, "description": "Used by default for these positions" }, "is_default": { "type": "boolean", "description": "Default template of its kind" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 16 }, "title": { "type": "string", "maxLength": 120 } }, "required": [ "key", "title" ] }, "minItems": 1, "maxItems": 20 }, "items": { "type": "array", "items": { "type": "object", "properties": { "section_key": { "type": "string", "maxLength": 16 }, "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "assignee_type": { "type": "string", "enum": [ "user", "position", "manager", "location_manager", "employee", "initiator" ] }, "assignee_id": { "type": [ "integer", "null" ] }, "due_offset": { "type": "integer", "minimum": -365, "maximum": 365 }, "requires": { "type": "string", "enum": [ "none", "comment", "file" ] }, "required": { "type": "boolean" }, "create_task": { "type": "boolean" }, "position_ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "section_key", "title" ] }, "maxItems": 200 } }, "required": [ "name", "kind", "sections" ] }, "example": { "name": "Replace the broken fridge seal", "kind": "onboarding", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "color": "string", "sections": [ { "key": "string", "title": "Replace the broken fridge seal" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "position_ids": { "type": "array", "items": { "type": "integer" } }, "is_default": { "type": "boolean" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee_type": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_offset": { "type": "integer" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "create_task": { "type": "boolean" }, "position_ids": { "type": "array" } } } }, "items_count": { "type": "integer" }, "used": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 4, "kind": "onboarding", "name": "Barista onboarding", "description": null, "color": "#1f9d63", "position_ids": [ 7 ], "is_default": true, "sections": [ { "key": "s1", "title": "Before the first day" } ], "items": [ { "id": 31, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee_type": "location_manager", "assignee_id": null, "due_offset": -1, "requires": "none", "required": true, "create_task": true, "position_ids": [] } ], "items_count": 1, "used": 14 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "hrTemplatesDelete", "summary": "Delete a checklist template", "tags": [ "HR" ], "x-mcp-tool": "hr_templates_delete", "x-permissions": [ "hr.onboarding" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hr/templates/{id}/duplicate": { "post": { "operationId": "hrTemplatesDuplicate", "summary": "Duplicate a checklist template", "tags": [ "HR" ], "x-mcp-tool": "hr_templates_duplicate", "x-permissions": [ "hr.onboarding" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template id", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "position_ids": { "type": "array", "items": { "type": "integer" } }, "is_default": { "type": "boolean" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "assignee_type": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_offset": { "type": "integer" }, "requires": { "type": "string" }, "required": { "type": "boolean" }, "create_task": { "type": "boolean" }, "position_ids": { "type": "array" } } } }, "items_count": { "type": "integer" }, "used": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 4, "kind": "onboarding", "name": "Barista onboarding", "description": null, "color": "#1f9d63", "position_ids": [ 7 ], "is_default": true, "sections": [ { "key": "s1", "title": "Before the first day" } ], "items": [ { "id": 31, "section_key": "s1", "title": "Prepare a uniform", "description": null, "assignee_type": "location_manager", "assignee_id": null, "due_offset": -1, "requires": "none", "required": true, "create_task": true, "position_ids": [] } ], "items_count": 1, "used": 14 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions": { "get": { "operationId": "instructionsList", "summary": "List instructions", "description": "Instructions visible to the acting user, in library order. Readers get published documents; editors also get drafts and archived documents they can edit (filter with `status`). Read status (`viewed`, `acknowledged`, `needs_ack`) is for the acting user.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "folder_id", "in": "query", "description": "Only documents directly in this folder", "schema": { "type": "integer" } }, { "name": "root", "in": "query", "description": "Only documents in the library root (no folder)", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search in title, text, summary and tags", "schema": { "type": "string", "maxLength": 200 } }, { "name": "status[]", "in": "query", "description": "Filter by status: draft, published, archived", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "filter", "in": "query", "description": "`needs_ack` — waiting for the acting user's acknowledgement; `unread` — never opened by the acting user", "schema": { "type": "string", "enum": [ "needs_ack", "unread" ] } }, { "name": "tags[]", "in": "query", "description": "Only documents with any of these tags", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "updated_since", "in": "query", "description": "Only documents published (or, for editors, edited) after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "folder_id": { "type": "integer" }, "status": { "type": "string" }, "version": { "type": "integer" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "require_ack": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "words": { "type": "integer" }, "viewed": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "has_unpublished_changes": { "type": [ "string", "null" ] }, "can_edit": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "folder_id": 14, "status": "published", "version": 3, "published_at": "2026-10-28T09:12:00+05:00", "updated_at": "2026-10-28T09:12:00+05:00", "require_ack": true, "tags": [ "Barista", "Opening" ], "words": 412, "viewed": true, "acknowledged": false, "needs_ack": true, "has_unpublished_changes": null, "can_edit": false, "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "instructionsCreate", "summary": "Create an instruction", "description": "Creates a draft in a folder where the acting user can edit (the library root — knowledge-base managers only). Content is converted to the editor format; pass `publish=true` to publish the first version right away (employees are notified).", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_create", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title", "minLength": 1, "maxLength": 250 }, "content": { "type": "string", "description": "Body text", "maxLength": 500000 }, "content_format": { "type": "string", "enum": [ "markdown", "html", "text" ], "description": "Format of `content`, default `markdown`. HTML is sanitised to text formatting, headings, lists, tables, quotes, code and links; add images and files with the upload operation" }, "template": { "type": "string", "enum": [ "sop", "opening", "sanitation", "equipment" ], "description": "Start from a built-in template (ignored when `content` is passed)" }, "folder_id": { "type": [ "integer", "null" ], "description": "Folder id (null — library root, managers only). Moving requires edit rights on the target folder" }, "icon": { "type": [ "string", "null" ], "description": "Material Symbols icon name", "maxLength": 40 }, "summary": { "type": [ "string", "null" ], "description": "Short description shown in the list", "maxLength": 500 }, "require_ack": { "type": "boolean", "description": "Employees must confirm they have read each major version" }, "review_every_days": { "type": [ "integer", "null" ], "description": "Review period in days (null — no review reminders)", "minimum": 1, "maximum": 1095 }, "owner_id": { "type": [ "integer", "null" ], "description": "Responsible user id" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags (replace the current ones)", "maxItems": 20 }, "ai_visibility": { "type": "string", "enum": [ "inherit", "none", "staff", "client" ], "description": "Visibility for the external AI knowledge base (only when the AI knowledge base is enabled for the company; managers only)" }, "ai_note": { "type": [ "string", "null" ], "description": "Hint for the external AI (same conditions as `ai_visibility`)", "maxLength": 2000 }, "publish": { "type": "boolean", "description": "Publish the first version immediately" }, "change_note": { "type": "string", "description": "Version note when publishing", "maxLength": 490 } }, "required": [ "title" ] }, "example": { "title": "Replace the broken fridge seal", "content": "string", "content_format": "markdown", "template": "sop" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/badge": { "get": { "operationId": "instructionsBadge", "summary": "Get my reading counters", "description": "Counters for the acting user over the published instructions they can read: total, never opened, and waiting for acknowledgement.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_badge", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "integer" }, "unread": { "type": "integer" }, "needs_ack": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "total": 42, "unread": 5, "needs_ack": 2 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/by-ref/{ref}": { "get": { "operationId": "instructionsByRef", "summary": "Find an instruction by external reference", "description": "Resolves an external reference (for example `confluence:12345` for pages imported from Confluence) to the instruction UUID — use it to redirect old links.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_by_ref", "x-scope": "read", "parameters": [ { "name": "ref", "in": "path", "required": true, "description": "External reference, e.g. `confluence:12345`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/changes": { "get": { "operationId": "instructionsChanges", "summary": "List instruction changes", "description": "Change feed for mirrors and caches, oldest first: every document of the company changed after `updated_since`, with `state` = `active` (published and readable by the acting user) or `removed` (deleted, archived, unpublished or no longer visible). Store the last `updated_at` and pass it as `updated_since` next time.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_changes", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "updated_since", "in": "query", "description": "Only changes after this moment; omit for a full snapshot", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "state": { "type": "string" }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "state": "active", "version": 3, "updated_at": "2026-10-28T09:12:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/folders": { "get": { "operationId": "instructionsFoldersList", "summary": "List folders", "description": "Folder tree visible to the acting user with document counts (`count` — directly in the folder, `total` — with subfolders). Readers see only branches that contain readable documents.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_folders_list", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "parent_id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "total": { "type": "integer" }, "can_edit": { "type": "boolean" }, "restricted": { "type": "boolean" }, "children": { "type": "array" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 14, "parent_id": 3, "name": "Barista", "icon": "coffee", "color": null, "count": 6, "total": 6, "can_edit": false, "restricted": false, "children": [] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "instructionsFoldersCreate", "summary": "Create a folder", "description": "Creates a folder inside `parent_id` (requires edit rights on it) or in the root (knowledge-base managers only).", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_folders_create", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "parent_id": { "type": [ "integer", "null" ], "description": "Parent folder id" }, "icon": { "type": [ "string", "null" ], "description": "Material Symbols icon name", "maxLength": 40 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "parent_id": 42, "icon": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "parent_id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "total": { "type": "integer" }, "can_edit": { "type": "boolean" }, "restricted": { "type": "boolean" }, "children": { "type": "array" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 14, "parent_id": 3, "name": "Barista", "icon": "coffee", "color": null, "count": 6, "total": 6, "can_edit": false, "restricted": false, "children": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/folders/{id}": { "patch": { "operationId": "instructionsFoldersUpdate", "summary": "Update a folder", "description": "Rename, change the icon/colour or move the folder (`parent_id`; moving requires edit rights on both the old and the new parent).", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_folders_update", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Folder id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "parent_id": { "type": [ "integer", "null" ], "description": "New parent folder id (null — root)" }, "icon": { "type": [ "string", "null" ], "maxLength": 40 }, "color": { "type": [ "string", "null" ], "maxLength": 20 }, "ai_visibility": { "type": "string", "enum": [ "inherit", "none", "staff", "client" ], "description": "Visibility for the external AI knowledge base (managers of companies with the AI knowledge base only)" } } }, "example": { "name": "Replace the broken fridge seal", "parent_id": 42, "icon": "string", "color": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "parent_id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "total": { "type": "integer" }, "can_edit": { "type": "boolean" }, "restricted": { "type": "boolean" }, "children": { "type": "array" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 14, "parent_id": 3, "name": "Barista", "icon": "coffee", "color": null, "count": 6, "total": 6, "can_edit": false, "restricted": false, "children": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "instructionsFoldersDelete", "summary": "Delete a folder", "description": "Deletes the folder; its subfolders and documents move one level up and keep the folder's permissions.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_folders_delete", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Folder id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/folders/{id}/access": { "get": { "operationId": "instructionsFoldersAccessGet", "summary": "Get folder permissions", "description": "Who can view and edit the folder (inherited by its documents and subfolders). Requires edit rights on the folder.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_folders_access_get", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Folder id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "view": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "edit": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "restricted_by": { "type": "array" }, "inherited_edit": { "type": "object", "properties": { "folder": { "type": [ "string", "null" ] }, "subjects": { "type": "array" } } } } } }, "required": [ "data" ] }, "example": { "data": { "view": [ { "type": "position", "id": 7, "name": "Barista" }, { "type": "department", "id": 12, "name": "Abay Ave" } ], "edit": [ { "type": "user", "id": 120, "name": "Daniyar Omarov" } ], "restricted_by": [], "inherited_edit": { "folder": null, "subjects": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "instructionsFoldersAccessUpdate", "summary": "Set folder permissions", "description": "Replaces the view and/or edit lists of the folder. Same subjects and self-protection rules as for documents.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_folders_access_update", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Folder id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "view": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "position", "department", "team" ], "description": "Subject type" }, "id": { "type": "integer", "description": "User, position, location or team id" } }, "required": [ "type", "id" ] }, "description": "Who can view. Empty array — everyone who sees the parent folder; omit to keep unchanged", "maxItems": 500 }, "edit": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "position", "department", "team" ], "description": "Subject type" }, "id": { "type": "integer", "description": "User, position, location or team id" } }, "required": [ "type", "id" ] }, "description": "Who can edit. Empty array — inherit editors from the folder; omit to keep unchanged", "maxItems": 500 } } }, "example": { "view": [ { "type": "user", "id": 42 } ], "edit": [ { "type": "user", "id": 42 } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "view": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "edit": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "restricted_by": { "type": "array" }, "inherited_edit": { "type": "object", "properties": { "folder": { "type": [ "string", "null" ] }, "subjects": { "type": "array" } } } } } }, "required": [ "data" ] }, "example": { "data": { "view": [ { "type": "position", "id": 7, "name": "Barista" }, { "type": "department", "id": 12, "name": "Abay Ave" } ], "edit": [ { "type": "user", "id": 120, "name": "Daniyar Omarov" } ], "restricted_by": [], "inherited_edit": { "folder": null, "subjects": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/search": { "get": { "operationId": "instructionsSearch", "summary": "Search instructions", "description": "Full-text search over the instructions visible to the acting user (readers — published text; editors — also working titles). Returns up to `limit` matches with a text snippet. Legacy AI-bot keys keep the previous behaviour of this endpoint (see the instructions external API guide).", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_search", "x-scope": "read", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "folder_id", "in": "query", "description": "Only documents in this folder and its subfolders", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "status": { "type": "string" }, "folder_id": { "type": "integer" }, "snippet": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "status": "published", "folder_id": 14, "snippet": "…calibrate the grinder before the first espresso…", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/tree": { "get": { "operationId": "instructionsTree", "summary": "Get the library tree", "description": "The whole library in one call: the folder tree (with document counts and edit rights) and the list of documents visible to the acting user (see `instructions.list` for the item shape).", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_tree", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "parent_id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "total": { "type": "integer" }, "can_edit": { "type": "boolean" }, "restricted": { "type": "boolean" }, "children": { "type": "array" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "folder_id": { "type": "integer" }, "status": { "type": "string" }, "version": { "type": "integer" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "require_ack": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "words": { "type": "integer" }, "viewed": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "has_unpublished_changes": { "type": [ "string", "null" ] }, "can_edit": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } } } }, "can_create_in_root": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "folders": [ { "id": 14, "parent_id": 3, "name": "Barista", "icon": "coffee", "color": null, "count": 6, "total": 6, "can_edit": false, "restricted": false, "children": [] } ], "documents": [ { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "folder_id": 14, "status": "published", "version": 3, "published_at": "2026-10-28T09:12:00+05:00", "updated_at": "2026-10-28T09:12:00+05:00", "require_ack": true, "tags": [ "Barista", "Opening" ], "words": 412, "viewed": true, "acknowledged": false, "needs_ack": true, "has_unpublished_changes": null, "can_edit": false, "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } ], "can_create_in_root": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}": { "get": { "operationId": "instructionsGet", "summary": "Retrieve an instruction", "description": "The current published version of a document (or an older one with `version`) with its content in Markdown (default), HTML or plain text, the table of contents, attachments with download links and the acting user's acknowledgement status. Editors can request the unpublished draft with `draft=true`; a never-published document returns its draft. Pass `track=true` to count the call as a view by the acting user (as when the employee opens it in the app).", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "Format of `content`", "schema": { "type": "string", "enum": [ "markdown", "html", "text" ], "default": "markdown" } }, { "name": "version", "in": "query", "description": "Version number (default — current published version)", "schema": { "type": "integer", "minimum": 1 } }, { "name": "draft", "in": "query", "description": "Return the working draft (editors only)", "schema": { "type": "boolean" } }, { "name": "track", "in": "query", "description": "Record a view of the current version by the acting user", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "instructionsUpdate", "summary": "Update an instruction", "description": "Edits the working draft (`title`, `content`) and document settings. Changes to title or content are saved to the draft and become visible to readers only after `publish`; settings (folder, tags, review period, acknowledgement) apply immediately. Moving to another folder requires edit rights on it.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title (draft)", "minLength": 1, "maxLength": 250 }, "content": { "type": "string", "description": "New body text, replaces the draft content", "maxLength": 500000 }, "content_format": { "type": "string", "enum": [ "markdown", "html", "text" ], "description": "Format of `content`, default `markdown`. HTML is sanitised to text formatting, headings, lists, tables, quotes, code and links; add images and files with the upload operation" }, "folder_id": { "type": [ "integer", "null" ], "description": "Folder id (null — library root, managers only). Moving requires edit rights on the target folder" }, "icon": { "type": [ "string", "null" ], "description": "Material Symbols icon name", "maxLength": 40 }, "summary": { "type": [ "string", "null" ], "description": "Short description shown in the list", "maxLength": 500 }, "require_ack": { "type": "boolean", "description": "Employees must confirm they have read each major version" }, "review_every_days": { "type": [ "integer", "null" ], "description": "Review period in days (null — no review reminders)", "minimum": 1, "maximum": 1095 }, "owner_id": { "type": [ "integer", "null" ], "description": "Responsible user id" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags (replace the current ones)", "maxItems": 20 }, "ai_visibility": { "type": "string", "enum": [ "inherit", "none", "staff", "client" ], "description": "Visibility for the external AI knowledge base (only when the AI knowledge base is enabled for the company; managers only)" }, "ai_note": { "type": [ "string", "null" ], "description": "Hint for the external AI (same conditions as `ai_visibility`)", "maxLength": 2000 } } }, "example": { "title": "Replace the broken fridge seal", "content": "string", "content_format": "markdown", "folder_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "instructionsDelete", "summary": "Delete an instruction", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/access": { "get": { "operationId": "instructionsAccessGet", "summary": "Get instruction permissions", "description": "Who can view and who can edit the document, plus folders above that restrict viewing and the inherited editors. Editors of the document only.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_access_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "view": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "edit": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "restricted_by": { "type": "array" }, "inherited_edit": { "type": "object", "properties": { "folder": { "type": [ "string", "null" ] }, "subjects": { "type": "array" } } } } } }, "required": [ "data" ] }, "example": { "data": { "view": [ { "type": "position", "id": 7, "name": "Barista" }, { "type": "department", "id": 12, "name": "Abay Ave" } ], "edit": [ { "type": "user", "id": 120, "name": "Daniyar Omarov" } ], "restricted_by": [], "inherited_edit": { "folder": null, "subjects": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "instructionsAccessUpdate", "summary": "Set instruction permissions", "description": "Replaces the view and/or edit lists of the document. Subjects: `user`, `position`, `department` (location), `team`. If the change would remove the acting user's own edit rights, they are kept as an editor.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_access_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "view": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "position", "department", "team" ], "description": "Subject type" }, "id": { "type": "integer", "description": "User, position, location or team id" } }, "required": [ "type", "id" ] }, "description": "Who can view. Empty array — everyone who sees the parent folder; omit to keep unchanged", "maxItems": 500 }, "edit": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "position", "department", "team" ], "description": "Subject type" }, "id": { "type": "integer", "description": "User, position, location or team id" } }, "required": [ "type", "id" ] }, "description": "Who can edit. Empty array — inherit editors from the folder; omit to keep unchanged", "maxItems": 500 } } }, "example": { "view": [ { "type": "user", "id": 42 } ], "edit": [ { "type": "user", "id": 42 } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "view": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "edit": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "restricted_by": { "type": "array" }, "inherited_edit": { "type": "object", "properties": { "folder": { "type": [ "string", "null" ] }, "subjects": { "type": "array" } } } } } }, "required": [ "data" ] }, "example": { "data": { "view": [ { "type": "position", "id": 7, "name": "Barista" }, { "type": "department", "id": 12, "name": "Abay Ave" } ], "edit": [ { "type": "user", "id": 120, "name": "Daniyar Omarov" } ], "restricted_by": [], "inherited_edit": { "folder": null, "subjects": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/acknowledge": { "post": { "operationId": "instructionsAcknowledge", "summary": "Acknowledge an instruction", "description": "Records that the acting user has read the current version (\"I have read it\"). Required again after each major version when the document has `require_ack`.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_acknowledge", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "acknowledged": { "type": "boolean" }, "version": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "acknowledged": true, "version": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/acknowledgements": { "get": { "operationId": "instructionsAcknowledgements", "summary": "Get the acknowledgement report", "description": "Who in the audience of the document has opened and acknowledged the current major version. Editors of the document only.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_acknowledgements", "x-plan-feature": "instructions_pro", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "integer" }, "viewed": { "type": "integer" }, "acknowledged": { "type": "integer" }, "ack_rate": { "type": "integer" }, "ack_since_version": { "type": "integer" }, "users": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position": { "type": "string" }, "last_viewed_at": { "type": "string", "format": "date-time" }, "viewed_version": { "type": "integer" }, "acknowledged_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "total": 18, "viewed": 15, "acknowledged": 12, "ack_rate": 67, "ack_since_version": 3, "users": [ { "user": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "position": "Barista", "last_viewed_at": "2026-10-29T08:01:00+05:00", "viewed_version": 3, "acknowledged_at": "2026-10-29T08:03:00+05:00", "source": "app" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/archive": { "post": { "operationId": "instructionsArchive", "summary": "Archive or unarchive an instruction", "description": "Archived documents are hidden from readers. Pass `archived=false` to return a document from the archive.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_archive", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean", "description": "Default true" } } }, "example": { "archived": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/diff": { "get": { "operationId": "instructionsDiff", "summary": "Compare versions", "description": "Block-level comparison of two versions: `from` (0 — empty document) and `to` (default — current version; editors may pass `draft`). Each block is HTML with `op` = `added`, `removed` or `same`.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_diff", "x-plan-feature": "instructions_pro", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Version number to compare from (0 — empty)", "schema": { "type": "integer", "minimum": 0 } }, { "name": "to", "in": "query", "description": "Version number to compare to, or `draft` (editors only). Default — current version", "schema": { "type": "string", "maxLength": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "html": { "type": "string" } } } }, "added": { "type": "integer" }, "removed": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "from": 2, "to": "3", "blocks": [ { "op": "removed", "html": "

Grind size 12

" }, { "op": "added", "html": "

Grind size 10

" } ], "added": 1, "removed": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/discard": { "post": { "operationId": "instructionsDiscard", "summary": "Discard draft changes", "description": "Resets the draft to the current published version.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_discard", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/duplicate": { "post": { "operationId": "instructionsDuplicate", "summary": "Duplicate an instruction", "description": "Creates a draft copy in the same folder with the same settings and permissions.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_duplicate", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/files": { "get": { "operationId": "instructionsFilesList", "summary": "List instruction files", "description": "Images and attachments used in the current published version (editors: in the draft with `draft=true`) with download links.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_files_list", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "draft", "in": "query", "description": "Files of the working draft (editors only)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "instructionsFilesUpload", "summary": "Upload a file to an instruction", "description": "Uploads an image (JPEG, PNG, WebP, GIF up to 15 MB) or a file (PDF, Office, TXT, CSV, ZIP, MP4, MOV up to 50 MB) and, by default, appends it to the end of the draft as an image or attachment block. Publish to show it to readers.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_files_upload", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "append": { "type": "boolean", "description": "Append to the end of the draft, default true" } }, "required": [ "file" ] } }, "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } } }, "append": { "type": "boolean", "description": "Append to the end of the draft, default true" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/publish": { "post": { "operationId": "instructionsPublish", "summary": "Publish an instruction", "description": "Publishes the draft as a new version. A major version (default) requires a new acknowledgement and notifies employees; a minor one notifies only when `notify=true`.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_publish", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_note": { "type": "string", "description": "What changed", "maxLength": 490 }, "is_major": { "type": "boolean", "description": "Major version, default true" }, "notify": { "type": "boolean", "description": "Notify employees (default — only for a major version)" } } }, "example": { "change_note": "string", "is_major": true, "notify": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/remind": { "post": { "operationId": "instructionsRemind", "summary": "Remind employees to read an instruction", "description": "Sends a push / in-app notification to everyone in the audience who has not acknowledged the current version yet.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_remind", "x-plan-feature": "instructions_pro", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reminded": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "reminded": 6 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/restore": { "post": { "operationId": "instructionsRestore", "summary": "Restore an old version to the draft", "description": "Copies an older version into the draft; publish it to make it current again.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_restore", "x-plan-feature": "instructions_pro", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "Version number to restore", "minimum": 1 } }, "required": [ "version" ] }, "example": { "version": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/reviewed": { "post": { "operationId": "instructionsReviewed", "summary": "Mark an instruction as reviewed", "description": "Confirms the document is still up to date without changes: the next review date moves one period ahead. Only for published documents with a review period.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_reviewed", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "icon": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string" }, "folder": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "folder_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "integer" }, "is_latest": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "versions_count": { "type": "integer" }, "format": { "type": "string" }, "content": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "level": { "type": "integer" } } } }, "words": { "type": "integer" }, "read_minutes": { "type": "integer" }, "require_ack": { "type": "boolean" }, "acknowledged": { "type": "boolean" }, "needs_ack": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "can_edit": { "type": "boolean" }, "has_unpublished_changes": { "type": "boolean" }, "review_every_days": { "type": "integer" }, "review_due_at": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "title": "Opening the coffee shop", "icon": "coffee", "summary": "Morning checklist for baristas", "status": "published", "folder": { "id": 14, "name": "Barista" }, "folder_path": [ { "id": 3, "name": "Operations" }, { "id": 14, "name": "Barista" } ], "tags": [ "Barista", "Opening" ], "version": 3, "is_latest": true, "is_draft": false, "published_at": "2026-10-28T09:12:00+05:00", "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "change_note": "New grinder settings", "is_major": true, "versions_count": 3, "format": "markdown", "content": "## Before opening\n\n1. Turn on the espresso machine\n2. Calibrate the grinder\n\n> **Important:** check fridge temperatures.", "toc": [ { "id": "before-opening", "text": "Before opening", "level": 2 } ], "words": 412, "read_minutes": 3, "require_ack": true, "acknowledged": false, "needs_ack": true, "attachments": [ { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "kind": "file", "name": "Cleaning schedule.pdf", "mime": "application/pdf", "size": 182044, "width": null, "height": null, "url": "https://files.jecheck.io/instructions/761/2026/11/0c1d2e3f.pdf" } ], "can_edit": true, "has_unpublished_changes": false, "review_every_days": 180, "review_due_at": "2027-04-26", "owner": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "updated_at": "2026-10-28T09:12:00+05:00", "url": "https://app.jecheck.io/ui/instructions/5d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/instructions/{uuid}/versions": { "get": { "operationId": "instructionsVersions", "summary": "List versions of an instruction", "description": "Published versions, newest first. Read an older version with `GET /instructions/{uuid}?version=N`.", "tags": [ "Instructions" ], "x-mcp-tool": "instructions_versions", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Instruction UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "title": { "type": "string" }, "change_note": { "type": "string" }, "is_major": { "type": "boolean" }, "words": { "type": "integer" }, "published_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "published_at": { "type": "string", "format": "date-time" }, "is_latest": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "number": 3, "title": "Opening the coffee shop", "change_note": "New grinder settings", "is_major": true, "words": 412, "published_by": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "published_at": "2026-10-28T09:12:00+05:00", "is_latest": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/locations": { "get": { "operationId": "locationsList", "summary": "List locations", "description": "Locations the token can see, sorted by name. Administrators and holders of `locations.manage` / `locations.staff` see every location; other users see their own locations plus the locations where any of their permissions applies.", "tags": [ "Locations" ], "x-mcp-tool": "locations_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "region_id", "in": "query", "description": "Only locations of this region", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search in name and address", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "timezone": { "type": "string" }, "timezone_inherited": { "type": "boolean" }, "region": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 12, "name": "Abay Ave", "address": "Almaty, Abay Ave 52", "email": "abay@coffeelab.kz", "timezone": "Asia/Almaty", "timezone_inherited": true, "region": { "id": 3, "name": "Almaty" }, "managers": [ { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" } ], "created_at": "2024-03-02T09:15:00+05:00", "url": "https://app.jecheck.io/ui/locations" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "locationsCreate", "summary": "Create a location", "description": "Adds a location to the company. On the free plan the number of locations is limited — the call fails with `validation_failed` when the limit is reached.", "tags": [ "Locations" ], "x-mcp-tool": "locations_create", "x-permissions": [ "locations.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Location name", "minLength": 2, "maxLength": 255 }, "address": { "type": [ "string", "null" ], "description": "Street address", "maxLength": 500 }, "email": { "type": [ "string", "null" ], "description": "Contact email of the location", "maxLength": 128 }, "region_id": { "type": [ "integer", "null" ], "description": "Region id; `null` removes the location from its region" }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone, e.g. `Asia/Almaty`; `null` — same as the company", "maxLength": 64 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "address": "string", "email": "anna@example.com", "region_id": 42 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "timezone": { "type": "string" }, "timezone_inherited": { "type": "boolean" }, "region": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "region_managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "staff_count": { "type": "integer" }, "on_shift_now": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "name": "Abay Ave", "address": "Almaty, Abay Ave 52", "email": "abay@coffeelab.kz", "timezone": "Asia/Almaty", "timezone_inherited": true, "region": { "id": 3, "name": "Almaty" }, "managers": [ { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" } ], "created_at": "2024-03-02T09:15:00+05:00", "url": "https://app.jecheck.io/ui/locations", "region_managers": [ { "id": 98, "uuid": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "name": "Asel Nurlanova" } ], "teams": [ { "id": 4, "name": "Maintenance" } ], "staff_count": 14, "on_shift_now": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/locations/people/{user_id}/anywhere": { "put": { "operationId": "locationsAnywhereSet", "summary": "Allow an employee to work at any location", "description": "\"Can work at all locations\": the employee may be scheduled and audit at any location without being attached to it. It does not widen what data the employee sees. Written to the access log.", "tags": [ "Locations" ], "x-mcp-tool": "locations_anywhere_set", "x-permissions": [ "locations.staff" ], "x-scope": "write", "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "anywhere": { "type": "boolean" } }, "required": [ "anywhere" ] }, "example": { "anywhere": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "anywhere": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "anywhere": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/locations/regions": { "get": { "operationId": "locationsRegionsList", "summary": "List regions", "description": "Regions (groups of locations) with their managers. `locations` lists only the locations visible to the token.", "tags": [ "Locations" ], "x-mcp-tool": "locations_regions_list", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 3, "name": "Almaty", "color": "#2f6fed", "managers": [ { "id": 98, "uuid": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "name": "Asel Nurlanova" } ], "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "locationsRegionsCreate", "summary": "Create a region", "description": "Creates a region. Setting `manager_ids` additionally requires `locations.staff`.", "tags": [ "Locations" ], "x-mcp-tool": "locations_regions_create", "x-permissions": [ "locations.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Region name", "minLength": 1, "maxLength": 120 }, "color": { "type": [ "string", "null" ], "description": "Color, hex like `#2f6fed`", "maxLength": 9 }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Locations of the region", "maxItems": 1000 }, "manager_ids": { "type": "array", "items": { "type": "integer" }, "description": "Region managers (user ids); requires `locations.staff`", "maxItems": 50 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "color": "string", "location_ids": [ 12, 14 ], "manager_ids": [ 12, 14 ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 3, "name": "Almaty", "color": "#2f6fed", "managers": [ { "id": 98, "uuid": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "name": "Asel Nurlanova" } ], "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/locations/regions/{id}": { "patch": { "operationId": "locationsRegionsUpdate", "summary": "Update a region", "description": "Partial update. `location_ids` replaces the set of locations in the region; `manager_ids` replaces its managers (requires `locations.staff`).", "tags": [ "Locations" ], "x-mcp-tool": "locations_regions_update", "x-permissions": [ "locations.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Region id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Region name", "minLength": 1, "maxLength": 120 }, "color": { "type": [ "string", "null" ], "description": "Color, hex like `#2f6fed`", "maxLength": 9 }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Locations of the region", "maxItems": 1000 }, "manager_ids": { "type": "array", "items": { "type": "integer" }, "description": "Region managers (user ids); requires `locations.staff`", "maxItems": 50 } } }, "example": { "name": "Replace the broken fridge seal", "color": "string", "location_ids": [ 12, 14 ], "manager_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 3, "name": "Almaty", "color": "#2f6fed", "managers": [ { "id": 98, "uuid": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "name": "Asel Nurlanova" } ], "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "locationsRegionsDelete", "summary": "Delete a region", "description": "Deletes the region; its locations stay without a region.", "tags": [ "Locations" ], "x-mcp-tool": "locations_regions_delete", "x-permissions": [ "locations.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Region id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/locations/{id}": { "get": { "operationId": "locationsGet", "summary": "Retrieve a location", "description": "Location card: address, time zone, region, managers of the location and of its region, teams serving it. With `locations.manage` or `locations.staff` it also includes the staff count and who is on shift right now.", "tags": [ "Locations" ], "x-mcp-tool": "locations_get", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Location id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "timezone": { "type": "string" }, "timezone_inherited": { "type": "boolean" }, "region": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "region_managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "staff_count": { "type": "integer" }, "on_shift_now": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "name": "Abay Ave", "address": "Almaty, Abay Ave 52", "email": "abay@coffeelab.kz", "timezone": "Asia/Almaty", "timezone_inherited": true, "region": { "id": 3, "name": "Almaty" }, "managers": [ { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" } ], "created_at": "2024-03-02T09:15:00+05:00", "url": "https://app.jecheck.io/ui/locations", "region_managers": [ { "id": 98, "uuid": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "name": "Asel Nurlanova" } ], "teams": [ { "id": 4, "name": "Maintenance" } ], "staff_count": 14, "on_shift_now": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "locationsUpdate", "summary": "Update a location", "description": "Partial update: send only the fields to change.", "tags": [ "Locations" ], "x-mcp-tool": "locations_update", "x-permissions": [ "locations.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Location id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Location name", "minLength": 2, "maxLength": 255 }, "address": { "type": [ "string", "null" ], "description": "Street address", "maxLength": 500 }, "email": { "type": [ "string", "null" ], "description": "Contact email of the location", "maxLength": 128 }, "region_id": { "type": [ "integer", "null" ], "description": "Region id; `null` removes the location from its region" }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone, e.g. `Asia/Almaty`; `null` — same as the company", "maxLength": 64 } } }, "example": { "name": "Replace the broken fridge seal", "address": "string", "email": "anna@example.com", "region_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "timezone": { "type": "string" }, "timezone_inherited": { "type": "boolean" }, "region": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "region_managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "staff_count": { "type": "integer" }, "on_shift_now": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "name": "Abay Ave", "address": "Almaty, Abay Ave 52", "email": "abay@coffeelab.kz", "timezone": "Asia/Almaty", "timezone_inherited": true, "region": { "id": 3, "name": "Almaty" }, "managers": [ { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" } ], "created_at": "2024-03-02T09:15:00+05:00", "url": "https://app.jecheck.io/ui/locations", "region_managers": [ { "id": 98, "uuid": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "name": "Asel Nurlanova" } ], "teams": [ { "id": 4, "name": "Maintenance" } ], "staff_count": 14, "on_shift_now": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "locationsDelete", "summary": "Delete a location", "description": "Marks the location as deleted. Its history (audits, tasks) stays; it disappears from lists and filters.", "tags": [ "Locations" ], "x-mcp-tool": "locations_delete", "x-permissions": [ "locations.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Location id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/locations/{id}/managers": { "put": { "operationId": "locationsManagersSet", "summary": "Set location managers", "description": "Replaces the list of managers of the location. Managers get the permissions of the system role \"Location manager\" for this location. The change is written to the access log.", "tags": [ "Locations" ], "x-mcp-tool": "locations_managers_set", "x-permissions": [ "locations.staff" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Location id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "integer" }, "description": "Employee ids; empty array removes all managers", "maxItems": 50 } }, "required": [ "user_ids" ] }, "example": { "user_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "timezone": { "type": "string" }, "timezone_inherited": { "type": "boolean" }, "region": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "region_managers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "staff_count": { "type": "integer" }, "on_shift_now": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "name": "Abay Ave", "address": "Almaty, Abay Ave 52", "email": "abay@coffeelab.kz", "timezone": "Asia/Almaty", "timezone_inherited": true, "region": { "id": 3, "name": "Almaty" }, "managers": [ { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" } ], "created_at": "2024-03-02T09:15:00+05:00", "url": "https://app.jecheck.io/ui/locations", "region_managers": [ { "id": 98, "uuid": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "name": "Asel Nurlanova" } ], "teams": [ { "id": 4, "name": "Maintenance" } ], "staff_count": 14, "on_shift_now": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/locations/{id}/staff": { "get": { "operationId": "locationsStaffList", "summary": "List location staff", "description": "Employees attached to the location: `kind` is `home` (primary location) or `extra` (also works here); managers that are not attached have `kind: null`. `on_shift_now` — a published shift is running or the employee has clocked in.", "tags": [ "Locations" ], "x-mcp-tool": "locations_staff_list", "x-permissions": [ "locations.manage", "locations.staff" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Location id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "on_shift_now": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "kind": "home", "is_manager": false, "position": { "id": 5, "name": "Barista" }, "on_shift_now": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "locationsStaffSet", "summary": "Attach or detach employees", "description": "`kind: home` makes the location the primary one for these employees (their previous primary location becomes additional); `kind: extra` adds it as an additional location; `kind: null` removes them from the location (the manager flag is kept). Returns the updated staff list.", "tags": [ "Locations" ], "x-mcp-tool": "locations_staff_set", "x-permissions": [ "locations.staff" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Location id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "integer" }, "description": "Employee ids", "minItems": 1, "maxItems": 200 }, "kind": { "type": [ "string", "null" ], "enum": [ "home", "extra" ], "description": "`home`, `extra` or `null` to detach" } }, "required": [ "user_ids", "kind" ] }, "example": { "user_ids": [ 12, 14 ], "kind": "home" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "on_shift_now": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "kind": "home", "is_manager": false, "position": { "id": 5, "name": "Barista" }, "on_shift_now": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/me": { "get": { "operationId": "accountMe", "summary": "Get the current identity", "description": "Returns the user the token acts as (for a company key — its service user), the company, the token kind and scopes, and the list of permissions with the locations where each one applies (`null` — all locations).", "tags": [ "Account" ], "x-mcp-tool": "account_me", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_service": { "type": "boolean" }, "locale": { "type": "string" } } }, "company": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "plan": { "type": "string" } } }, "token": { "type": "object", "properties": { "kind": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ] } } }, "permissions": { "type": "object", "properties": { "analytics.view": { "type": [ "string", "null" ] }, "audits.view": { "type": "array", "items": { "type": "integer" } }, "tasks.view_all": { "type": [ "string", "null" ] } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "user": { "id": 1042, "uuid": "9b7c3f8e-2d1a-4b6e-9f00-1c2d3e4f5a6b", "name": "API: Data warehouse", "email": "api-7f3k@api.jecheck.io", "is_admin": false, "is_service": true, "locale": "en" }, "company": { "id": 761, "name": "Coffee Lab", "country": "KZ", "locale": "ru", "timezone": "Asia/Almaty", "plan": "enterprise" }, "token": { "kind": "key", "name": "Data warehouse", "prefix": "jck_live_a1B2c3", "scopes": [ "read", "write" ], "expires_at": null }, "permissions": { "analytics.view": null, "audits.view": [ 12, 14 ], "tasks.view_all": null }, "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/locations": { "get": { "operationId": "mysteryLocations", "summary": "Get mystery shopper scores by location", "description": "Accepted visits per location: count, average and last scores, trend of the last 8 visits.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_locations", "x-permissions": [ "mystery.view" ], "x-plan-feature": "mystery", "x-scope": "read", "parameters": [ { "name": "date_from", "in": "query", "description": "Submitted from", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Submitted to", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "visits": { "type": "integer" }, "avg": { "type": "number" }, "last": { "type": "number" }, "prev": { "type": "integer" }, "last_at": { "type": "string", "format": "date-time" }, "trend": { "type": "array", "items": { "type": "integer" } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "location": { "id": 12, "name": "Abay Ave" }, "visits": 6, "avg": 84.2, "last": 87.5, "prev": 80, "last_at": "2026-11-03T13:40:00+05:00", "trend": [ 78, 80, 87.5 ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/media/{id}": { "get": { "operationId": "mysteryMediaGet", "summary": "Download a private visit file", "description": "Audio / video recorded by the guest (REST only, not available as an MCP tool).", "tags": [ "Mystery shopper" ], "x-permissions": [ "mystery.view" ], "x-plan-feature": "mystery", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "File id from `files` of the visit", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "file": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "file": "binary" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders": { "get": { "operationId": "mysteryOrdersList", "summary": "List turnkey orders", "description": "Orders for mystery shopper checks performed by jeCheck guests, with progress of their visits. No plan feature is needed — the service is paid per order.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_list", "x-permissions": [ "mystery.orders" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "business_type": { "type": "string" }, "scenarios": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string" }, "checklist_id": { "type": "integer" }, "needs_questionnaire": { "type": "boolean" }, "questionnaire_brief": { "type": [ "string", "null" ] }, "visits_per_location": { "type": "integer" }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": "string" }, "age_from": { "type": "integer" }, "age_to": { "type": "integer" } } }, "legend": { "type": [ "string", "null" ] }, "reimbursement": { "type": "integer" }, "currency": { "type": "string" }, "quote": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } }, "offer": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "payment_status": { "type": "string" }, "decline_reason": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "department_id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "visits": { "type": "integer" }, "note": { "type": [ "string", "null" ] } } } }, "problems": { "type": "object" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "avg": { "type": [ "string", "null" ] }, "planned": { "type": "integer" } } }, "submitted_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "number": "MS-00042", "status": "quoted", "business_type": "cafe", "scenarios": [ "service", "cleanliness" ], "goal": "Check the new menu launch", "checklist_id": 310, "needs_questionnaire": false, "questionnaire_brief": null, "visits_per_location": 2, "period_from": "2026-11-10", "period_to": "2026-11-30", "time_slots": [ "weekday", "evening" ], "requirements": { "audio": false, "receipt": true, "place_photos": false, "staff": true, "express": false }, "shopper_profile": { "gender": "any", "age_from": 20, "age_to": 35 }, "legend": null, "reimbursement": 5000, "currency": "KZT", "quote": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 }, "offer": null, "total": 84000, "contact_name": "Daniyar Omarov", "contact_phone": "+7 701 000 00 01", "comment": null, "payment_status": "none", "decline_reason": null, "locations": [ { "id": 77, "department_id": 12, "name": "Abay Ave", "city": "Almaty", "address": "12 Abay Ave", "visits": 2, "note": null } ], "problems": {}, "progress": { "done": 0, "avg": null, "planned": 6 }, "submitted_at": "2026-11-03T10:00:00+05:00", "confirmed_at": null, "launched_at": null, "completed_at": null, "created_at": "2026-11-02T18:00:00+05:00", "url": "https://app.jecheck.io/ui/mystery/orders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "mysteryOrdersCreate", "summary": "Create a turnkey order draft", "description": "Saves a draft with a quote; `problems` lists what is missing before `submit`. The service is currently available only in some countries (see the catalog).", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_create", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_type": { "type": [ "string", "null" ], "enum": [ "restaurant", "cafe", "bar", "coffee", "fastfood", "retail", "beauty", "clinic", "hotel", "other" ], "description": "Business type (affects price and reimbursement)" }, "scenarios": { "type": "array", "items": { "type": "string" }, "description": "What the guest checks: dine_in, takeaway, delivery, phone, consultation", "maxItems": 5 }, "goal": { "type": [ "string", "null" ], "maxLength": 3000 }, "checklist_id": { "type": [ "integer", "null" ], "description": "Questionnaire (checklist) to use" }, "needs_questionnaire": { "type": "boolean", "description": "Ask jeCheck to prepare the questionnaire" }, "questionnaire_brief": { "type": [ "string", "null" ], "maxLength": 3000 }, "visits_per_location": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "period_from": { "type": [ "string", "null" ], "format": "date" }, "period_to": { "type": [ "string", "null" ], "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" }, "description": "weekday, weekend, morning, lunch, evening", "maxItems": 5 }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": [ "string", "null" ], "enum": [ "any", "f", "m" ] }, "age_from": { "type": [ "integer", "null" ], "minimum": 16, "maximum": 80 }, "age_to": { "type": [ "integer", "null" ], "minimum": 16, "maximum": 80 }, "note": { "type": [ "string", "null" ], "maxLength": 500 } } }, "legend": { "type": [ "string", "null" ], "maxLength": 3000 }, "reimbursement": { "type": [ "number", "null" ], "description": "Receipt reimbursement per visit", "minimum": 0 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "department_id": { "type": "integer", "description": "Location id" }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "address": { "type": [ "string", "null" ], "maxLength": 500 }, "visits": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "note": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "department_id" ] }, "maxItems": 300 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "comment": { "type": [ "string", "null" ], "maxLength": 3000 } } }, "example": { "business_type": "restaurant", "scenarios": [ "example" ], "goal": "string", "checklist_id": 42 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "business_type": { "type": "string" }, "scenarios": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string" }, "checklist_id": { "type": "integer" }, "needs_questionnaire": { "type": "boolean" }, "questionnaire_brief": { "type": [ "string", "null" ] }, "visits_per_location": { "type": "integer" }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": "string" }, "age_from": { "type": "integer" }, "age_to": { "type": "integer" } } }, "legend": { "type": [ "string", "null" ] }, "reimbursement": { "type": "integer" }, "currency": { "type": "string" }, "quote": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } }, "offer": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "payment_status": { "type": "string" }, "decline_reason": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "department_id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "visits": { "type": "integer" }, "note": { "type": [ "string", "null" ] } } } }, "problems": { "type": "object" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "avg": { "type": [ "string", "null" ] }, "planned": { "type": "integer" } } }, "submitted_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "number": "MS-00042", "status": "quoted", "business_type": "cafe", "scenarios": [ "service", "cleanliness" ], "goal": "Check the new menu launch", "checklist_id": 310, "needs_questionnaire": false, "questionnaire_brief": null, "visits_per_location": 2, "period_from": "2026-11-10", "period_to": "2026-11-30", "time_slots": [ "weekday", "evening" ], "requirements": { "audio": false, "receipt": true, "place_photos": false, "staff": true, "express": false }, "shopper_profile": { "gender": "any", "age_from": 20, "age_to": 35 }, "legend": null, "reimbursement": 5000, "currency": "KZT", "quote": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 }, "offer": null, "total": 84000, "contact_name": "Daniyar Omarov", "contact_phone": "+7 701 000 00 01", "comment": null, "payment_status": "none", "decline_reason": null, "locations": [ { "id": 77, "department_id": 12, "name": "Abay Ave", "city": "Almaty", "address": "12 Abay Ave", "visits": 2, "note": null } ], "problems": {}, "progress": { "done": 0, "avg": null, "planned": 6 }, "submitted_at": "2026-11-03T10:00:00+05:00", "confirmed_at": null, "launched_at": null, "completed_at": null, "created_at": "2026-11-02T18:00:00+05:00", "url": "https://app.jecheck.io/ui/mystery/orders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders/catalog": { "get": { "operationId": "mysteryOrdersCatalog", "summary": "Get turnkey pricing catalog", "description": "Whether the service is available in the company's country, business types, cities and prices used by the quote.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_catalog", "x-permissions": [ "mystery.orders" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "availability": { "type": "object", "properties": { "available": { "type": "boolean" }, "country": { "type": "string" }, "countries": { "type": "array", "items": { "type": "string" } } } }, "catalog": { "type": "object", "properties": { "currency": { "type": "string" }, "cities": { "type": "array", "items": { "type": "string" } }, "major_cities": { "type": "array", "items": { "type": "string" } }, "business_types": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reimbursement": { "type": "integer" }, "tier": { "type": "string" } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "availability": { "available": true, "country": "KZ", "countries": [ "KZ" ] }, "catalog": { "currency": "KZT", "cities": [ "Almaty" ], "major_cities": [ "Almaty" ], "business_types": [ { "key": "cafe", "reimbursement": 5000, "tier": "standard" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders/quote": { "post": { "operationId": "mysteryOrdersQuote", "summary": "Calculate a turnkey quote", "description": "Price estimate for the given order parameters without saving anything.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_quote", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_type": { "type": [ "string", "null" ], "enum": [ "restaurant", "cafe", "bar", "coffee", "fastfood", "retail", "beauty", "clinic", "hotel", "other" ], "description": "Business type (affects price and reimbursement)" }, "scenarios": { "type": "array", "items": { "type": "string" }, "description": "What the guest checks: dine_in, takeaway, delivery, phone, consultation", "maxItems": 5 }, "goal": { "type": [ "string", "null" ], "maxLength": 3000 }, "checklist_id": { "type": [ "integer", "null" ], "description": "Questionnaire (checklist) to use" }, "needs_questionnaire": { "type": "boolean", "description": "Ask jeCheck to prepare the questionnaire" }, "questionnaire_brief": { "type": [ "string", "null" ], "maxLength": 3000 }, "visits_per_location": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "period_from": { "type": [ "string", "null" ], "format": "date" }, "period_to": { "type": [ "string", "null" ], "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" }, "description": "weekday, weekend, morning, lunch, evening", "maxItems": 5 }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": [ "string", "null" ], "enum": [ "any", "f", "m" ] }, "age_from": { "type": [ "integer", "null" ], "minimum": 16, "maximum": 80 }, "age_to": { "type": [ "integer", "null" ], "minimum": 16, "maximum": 80 }, "note": { "type": [ "string", "null" ], "maxLength": 500 } } }, "legend": { "type": [ "string", "null" ], "maxLength": 3000 }, "reimbursement": { "type": [ "number", "null" ], "description": "Receipt reimbursement per visit", "minimum": 0 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "department_id": { "type": "integer", "description": "Location id" }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "address": { "type": [ "string", "null" ], "maxLength": 500 }, "visits": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "note": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "department_id" ] }, "maxItems": 300 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "comment": { "type": [ "string", "null" ], "maxLength": 3000 } } }, "example": { "business_type": "restaurant", "scenarios": [ "example" ], "goal": "string", "checklist_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders/{uuid}": { "get": { "operationId": "mysteryOrdersGet", "summary": "Retrieve a turnkey order", "description": "Order terms, quote and offer, progress, visits (results after jeCheck approves them) and the message history.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_get", "x-permissions": [ "mystery.orders" ], "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Order UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "business_type": { "type": "string" }, "scenarios": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string" }, "checklist_id": { "type": "integer" }, "needs_questionnaire": { "type": "boolean" }, "questionnaire_brief": { "type": [ "string", "null" ] }, "visits_per_location": { "type": "integer" }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": "string" }, "age_from": { "type": "integer" }, "age_to": { "type": "integer" } } }, "legend": { "type": [ "string", "null" ] }, "reimbursement": { "type": "integer" }, "currency": { "type": "string" }, "quote": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } }, "offer": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "payment_status": { "type": "string" }, "decline_reason": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "department_id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "visits": { "type": "integer" }, "note": { "type": [ "string", "null" ] } } } }, "problems": { "type": "object" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "avg": { "type": [ "string", "null" ] }, "planned": { "type": "integer" } } }, "submitted_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "visits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "stage": { "type": "string" }, "window_to": { "type": "string", "format": "date-time" }, "visited_at": { "type": "string", "format": "date-time" }, "score": { "type": "integer" }, "audit_uuid": { "type": "string", "format": "uuid" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "side": { "type": "string" }, "author": { "type": "string" }, "body": { "type": "string" }, "payload": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "number": "MS-00042", "status": "quoted", "business_type": "cafe", "scenarios": [ "service", "cleanliness" ], "goal": "Check the new menu launch", "checklist_id": 310, "needs_questionnaire": false, "questionnaire_brief": null, "visits_per_location": 2, "period_from": "2026-11-10", "period_to": "2026-11-30", "time_slots": [ "weekday", "evening" ], "requirements": { "audio": false, "receipt": true, "place_photos": false, "staff": true, "express": false }, "shopper_profile": { "gender": "any", "age_from": 20, "age_to": 35 }, "legend": null, "reimbursement": 5000, "currency": "KZT", "quote": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 }, "offer": null, "total": 84000, "contact_name": "Daniyar Omarov", "contact_phone": "+7 701 000 00 01", "comment": null, "payment_status": "none", "decline_reason": null, "locations": [ { "id": 77, "department_id": 12, "name": "Abay Ave", "city": "Almaty", "address": "12 Abay Ave", "visits": 2, "note": null } ], "problems": {}, "progress": { "done": 0, "avg": null, "planned": 6 }, "submitted_at": "2026-11-03T10:00:00+05:00", "confirmed_at": null, "launched_at": null, "completed_at": null, "created_at": "2026-11-02T18:00:00+05:00", "url": "https://app.jecheck.io/ui/mystery/orders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "visits": [ { "id": 2050, "location": { "id": 12, "name": "Abay Ave" }, "stage": "done", "window_to": "2026-11-20T21:00:00+05:00", "visited_at": "2026-11-18T19:10:00+05:00", "score": 91, "audit_uuid": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e" } ], "events": [ { "id": 1, "type": "message", "side": "service", "author": "Anna", "body": "We have prepared the terms", "payload": null, "at": "2026-11-03T11:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "mysteryOrdersUpdate", "summary": "Update a turnkey order draft", "description": "Only drafts can be edited; after submitting, changes are agreed with the manager in messages.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_update", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Order UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_type": { "type": [ "string", "null" ], "enum": [ "restaurant", "cafe", "bar", "coffee", "fastfood", "retail", "beauty", "clinic", "hotel", "other" ], "description": "Business type (affects price and reimbursement)" }, "scenarios": { "type": "array", "items": { "type": "string" }, "description": "What the guest checks: dine_in, takeaway, delivery, phone, consultation", "maxItems": 5 }, "goal": { "type": [ "string", "null" ], "maxLength": 3000 }, "checklist_id": { "type": [ "integer", "null" ], "description": "Questionnaire (checklist) to use" }, "needs_questionnaire": { "type": "boolean", "description": "Ask jeCheck to prepare the questionnaire" }, "questionnaire_brief": { "type": [ "string", "null" ], "maxLength": 3000 }, "visits_per_location": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "period_from": { "type": [ "string", "null" ], "format": "date" }, "period_to": { "type": [ "string", "null" ], "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" }, "description": "weekday, weekend, morning, lunch, evening", "maxItems": 5 }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": [ "string", "null" ], "enum": [ "any", "f", "m" ] }, "age_from": { "type": [ "integer", "null" ], "minimum": 16, "maximum": 80 }, "age_to": { "type": [ "integer", "null" ], "minimum": 16, "maximum": 80 }, "note": { "type": [ "string", "null" ], "maxLength": 500 } } }, "legend": { "type": [ "string", "null" ], "maxLength": 3000 }, "reimbursement": { "type": [ "number", "null" ], "description": "Receipt reimbursement per visit", "minimum": 0 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "department_id": { "type": "integer", "description": "Location id" }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "address": { "type": [ "string", "null" ], "maxLength": 500 }, "visits": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "note": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "department_id" ] }, "maxItems": 300 }, "contact_name": { "type": [ "string", "null" ], "maxLength": 255 }, "contact_phone": { "type": [ "string", "null" ], "maxLength": 64 }, "comment": { "type": [ "string", "null" ], "maxLength": 3000 } } }, "example": { "business_type": "restaurant", "scenarios": [ "example" ], "goal": "string", "checklist_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "business_type": { "type": "string" }, "scenarios": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string" }, "checklist_id": { "type": "integer" }, "needs_questionnaire": { "type": "boolean" }, "questionnaire_brief": { "type": [ "string", "null" ] }, "visits_per_location": { "type": "integer" }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": "string" }, "age_from": { "type": "integer" }, "age_to": { "type": "integer" } } }, "legend": { "type": [ "string", "null" ] }, "reimbursement": { "type": "integer" }, "currency": { "type": "string" }, "quote": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } }, "offer": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "payment_status": { "type": "string" }, "decline_reason": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "department_id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "visits": { "type": "integer" }, "note": { "type": [ "string", "null" ] } } } }, "problems": { "type": "object" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "avg": { "type": [ "string", "null" ] }, "planned": { "type": "integer" } } }, "submitted_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "number": "MS-00042", "status": "quoted", "business_type": "cafe", "scenarios": [ "service", "cleanliness" ], "goal": "Check the new menu launch", "checklist_id": 310, "needs_questionnaire": false, "questionnaire_brief": null, "visits_per_location": 2, "period_from": "2026-11-10", "period_to": "2026-11-30", "time_slots": [ "weekday", "evening" ], "requirements": { "audio": false, "receipt": true, "place_photos": false, "staff": true, "express": false }, "shopper_profile": { "gender": "any", "age_from": 20, "age_to": 35 }, "legend": null, "reimbursement": 5000, "currency": "KZT", "quote": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 }, "offer": null, "total": 84000, "contact_name": "Daniyar Omarov", "contact_phone": "+7 701 000 00 01", "comment": null, "payment_status": "none", "decline_reason": null, "locations": [ { "id": 77, "department_id": 12, "name": "Abay Ave", "city": "Almaty", "address": "12 Abay Ave", "visits": 2, "note": null } ], "problems": {}, "progress": { "done": 0, "avg": null, "planned": 6 }, "submitted_at": "2026-11-03T10:00:00+05:00", "confirmed_at": null, "launched_at": null, "completed_at": null, "created_at": "2026-11-02T18:00:00+05:00", "url": "https://app.jecheck.io/ui/mystery/orders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "mysteryOrdersDelete", "summary": "Delete a turnkey order draft", "description": "Only drafts can be deleted; submitted orders are cancelled.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_delete", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Order UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders/{uuid}/accept": { "post": { "operationId": "mysteryOrdersAccept", "summary": "Accept the offer of a turnkey order", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_accept", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Order UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "business_type": { "type": "string" }, "scenarios": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string" }, "checklist_id": { "type": "integer" }, "needs_questionnaire": { "type": "boolean" }, "questionnaire_brief": { "type": [ "string", "null" ] }, "visits_per_location": { "type": "integer" }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": "string" }, "age_from": { "type": "integer" }, "age_to": { "type": "integer" } } }, "legend": { "type": [ "string", "null" ] }, "reimbursement": { "type": "integer" }, "currency": { "type": "string" }, "quote": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } }, "offer": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "payment_status": { "type": "string" }, "decline_reason": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "department_id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "visits": { "type": "integer" }, "note": { "type": [ "string", "null" ] } } } }, "problems": { "type": "object" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "avg": { "type": [ "string", "null" ] }, "planned": { "type": "integer" } } }, "submitted_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "number": "MS-00042", "status": "quoted", "business_type": "cafe", "scenarios": [ "service", "cleanliness" ], "goal": "Check the new menu launch", "checklist_id": 310, "needs_questionnaire": false, "questionnaire_brief": null, "visits_per_location": 2, "period_from": "2026-11-10", "period_to": "2026-11-30", "time_slots": [ "weekday", "evening" ], "requirements": { "audio": false, "receipt": true, "place_photos": false, "staff": true, "express": false }, "shopper_profile": { "gender": "any", "age_from": 20, "age_to": 35 }, "legend": null, "reimbursement": 5000, "currency": "KZT", "quote": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 }, "offer": null, "total": 84000, "contact_name": "Daniyar Omarov", "contact_phone": "+7 701 000 00 01", "comment": null, "payment_status": "none", "decline_reason": null, "locations": [ { "id": 77, "department_id": 12, "name": "Abay Ave", "city": "Almaty", "address": "12 Abay Ave", "visits": 2, "note": null } ], "problems": {}, "progress": { "done": 0, "avg": null, "planned": 6 }, "submitted_at": "2026-11-03T10:00:00+05:00", "confirmed_at": null, "launched_at": null, "completed_at": null, "created_at": "2026-11-02T18:00:00+05:00", "url": "https://app.jecheck.io/ui/mystery/orders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders/{uuid}/cancel": { "post": { "operationId": "mysteryOrdersCancel", "summary": "Cancel a turnkey order", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_cancel", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Order UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 2000 } } }, "example": { "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "business_type": { "type": "string" }, "scenarios": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string" }, "checklist_id": { "type": "integer" }, "needs_questionnaire": { "type": "boolean" }, "questionnaire_brief": { "type": [ "string", "null" ] }, "visits_per_location": { "type": "integer" }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": "string" }, "age_from": { "type": "integer" }, "age_to": { "type": "integer" } } }, "legend": { "type": [ "string", "null" ] }, "reimbursement": { "type": "integer" }, "currency": { "type": "string" }, "quote": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } }, "offer": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "payment_status": { "type": "string" }, "decline_reason": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "department_id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "visits": { "type": "integer" }, "note": { "type": [ "string", "null" ] } } } }, "problems": { "type": "object" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "avg": { "type": [ "string", "null" ] }, "planned": { "type": "integer" } } }, "submitted_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "number": "MS-00042", "status": "quoted", "business_type": "cafe", "scenarios": [ "service", "cleanliness" ], "goal": "Check the new menu launch", "checklist_id": 310, "needs_questionnaire": false, "questionnaire_brief": null, "visits_per_location": 2, "period_from": "2026-11-10", "period_to": "2026-11-30", "time_slots": [ "weekday", "evening" ], "requirements": { "audio": false, "receipt": true, "place_photos": false, "staff": true, "express": false }, "shopper_profile": { "gender": "any", "age_from": 20, "age_to": 35 }, "legend": null, "reimbursement": 5000, "currency": "KZT", "quote": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 }, "offer": null, "total": 84000, "contact_name": "Daniyar Omarov", "contact_phone": "+7 701 000 00 01", "comment": null, "payment_status": "none", "decline_reason": null, "locations": [ { "id": 77, "department_id": 12, "name": "Abay Ave", "city": "Almaty", "address": "12 Abay Ave", "visits": 2, "note": null } ], "problems": {}, "progress": { "done": 0, "avg": null, "planned": 6 }, "submitted_at": "2026-11-03T10:00:00+05:00", "confirmed_at": null, "launched_at": null, "completed_at": null, "created_at": "2026-11-02T18:00:00+05:00", "url": "https://app.jecheck.io/ui/mystery/orders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders/{uuid}/messages": { "post": { "operationId": "mysteryOrdersMessagesCreate", "summary": "Write to the jeCheck manager", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_messages_create", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Order UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "body" ] }, "example": { "body": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "side": { "type": "string" }, "author": { "type": "string" }, "body": { "type": "string" }, "payload": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2, "type": "message", "side": "client", "author": "Daniyar Omarov", "body": "Can we add one more location?", "payload": null, "at": "2026-11-03T12:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/orders/{uuid}/submit": { "post": { "operationId": "mysteryOrdersSubmit", "summary": "Submit a turnkey order", "description": "Sends the completed draft to jeCheck managers, who reply with an offer.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_orders_submit", "x-permissions": [ "mystery.orders" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Order UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "business_type": { "type": "string" }, "scenarios": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string" }, "checklist_id": { "type": "integer" }, "needs_questionnaire": { "type": "boolean" }, "questionnaire_brief": { "type": [ "string", "null" ] }, "visits_per_location": { "type": "integer" }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "time_slots": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "properties": { "audio": { "type": "boolean" }, "receipt": { "type": "boolean" }, "place_photos": { "type": "boolean" }, "staff": { "type": "boolean" }, "express": { "type": "boolean" } } }, "shopper_profile": { "type": "object", "properties": { "gender": { "type": "string" }, "age_from": { "type": "integer" }, "age_to": { "type": "integer" } } }, "legend": { "type": [ "string", "null" ] }, "reimbursement": { "type": "integer" }, "currency": { "type": "string" }, "quote": { "type": "object", "properties": { "currency": { "type": "string" }, "visits": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "qty": { "type": "integer" }, "unit": { "type": "integer" }, "amount": { "type": "integer" } } } }, "total": { "type": "integer" }, "per_visit": { "type": "integer" } } }, "offer": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "payment_status": { "type": "string" }, "decline_reason": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "department_id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "visits": { "type": "integer" }, "note": { "type": [ "string", "null" ] } } } }, "problems": { "type": "object" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "avg": { "type": [ "string", "null" ] }, "planned": { "type": "integer" } } }, "submitted_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "number": "MS-00042", "status": "quoted", "business_type": "cafe", "scenarios": [ "service", "cleanliness" ], "goal": "Check the new menu launch", "checklist_id": 310, "needs_questionnaire": false, "questionnaire_brief": null, "visits_per_location": 2, "period_from": "2026-11-10", "period_to": "2026-11-30", "time_slots": [ "weekday", "evening" ], "requirements": { "audio": false, "receipt": true, "place_photos": false, "staff": true, "express": false }, "shopper_profile": { "gender": "any", "age_from": 20, "age_to": 35 }, "legend": null, "reimbursement": 5000, "currency": "KZT", "quote": { "currency": "KZT", "visits": 6, "lines": [ { "key": "visit", "qty": 6, "unit": 9000, "amount": 54000 } ], "total": 84000, "per_visit": 14000 }, "offer": null, "total": 84000, "contact_name": "Daniyar Omarov", "contact_phone": "+7 701 000 00 01", "comment": null, "payment_status": "none", "decline_reason": null, "locations": [ { "id": 77, "department_id": 12, "name": "Abay Ave", "city": "Almaty", "address": "12 Abay Ave", "visits": 2, "note": null } ], "problems": {}, "progress": { "done": 0, "avg": null, "planned": 6 }, "submitted_at": "2026-11-03T10:00:00+05:00", "confirmed_at": null, "launched_at": null, "completed_at": null, "created_at": "2026-11-02T18:00:00+05:00", "url": "https://app.jecheck.io/ui/mystery/orders/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/shoppers": { "get": { "operationId": "mysteryShoppersList", "summary": "List guests", "description": "The company's pool of mystery guests with visit statistics. Email and phone — only with `mystery.payouts` (logged).", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_shoppers_list", "x-permissions": [ "mystery.view" ], "x-plan-feature": "mystery", "x-scope": "read", "parameters": [ { "name": "active", "in": "query", "description": "Only active guests", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "has_email": { "type": "boolean" }, "note": { "type": "string" }, "is_active": { "type": "boolean" }, "visits": { "type": "object", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "rejected": { "type": "integer" }, "active": { "type": "integer" }, "returned": { "type": "integer" } } }, "last_visit_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 55, "name": "Madina K.", "city": "Almaty", "email": "madina@example.com", "phone": "+7 701 000 00 00", "has_email": true, "note": "Prefers weekends", "is_active": true, "visits": { "total": 12, "approved": 10, "rejected": 1, "active": 1, "returned": 2 }, "last_visit_at": "2026-11-03T13:40:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "mysteryShoppersCreate", "summary": "Add a guest", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_shoppers_create", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255 }, "email": { "type": [ "string", "null" ], "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 64 }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "note": { "type": [ "string", "null" ], "maxLength": 2000 }, "is_active": { "type": "boolean" } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "email": "anna@example.com", "phone": "+77010000000", "city": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "has_email": { "type": "boolean" }, "note": { "type": "string" }, "is_active": { "type": "boolean" }, "visits": { "type": "object", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "rejected": { "type": "integer" }, "active": { "type": "integer" }, "returned": { "type": "integer" } } }, "last_visit_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 55, "name": "Madina K.", "city": "Almaty", "email": "madina@example.com", "phone": "+7 701 000 00 00", "has_email": true, "note": "Prefers weekends", "is_active": true, "visits": { "total": 12, "approved": 10, "rejected": 1, "active": 1, "returned": 2 }, "last_visit_at": "2026-11-03T13:40:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/shoppers/{id}": { "patch": { "operationId": "mysteryShoppersUpdate", "summary": "Update a guest", "description": "Contacts (email, phone) can be changed only with `mystery.payouts`.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_shoppers_update", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Guest id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255 }, "email": { "type": [ "string", "null" ], "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 64 }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "note": { "type": [ "string", "null" ], "maxLength": 2000 }, "is_active": { "type": "boolean" } } }, "example": { "name": "Replace the broken fridge seal", "email": "anna@example.com", "phone": "+77010000000", "city": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "city": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "has_email": { "type": "boolean" }, "note": { "type": "string" }, "is_active": { "type": "boolean" }, "visits": { "type": "object", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "rejected": { "type": "integer" }, "active": { "type": "integer" }, "returned": { "type": "integer" } } }, "last_visit_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 55, "name": "Madina K.", "city": "Almaty", "email": "madina@example.com", "phone": "+7 701 000 00 00", "has_email": true, "note": "Prefers weekends", "is_active": true, "visits": { "total": 12, "approved": 10, "rejected": 1, "active": 1, "returned": 2 }, "last_visit_at": "2026-11-03T13:40:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "mysteryShoppersDelete", "summary": "Delete a guest", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_shoppers_delete", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Guest id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits": { "get": { "operationId": "mysteryVisitsList", "summary": "List mystery shopper visits", "description": "Visits of the company, newest first. The guest link (`guest_url`) is returned with `mystery.manage`; payouts — with `mystery.payouts` (logged). Turnkey visits (`managed`) hide the guest.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_list", "x-permissions": [ "mystery.view" ], "x-plan-feature": "mystery", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "status[]", "in": "query", "description": "scheduled, opened, in_progress, submitted, returned, approved, rejected, cancelled, expired", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_id", "in": "query", "description": "Only this questionnaire", "schema": { "type": "integer" } }, { "name": "shopper_id", "in": "query", "description": "Only this guest", "schema": { "type": "integer" } }, { "name": "wave", "in": "query", "description": "Only this wave", "schema": { "type": "string", "maxLength": 120 } }, { "name": "managed", "in": "query", "description": "`true` — only turnkey visits, `false` — only own visits", "schema": { "type": "boolean" } }, { "name": "flagged", "in": "query", "description": "Only submitted visits with serious fraud flags", "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "description": "Submitted from", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Submitted to", "schema": { "type": "string", "format": "date" } }, { "name": "updated_since", "in": "query", "description": "Only visits changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "mysteryVisitsCreate", "summary": "Create visits", "description": "Creates one visit per location for a questionnaire (checklist). Each visit gets a personal guest link (`guest_url`) that works without the app; with `shopper_id` and `send_email` the guest receives it by email.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_create", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checklist_id": { "type": "integer", "description": "Questionnaire (checklist)" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 300 }, "shopper_id": { "type": [ "integer", "null" ], "description": "Guest from the pool" }, "wave": { "type": [ "string", "null" ], "maxLength": 120 }, "brief": { "type": [ "string", "null" ], "description": "Task for the guest", "maxLength": 5000 }, "legend": { "type": [ "string", "null" ], "description": "Cover story", "maxLength": 5000 }, "window_from": { "type": [ "string", "null" ], "format": "date-time" }, "window_to": { "type": [ "string", "null" ], "format": "date-time", "description": "Deadline (after `window_from`)" }, "send_email": { "type": "boolean", "description": "Email the link to the guest" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean", "description": "false — accept automatically" }, "min_minutes": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 600 }, "geo_radius": { "type": [ "integer", "null" ], "minimum": 50, "maximum": 5000 }, "receipt_limit": { "type": [ "number", "null" ], "minimum": 0 }, "currency": { "type": [ "string", "null" ], "maxLength": 8 } }, "description": "Questionnaire requirements and anti-fraud checks" } }, "required": [ "checklist_id", "location_ids" ] }, "example": { "checklist_id": 42, "location_ids": [ 12, 14 ], "shopper_id": 42, "wave": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "guest_url": { "type": "string", "format": "uri" }, "invited": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 2041, "location": { "id": 12, "name": "Abay Ave" }, "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "invited": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}": { "get": { "operationId": "mysteryVisitsGet", "summary": "Retrieve a visit", "description": "Full questionnaire: answers with per-question results, timing, guest report, geolocation vs the location, fraud flags, AI check, files (receipt, photos, audio — private media via `mystery.media.get`), history. Turnkey visits are available after jeCheck approves them (`409 managed_visit` before).", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_get", "x-permissions": [ "mystery.view" ], "x-plan-feature": "mystery", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "mysteryVisitsUpdate", "summary": "Update a visit", "description": "Change the brief, cover story, time window or guest of an open visit. The guest cannot be changed after the visit has started.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_update", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": [ "string", "null" ], "maxLength": 5000 }, "legend": { "type": [ "string", "null" ], "maxLength": 5000 }, "window_from": { "type": [ "string", "null" ], "format": "date-time" }, "window_to": { "type": [ "string", "null" ], "format": "date-time" }, "shopper_id": { "type": [ "integer", "null" ] } } }, "example": { "brief": "string", "legend": "string", "window_from": "2026-11-03T09:00:00+05:00", "window_to": "2026-11-03T09:00:00+05:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "mysteryVisitsDelete", "summary": "Delete a visit", "description": "An accepted visit has become an audit — delete the audit first.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_delete", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/ai-review": { "post": { "operationId": "mysteryVisitsAiReview", "summary": "Run the AI review of a visit", "description": "Transcribes audio and asks the AI to check the questionnaire for consistency (requires the AI feature for the company). The result is in `ai_check` of the visit.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_ai_review", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/approve": { "post": { "operationId": "mysteryVisitsApprove", "summary": "Accept a visit", "description": "Accepts a submitted questionnaire: a regular audit is created from it (reports, mailings, corrective tasks follow as for any audit). Returns the visit with `audit_uuid`.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_approve", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Comment", "maxLength": 3000 } } }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/cancel": { "post": { "operationId": "mysteryVisitsCancel", "summary": "Cancel a visit", "description": "Cancels a visit that has not been submitted; the guest link stops working.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_cancel", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/invite": { "post": { "operationId": "mysteryVisitsInvite", "summary": "Send the link to the guest", "description": "Emails the questionnaire link to the guest of the visit (requires a guest with an email).", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_invite", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/payout": { "post": { "operationId": "mysteryVisitsPayout", "summary": "Set the payout of a visit", "description": "Payout status and amount for the guest (receipt reimbursement and fee). Requires `mystery.payouts`.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_payout", "x-permissions": [ "mystery.payouts" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "none", "pending", "paid" ] }, "amount": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "status" ] }, "example": { "status": "none", "amount": 4.5 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/recheck": { "post": { "operationId": "mysteryVisitsRecheck", "summary": "Re-run fraud checks", "description": "Recalculates automatic flags: geolocation, time on site, receipt, photo metadata, duplicates.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_recheck", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/reject": { "post": { "operationId": "mysteryVisitsReject", "summary": "Reject a visit", "description": "Rejects a submitted questionnaire (e.g. fraud); no payout.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_reject", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "note" ] }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/reopen": { "post": { "operationId": "mysteryVisitsReopen", "summary": "Reopen a visit", "description": "Reopens a cancelled or expired visit with a new deadline.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_reopen", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "window_to": { "type": [ "string", "null" ], "format": "date-time", "description": "New deadline (future)" } } }, "example": { "window_to": "2026-11-03T09:00:00+05:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/mystery/visits/{id}/return": { "post": { "operationId": "mysteryVisitsReturn", "summary": "Return a visit to the guest", "description": "Sends a submitted questionnaire back for corrections with a comment; the guest gets the link again.", "tags": [ "Mystery shopper" ], "x-mcp-tool": "mystery_visits_return", "x-permissions": [ "mystery.manage" ], "x-plan-feature": "mystery", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Visit id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "note" ] }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "managed": { "type": "boolean" }, "order_uuid": { "type": [ "string", "null" ] }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "shopper": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "wave": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "level": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guest_url": { "type": "string", "format": "uri" }, "audit_uuid": { "type": [ "string", "null" ] }, "payout_status": { "type": "string" }, "payout_amount": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "address": { "type": "string" }, "brief": { "type": "string" }, "legend": { "type": "string" }, "settings": { "type": "object", "properties": { "require_receipt": { "type": "boolean" }, "require_geo": { "type": "boolean" }, "require_timing": { "type": "boolean" }, "require_staff": { "type": "boolean" }, "require_audio": { "type": "boolean" }, "require_place_photos": { "type": "boolean" }, "review_required": { "type": "boolean" }, "min_minutes": { "type": "integer" }, "geo_radius": { "type": "integer" }, "receipt_limit": { "type": "integer" }, "currency": { "type": "string" } } }, "shopper_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "answers": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "v": { "type": "integer" }, "c": { "type": "string" } } } } }, "results": { "type": "object", "properties": { "8812": { "type": "object", "properties": { "r": { "type": "integer" }, "t": { "type": "string" } } } } }, "timing": { "type": "object", "properties": { "arrived": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" } } }, "report": { "type": "object", "properties": { "staff_name": { "type": "string" }, "receipt_amount": { "type": "integer" }, "summary": { "type": "string" } } }, "geo_start": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "acc": { "type": "integer" } } }, "geo_end": { "type": [ "string", "null" ] }, "geo_ref": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "distance_m": { "type": "integer" }, "duration_sec": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" }, "text": { "type": "string" } } } }, "sections_score": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "integer" } } } }, "ai_check": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "returned_count": { "type": "integer" }, "audit": { "type": [ "string", "null" ] }, "invited_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time" }, "form": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "settings": { "type": [ "string", "null" ] }, "weight": { "type": "integer" }, "can_skip": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "question_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "taken_at": { "type": "string", "format": "date-time" }, "mime": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "transcript": { "type": [ "string", "null" ] } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "user": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 2041, "uuid": "9e8d7c6b-5a49-4382-9716-05f4e3d2c1b0", "status": "submitted", "managed": false, "order_uuid": null, "location": { "id": 12, "name": "Abay Ave" }, "checklist": { "id": 310, "name": "Guest experience" }, "shopper": { "id": 55, "name": "Madina K." }, "wave": "November", "window_from": "2026-11-01T09:00:00+05:00", "window_to": "2026-11-07T21:00:00+05:00", "score": 87.5, "level": "warning", "submitted_at": "2026-11-03T13:40:00+05:00", "created_at": "2026-10-30T10:00:00+05:00", "guest_url": "https://app.jecheck.io/mg/Ab12Cd34Ef56Gh78Ij90Kl12", "audit_uuid": null, "payout_status": "pending", "payout_amount": 4500, "updated_at": "2026-11-03T13:40:00+05:00", "url": "https://app.jecheck.io/ui/mystery/visits/2041", "address": "12 Abay Ave", "brief": "Order a cappuccino and a dessert", "legend": "Ask about vegan options", "settings": { "require_receipt": true, "require_geo": true, "require_timing": true, "require_staff": true, "require_audio": false, "require_place_photos": false, "review_required": true, "min_minutes": 10, "geo_radius": 300, "receipt_limit": 5000, "currency": "KZT" }, "shopper_contacts": { "email": "madina@example.com", "phone": "+7 701 000 00 00" }, "answers": { "8812": { "v": 1, "c": "Greeted within 10 seconds" } }, "results": { "8812": { "r": 1, "t": "Yes" } }, "timing": { "arrived": "2026-11-03T13:05:00+05:00", "left": "2026-11-03T13:31:00+05:00" }, "report": { "staff_name": "Aliya", "receipt_amount": 4500, "summary": "Friendly service, long wait for dessert" }, "geo_start": { "lat": 43.2389, "lng": 76.9455, "acc": 12 }, "geo_end": null, "geo_ref": { "lat": 43.2391, "lng": 76.9452 }, "distance_m": 35, "duration_sec": 1560, "flags": [ { "code": "short_visit", "level": "warning", "text": "The visit took less than the minimum time" } ], "sections_score": [ { "id": 101, "name": "Service", "score": 90 } ], "ai_check": null, "review_note": null, "reviewer": null, "reviewed_at": null, "returned_count": 0, "audit": null, "invited_at": "2026-10-30T10:01:00+05:00", "opened_at": "2026-11-03T12:58:00+05:00", "started_at": "2026-11-03T13:02:00+05:00", "form": [ { "id": 101, "name": "Service", "hint": null, "questions": [ { "id": 8812, "section_id": 101, "name": "Were you greeted?", "hint": null, "type": "yes_no", "settings": null, "weight": 1, "can_skip": false, "photo": false } ] } ], "files": [ { "id": 9001, "question_id": null, "kind": "receipt", "url": "https://files.jecheck.io/mystery/761/receipt.jpg", "taken_at": "2026-11-03T13:30:00+05:00", "mime": "image/jpeg", "name": null, "duration": null, "size": 182044, "transcript": null } ], "events": [ { "type": "submitted", "at": "2026-11-03T13:40:00+05:00", "user": null, "note": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/notifications": { "get": { "operationId": "notificationsList", "summary": "List notifications", "description": "Notifications of the acting user, newest first. `meta.unread` — the number of unread notifications.", "tags": [ "Notifications" ], "x-mcp-tool": "notifications_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "unread", "in": "query", "description": "Only unread notifications", "schema": { "type": "boolean" } }, { "name": "since", "in": "query", "description": "Only notifications created after this moment", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "type": { "type": "string" }, "task_id": { "type": "string", "format": "uuid" } } }, "is_read": { "type": "boolean" }, "read_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 88123, "title": "New task: Replace the broken fridge seal", "body": "Abay Ave · due Nov 10", "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "data": { "type": "task", "task_id": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" }, "is_read": false, "read_at": null, "created_at": "2026-11-03T10:24:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/notifications/preferences": { "get": { "operationId": "notificationsPreferencesGet", "summary": "Get notification settings", "description": "Personal settings by channel (`push`, `email`) and event group: `assigned` — a task is assigned, `comments`, `updates` — status and due-date changes, `reminders` — due and overdue reminders, `digest` — daily email digest, `brief` — morning AI-control brief, `urgent` — urgent signals during the day. The in-app history is always kept.", "tags": [ "Notifications" ], "x-mcp-tool": "notifications_preferences_get", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "push": { "type": "object", "properties": { "assigned": { "type": "boolean" }, "comments": { "type": "boolean" }, "updates": { "type": "boolean" }, "reminders": { "type": "boolean" }, "brief": { "type": "boolean" }, "urgent": { "type": "boolean" } } }, "email": { "type": "object", "properties": { "assigned": { "type": "boolean" }, "digest": { "type": "boolean" }, "brief": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "push": { "assigned": true, "comments": true, "updates": true, "reminders": true, "brief": true, "urgent": true }, "email": { "assigned": true, "digest": false, "brief": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "notificationsPreferencesUpdate", "summary": "Update notification settings", "description": "Partial update: pass only the switches to change, e.g. `{\"email\": {\"digest\": false}}`. Unknown keys are ignored.", "tags": [ "Notifications" ], "x-mcp-tool": "notifications_preferences_update", "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "assigned": { "type": "boolean" }, "comments": { "type": "boolean" }, "updates": { "type": "boolean" }, "reminders": { "type": "boolean" }, "brief": { "type": "boolean" }, "urgent": { "type": "boolean" } }, "description": "Push notifications to the mobile app" }, "email": { "type": "object", "properties": { "assigned": { "type": "boolean" }, "digest": { "type": "boolean" }, "brief": { "type": "boolean" } }, "description": "Emails (only for users with web-cabinet access)" } } }, "example": { "push": { "assigned": true, "comments": true, "updates": true }, "email": { "assigned": true, "digest": true, "brief": true } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "push": { "type": "object", "properties": { "assigned": { "type": "boolean" }, "comments": { "type": "boolean" }, "updates": { "type": "boolean" }, "reminders": { "type": "boolean" }, "brief": { "type": "boolean" }, "urgent": { "type": "boolean" } } }, "email": { "type": "object", "properties": { "assigned": { "type": "boolean" }, "digest": { "type": "boolean" }, "brief": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "push": { "assigned": true, "comments": true, "updates": true, "reminders": true, "brief": true, "urgent": true }, "email": { "assigned": true, "digest": false, "brief": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/notifications/read": { "post": { "operationId": "notificationsRead", "summary": "Mark notifications as read", "description": "Pass `ids` to mark specific notifications, or `all: true` to mark everything as read. Returns the remaining unread count.", "tags": [ "Notifications" ], "x-mcp-tool": "notifications_read", "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "Notification ids", "maxItems": 200 }, "all": { "type": "boolean", "description": "Mark all notifications as read" } } }, "example": { "ids": [ 12, 14 ], "all": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "marked": { "type": "integer" }, "unread": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "marked": 2, "unread": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/notifications/unread-count": { "get": { "operationId": "notificationsUnreadCount", "summary": "Count unread notifications", "tags": [ "Notifications" ], "x-mcp-tool": "notifications_unread_count", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "unread": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "unread": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/audits": { "get": { "operationId": "plannerAuditsList", "summary": "List planned audits", "description": "Planned audits (calendar entries) in a date range, ordered by date. The status is computed on read: `done` — marked manually (`done_by: manual`) or matched by a conducted audit of the same checklist and location within the window `date ± tolerance` (`done_by: audit`, `audit_id`); `planned`, `inprogress` (today, start time passed), `overdue` (date passed, window still open), `missed` (window closed). Visible: locations where the token has `planner.view` or `planner.manage`, plus audits assigned to the token user.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_audits_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "date_from", "in": "query", "description": "From date (inclusive); default — today", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "To date (inclusive); default — 30 days after `date_from`; the range is limited to 366 days", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "auditor_ids[]", "in": "query", "description": "Only these auditors", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "checklist_ids[]", "in": "query", "description": "Only these checklists", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "status[]", "in": "query", "description": "Filter by status: planned, inprogress, overdue, missed, done", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "mine", "in": "query", "description": "Only audits assigned to the token user", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "done_by": { "type": [ "string", "null" ] }, "audit_id": { "type": [ "string", "null" ] }, "audit_date": { "type": [ "string", "null" ] }, "window_from": { "type": "string", "format": "date" }, "window_to": { "type": "string", "format": "date" }, "plan_key": { "type": "string", "format": "uuid" }, "series_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 48211, "date": "2026-11-05", "time": "09:00", "duration_min": 60, "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "status": "planned", "done_by": null, "audit_id": null, "audit_date": null, "window_from": "2026-11-04", "window_to": "2026-11-06", "plan_key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "series_id": 1842, "url": "https://app.jecheck.io/ui/planner?date=2026-11-05" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/audits/{id}": { "get": { "operationId": "plannerAuditsGet", "summary": "Retrieve a planned audit", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_audits_get", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Planned audit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "done_by": { "type": [ "string", "null" ] }, "audit_id": { "type": [ "string", "null" ] }, "audit_date": { "type": [ "string", "null" ] }, "window_from": { "type": "string", "format": "date" }, "window_to": { "type": "string", "format": "date" }, "plan_key": { "type": "string", "format": "uuid" }, "series_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 48211, "date": "2026-11-05", "time": "09:00", "duration_min": 60, "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "status": "planned", "done_by": null, "audit_id": null, "audit_date": null, "window_from": "2026-11-04", "window_to": "2026-11-06", "plan_key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "series_id": 1842, "url": "https://app.jecheck.io/ui/planner?date=2026-11-05" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "plannerAuditsCancel", "summary": "Cancel a planned audit", "description": "Removes one planned audit from its plan. A done audit cannot be cancelled. Requires `planner.manage` on its location.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_audits_cancel", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Planned audit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/audits/{id}/complete": { "post": { "operationId": "plannerAuditsComplete", "summary": "Mark a planned audit as done", "description": "Manual \"done\" mark (e.g. the audit was done on paper). Allowed with `planner.manage` on the location or to the assigned auditor.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_audits_complete", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Planned audit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "done_by": { "type": [ "string", "null" ] }, "audit_id": { "type": [ "string", "null" ] }, "audit_date": { "type": [ "string", "null" ] }, "window_from": { "type": "string", "format": "date" }, "window_to": { "type": "string", "format": "date" }, "plan_key": { "type": "string", "format": "uuid" }, "series_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 48211, "date": "2026-11-05", "time": "09:00", "duration_min": 60, "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "status": "planned", "done_by": null, "audit_id": null, "audit_date": null, "window_from": "2026-11-04", "window_to": "2026-11-06", "plan_key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "series_id": 1842, "url": "https://app.jecheck.io/ui/planner?date=2026-11-05" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/audits/{id}/reassign": { "post": { "operationId": "plannerAuditsReassign", "summary": "Reassign a planned audit", "description": "Assigns the planned audit to another auditor; the checklist must be available to them. Requires `planner.manage` on its location.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_audits_reassign", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Planned audit id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auditor_id": { "type": "integer", "description": "New auditor (user id)" } }, "required": [ "auditor_id" ] }, "example": { "auditor_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "done_by": { "type": [ "string", "null" ] }, "audit_id": { "type": [ "string", "null" ] }, "audit_date": { "type": [ "string", "null" ] }, "window_from": { "type": "string", "format": "date" }, "window_to": { "type": "string", "format": "date" }, "plan_key": { "type": "string", "format": "uuid" }, "series_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 48211, "date": "2026-11-05", "time": "09:00", "duration_min": 60, "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "status": "planned", "done_by": null, "audit_id": null, "audit_date": null, "window_from": "2026-11-04", "window_to": "2026-11-06", "plan_key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "series_id": 1842, "url": "https://app.jecheck.io/ui/planner?date=2026-11-05" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/audits/{id}/reschedule": { "post": { "operationId": "plannerAuditsReschedule", "summary": "Reschedule a planned audit", "description": "Moves the planned audit to another date and/or time; reminders are sent again. Requires `planner.manage` on its location.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_audits_reschedule", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Planned audit id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "New date" }, "time": { "type": "string", "description": "New start time `HH:MM` (kept if omitted)" } }, "required": [ "date" ] }, "example": { "date": "2026-11-01", "time": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "done_by": { "type": [ "string", "null" ] }, "audit_id": { "type": [ "string", "null" ] }, "audit_date": { "type": [ "string", "null" ] }, "window_from": { "type": "string", "format": "date" }, "window_to": { "type": "string", "format": "date" }, "plan_key": { "type": "string", "format": "uuid" }, "series_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 48211, "date": "2026-11-05", "time": "09:00", "duration_min": 60, "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "status": "planned", "done_by": null, "audit_id": null, "audit_date": null, "window_from": "2026-11-04", "window_to": "2026-11-06", "plan_key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "series_id": 1842, "url": "https://app.jecheck.io/ui/planner?date=2026-11-05" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/audits/{id}/uncomplete": { "post": { "operationId": "plannerAuditsUncomplete", "summary": "Remove the manual done mark", "description": "The status is computed again. Fails with 422 if the audit was not marked manually.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_audits_uncomplete", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Planned audit id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "done_by": { "type": [ "string", "null" ] }, "audit_id": { "type": [ "string", "null" ] }, "audit_date": { "type": [ "string", "null" ] }, "window_from": { "type": "string", "format": "date" }, "window_to": { "type": "string", "format": "date" }, "plan_key": { "type": "string", "format": "uuid" }, "series_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 48211, "date": "2026-11-05", "time": "09:00", "duration_min": 60, "checklist": { "id": 5845, "name": "Daily dining room check" }, "location": { "id": 12, "name": "Abay Ave" }, "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "status": "planned", "done_by": null, "audit_id": null, "audit_date": null, "window_from": "2026-11-04", "window_to": "2026-11-06", "plan_key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "series_id": 1842, "url": "https://app.jecheck.io/ui/planner?date=2026-11-05" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/plans": { "get": { "operationId": "plannerPlansList", "summary": "List audit plans", "description": "Active plans whose locations are all within the token's `planner.manage` permission. A plan is a set of recurring series of one checklist on several locations.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_plans_list", "x-permissions": [ "planner.manage" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recur": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "month_days": { "type": "array" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "tolerance_days": { "type": "integer" }, "notify": { "type": "object", "properties": { "email": { "type": "boolean" }, "day1": { "type": "boolean" }, "hour1": { "type": "boolean" }, "escalate": { "type": "boolean" } } }, "series_ids": { "type": "array", "items": { "type": "integer" } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "title": "Weekly hall check", "checklist": { "id": 5845, "name": "Daily dining room check" }, "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ], "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recur": "weekly", "weekdays": [ 1, 4 ], "month_days": [], "time": "09:00", "duration_min": 60, "start_date": "2026-11-03", "end_date": "2027-02-03", "tolerance_days": 1, "notify": { "email": true, "day1": true, "hour1": false, "escalate": true }, "series_ids": [ 1842, 1843 ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "plannerPlansCreate", "summary": "Create an audit plan", "description": "Creates a plan: one series per location with planned audits generated by the recurrence rule. Requires `planner.manage` on every location of the plan. The response contains the plan and how many audits were scheduled.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_plans_create", "x-permissions": [ "planner.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "description": "Plan title; default \"Plan: \"", "maxLength": 255 }, "checklist_id": { "type": "integer", "description": "Checklist to audit" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Locations — one series per location", "minItems": 1 }, "auditor_id": { "type": "integer", "description": "Auditor (user id); the checklist must be available to them" }, "recur": { "type": "string", "enum": [ "none", "daily", "weekdays", "weekly", "monthly" ], "description": "`none` — once on `start_date`, `daily`, `weekdays` (Mon–Fri), `weekly` (on `weekdays`), `monthly` (on `month_days`)" }, "weekdays": { "type": "array", "items": { "type": "integer" }, "description": "For `weekly`: days of week, 0 = Sunday … 6 = Saturday" }, "month_days": { "type": "array", "items": { "type": "integer" }, "description": "For `monthly`: days of month 1–31" }, "time": { "type": "string", "description": "Start time `HH:MM`, default 09:00" }, "duration_min": { "type": "integer", "description": "Planned duration, minutes (default 60)", "minimum": 5, "maximum": 1440 }, "start_date": { "type": "string", "format": "date", "description": "First day of the plan" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "Last day; default depends on the recurrence" }, "tolerance_days": { "type": "integer", "description": "An audit conducted within ± this many days of the planned date counts; default depends on the frequency", "minimum": 0, "maximum": 14 }, "notify": { "type": "object", "properties": { "email": { "type": "boolean", "description": "Email the auditor about the plan" }, "day1": { "type": "boolean", "description": "Remind a day before" }, "hour1": { "type": "boolean", "description": "Remind an hour before" }, "escalate": { "type": "boolean", "description": "Notify managers about missed audits" } }, "description": "Notifications" } }, "required": [ "checklist_id", "location_ids", "auditor_id", "recur", "start_date" ] }, "example": { "title": "Replace the broken fridge seal", "checklist_id": 42, "location_ids": [ 12, 14 ], "auditor_id": 42, "recur": "none", "start_date": "2026-11-01" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "key": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recur": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "month_days": { "type": "array" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "tolerance_days": { "type": "integer" }, "notify": { "type": "object", "properties": { "email": { "type": "boolean" }, "day1": { "type": "boolean" }, "hour1": { "type": "boolean" }, "escalate": { "type": "boolean" } } }, "series_ids": { "type": "array", "items": { "type": "integer" } } } }, "scheduled": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "plan": { "key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "title": "Weekly hall check", "checklist": { "id": 5845, "name": "Daily dining room check" }, "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ], "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recur": "weekly", "weekdays": [ 1, 4 ], "month_days": [], "time": "09:00", "duration_min": 60, "start_date": "2026-11-03", "end_date": "2027-02-03", "tolerance_days": 1, "notify": { "email": true, "day1": true, "hour1": false, "escalate": true }, "series_ids": [ 1842, 1843 ] }, "scheduled": 28 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/plans/{key}": { "get": { "operationId": "plannerPlansGet", "summary": "Retrieve an audit plan", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_plans_get", "x-permissions": [ "planner.manage" ], "x-scope": "read", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Plan key (UUID, or `s` for older single-series plans)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recur": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "month_days": { "type": "array" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "tolerance_days": { "type": "integer" }, "notify": { "type": "object", "properties": { "email": { "type": "boolean" }, "day1": { "type": "boolean" }, "hour1": { "type": "boolean" }, "escalate": { "type": "boolean" } } }, "series_ids": { "type": "array", "items": { "type": "integer" } } } } }, "required": [ "data" ] }, "example": { "data": { "key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "title": "Weekly hall check", "checklist": { "id": 5845, "name": "Daily dining room check" }, "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ], "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recur": "weekly", "weekdays": [ 1, 4 ], "month_days": [], "time": "09:00", "duration_min": 60, "start_date": "2026-11-03", "end_date": "2027-02-03", "tolerance_days": 1, "notify": { "email": true, "day1": true, "hour1": false, "escalate": true }, "series_ids": [ 1842, 1843 ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "plannerPlansUpdate", "summary": "Update an audit plan", "description": "Replaces the plan settings. Past audits stay as they are; upcoming ones (from today, except done) are regenerated. Removed locations lose their series, added ones get new series. Requires `planner.manage` on the old and new locations. `upcoming` — planned audits from today.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_plans_update", "x-permissions": [ "planner.manage" ], "x-scope": "write", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Plan key (UUID, or `s` for older single-series plans)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "description": "Plan title; default \"Plan: \"", "maxLength": 255 }, "checklist_id": { "type": "integer", "description": "Checklist to audit" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Locations — one series per location", "minItems": 1 }, "auditor_id": { "type": "integer", "description": "Auditor (user id); the checklist must be available to them" }, "recur": { "type": "string", "enum": [ "none", "daily", "weekdays", "weekly", "monthly" ], "description": "`none` — once on `start_date`, `daily`, `weekdays` (Mon–Fri), `weekly` (on `weekdays`), `monthly` (on `month_days`)" }, "weekdays": { "type": "array", "items": { "type": "integer" }, "description": "For `weekly`: days of week, 0 = Sunday … 6 = Saturday" }, "month_days": { "type": "array", "items": { "type": "integer" }, "description": "For `monthly`: days of month 1–31" }, "time": { "type": "string", "description": "Start time `HH:MM`, default 09:00" }, "duration_min": { "type": "integer", "description": "Planned duration, minutes (default 60)", "minimum": 5, "maximum": 1440 }, "start_date": { "type": "string", "format": "date", "description": "First day of the plan" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "Last day; default depends on the recurrence" }, "tolerance_days": { "type": "integer", "description": "An audit conducted within ± this many days of the planned date counts; default depends on the frequency", "minimum": 0, "maximum": 14 }, "notify": { "type": "object", "properties": { "email": { "type": "boolean", "description": "Email the auditor about the plan" }, "day1": { "type": "boolean", "description": "Remind a day before" }, "hour1": { "type": "boolean", "description": "Remind an hour before" }, "escalate": { "type": "boolean", "description": "Notify managers about missed audits" } }, "description": "Notifications" } }, "required": [ "checklist_id", "location_ids", "auditor_id", "recur", "start_date" ] }, "example": { "title": "Replace the broken fridge seal", "checklist_id": 42, "location_ids": [ 12, 14 ], "auditor_id": 42, "recur": "none", "start_date": "2026-11-01" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "key": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "checklist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "auditor": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "recur": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "month_days": { "type": "array" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "tolerance_days": { "type": "integer" }, "notify": { "type": "object", "properties": { "email": { "type": "boolean" }, "day1": { "type": "boolean" }, "hour1": { "type": "boolean" }, "escalate": { "type": "boolean" } } }, "series_ids": { "type": "array", "items": { "type": "integer" } } } }, "upcoming": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "plan": { "key": "0b7c1f9e-2d4a-4f6b-8e3c-5a9d7b1c2e4f", "title": "Weekly hall check", "checklist": { "id": 5845, "name": "Daily dining room check" }, "locations": [ { "id": 12, "name": "Abay Ave" }, { "id": 14, "name": "Dostyk Plaza" } ], "auditor": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "recur": "weekly", "weekdays": [ 1, 4 ], "month_days": [], "time": "09:00", "duration_min": 60, "start_date": "2026-11-03", "end_date": "2027-02-03", "tolerance_days": 1, "notify": { "email": true, "day1": true, "hour1": false, "escalate": true }, "series_ids": [ 1842, 1843 ] }, "upcoming": 18 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "plannerPlansDelete", "summary": "Delete an audit plan", "description": "Stops the plan: its series are retired and upcoming planned audits (except done) are removed; history stays. `removed` — how many upcoming audits were removed.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_plans_delete", "x-permissions": [ "planner.manage" ], "x-scope": "write", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Plan key (UUID, or `s` for older single-series plans)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "removed": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true, "removed": 12 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/templates": { "get": { "operationId": "plannerTemplatesList", "summary": "List plan templates", "description": "Saved plan settings shared in the company, to create similar plans quickly.", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_templates_list", "x-permissions": [ "planner.manage" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "settings": { "type": "object", "properties": { "title": { "type": "string" }, "checklist_id": { "type": "integer" }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "auditor_id": { "type": "integer" }, "recur": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "month_days": { "type": "array" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "tolerance_days": { "type": "integer" }, "notify": { "type": "object", "properties": { "email": { "type": "boolean" }, "day1": { "type": "boolean" }, "hour1": { "type": "boolean" }, "escalate": { "type": "boolean" } } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 7, "name": "Weekly hall check", "settings": { "title": "Weekly hall check", "checklist_id": 5845, "location_ids": [ 12, 14 ], "auditor_id": 311, "recur": "weekly", "weekdays": [ 1, 4 ], "month_days": [], "time": "09:00", "duration_min": 60, "tolerance_days": 1, "notify": { "email": true, "day1": true, "hour1": false, "escalate": true } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "plannerTemplatesCreate", "summary": "Save a plan template", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_templates_create", "x-permissions": [ "planner.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name", "minLength": 1, "maxLength": 255 }, "settings": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "checklist_id": { "type": [ "integer", "null" ] }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "auditor_id": { "type": [ "integer", "null" ] }, "recur": { "type": [ "string", "null" ], "enum": [ "none", "daily", "weekdays", "weekly", "monthly" ] }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "month_days": { "type": "array", "items": { "type": "integer" } }, "time": { "type": [ "string", "null" ], "maxLength": 5 }, "duration_min": { "type": [ "integer", "null" ], "minimum": 5, "maximum": 1440 }, "tolerance_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 14 }, "notify": { "type": "object", "properties": {}, "additionalProperties": true } }, "description": "Any subset of the plan fields (same names as in `planner.plans.create`)" } }, "required": [ "name", "settings" ] }, "example": { "name": "Replace the broken fridge seal", "settings": { "title": "Replace the broken fridge seal", "checklist_id": 42, "location_ids": [ 12, 14 ] } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "settings": { "type": "object", "properties": { "title": { "type": "string" }, "checklist_id": { "type": "integer" }, "location_ids": { "type": "array", "items": { "type": "integer" } }, "auditor_id": { "type": "integer" }, "recur": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "month_days": { "type": "array" }, "time": { "type": "string" }, "duration_min": { "type": "integer" }, "tolerance_days": { "type": "integer" }, "notify": { "type": "object", "properties": { "email": { "type": "boolean" }, "day1": { "type": "boolean" }, "hour1": { "type": "boolean" }, "escalate": { "type": "boolean" } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Weekly hall check", "settings": { "title": "Weekly hall check", "checklist_id": 5845, "location_ids": [ 12, 14 ], "auditor_id": 311, "recur": "weekly", "weekdays": [ 1, 4 ], "month_days": [], "time": "09:00", "duration_min": 60, "tolerance_days": 1, "notify": { "email": true, "day1": true, "hour1": false, "escalate": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/planner/templates/{id}": { "delete": { "operationId": "plannerTemplatesDelete", "summary": "Delete a plan template", "tags": [ "Audit planner" ], "x-mcp-tool": "planner_templates_delete", "x-permissions": [ "planner.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes": { "get": { "operationId": "processesList", "summary": "List processes available for requests", "description": "Published processes the acting user may submit a request for, with the published form and a summary of the route.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_list", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "location_ids": { "type": [ "string", "null" ] }, "route": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "location_ids": null, "route": [ { "type": "approval", "name": "Manager approval" }, { "type": "task", "name": "Purchase" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/approvals": { "get": { "operationId": "processesApprovals", "summary": "List requests waiting for me", "description": "Requests where the acting user must approve or accept the active step (`waiting` = `approval` / `review`), or that were returned to the acting user for rework (`rework`).", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_approvals", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "waiting": { "type": "string" }, "step": { "type": "string" }, "since": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "waiting": "approval", "step": "Manager approval", "since": "2026-11-03T10:00:00+05:00", "due_at": "2026-11-04T10:00:00+05:00", "location": { "id": 12, "name": "Abay Ave" }, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/definitions": { "get": { "operationId": "processesDefinitionsList", "summary": "List all processes (library)", "description": "All processes of the company including drafts and archived ones, with request counters. Requires `processes.manage` or `processes.reports`.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_list", "x-permissions": [ "processes.manage", "processes.reports" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "has_unpublished_changes": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "open_requests": { "type": "integer" }, "total_requests": { "type": "integer" }, "avg_minutes": { "type": "integer" }, "overdue_steps": { "type": "integer" }, "fields_count": { "type": "integer" }, "route": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "status": "active", "version": 3, "has_unpublished_changes": false, "published_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-10-20T09:00:00+05:00", "open_requests": 4, "total_requests": 120, "avg_minutes": 1440, "overdue_steps": 1, "fields_count": 5, "route": [ { "type": "approval", "name": "Manager approval" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "processesDefinitionsCreate", "summary": "Create a process", "description": "Creates a draft process, empty or from a template. Publish it with `processes.definitions.publish`.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_create", "x-permissions": [ "processes.manage" ], "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "purchase", "repair", "refund", "writeoff", "advance", "access", "trip" ], "description": "Template key" } } }, "example": { "preset": "purchase" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "has_unpublished_changes": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "flow": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "approvers": { "type": "object", "properties": { "kind": { "type": "string" } } }, "rule": { "type": "string" }, "hours": { "type": "integer" } } } } } }, "settings": { "type": "object", "properties": { "submit": { "type": "object", "properties": { "mode": { "type": "string" } } }, "locations": { "type": [ "string", "null" ] }, "watchers": { "type": "array" }, "author_cancel": { "type": "boolean" }, "show_route": { "type": "boolean" } } }, "errors": { "type": "array" }, "has_requests": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "status": "active", "version": 3, "has_unpublished_changes": false, "published_at": "2026-10-20T09:00:00+05:00", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "flow": { "steps": [ { "id": "s_approve", "type": "approval", "approvers": { "kind": "manager" }, "rule": "any", "hours": 24 } ] }, "settings": { "submit": { "mode": "all" }, "locations": null, "watchers": [], "author_cancel": true, "show_route": true }, "errors": [], "has_requests": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/order": { "put": { "operationId": "processesDefinitionsReorder", "summary": "Reorder processes", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_reorder", "x-permissions": [ "processes.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "Process ids in the new order", "minItems": 1 } }, "required": [ "ids" ] }, "example": { "ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "ok": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/presets": { "get": { "operationId": "processesPresets", "summary": "List process templates", "description": "Ready-made processes to start from (`preset` in `processes.definitions.create`).", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_presets", "x-permissions": [ "processes.manage" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "fields_count": { "type": "integer" }, "route": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "key": "purchase", "name": "Purchase request", "description": "Approval and purchase", "icon": "shopping_cart", "color": "#5b54e8", "fields_count": 5, "route": [ { "type": "approval", "name": "Manager approval" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests": { "get": { "operationId": "processesRequestsList", "summary": "List requests", "description": "Requests visible to the acting user (same visibility as tasks), newest first.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "process_id", "in": "query", "description": "Only this process", "schema": { "type": "integer" } }, { "name": "state[]", "in": "query", "description": "Route state: running, returned, approved, done, rejected, cancelled", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "mine", "in": "query", "description": "Only requests submitted by the acting user", "schema": { "type": "boolean" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "date_from", "in": "query", "description": "Submitted from (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Submitted to (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "updated_since", "in": "query", "description": "Only requests changed after this moment", "schema": { "type": "string", "format": "date-time" } }, { "name": "search", "in": "query", "description": "Search in title and number", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "state": { "type": "string" }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "due_date": { "type": "string", "format": "date" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "state": "running", "process": { "id": 7, "name": "Purchase request" }, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "due_date": "2026-11-07", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "updated_at": "2026-11-03T10:05:00+05:00", "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}": { "get": { "operationId": "processesRequestsGet", "summary": "Retrieve a request and its route", "description": "Form answers (file links valid for 1 hour), the route with decisions, the steps ahead (by current answers) and what the acting user may do now (`can`).", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/cancel": { "post": { "operationId": "processesRequestsCancel", "summary": "Cancel a request", "description": "The author (if the process allows it) or a user with `processes.override` cancels an open request.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_cancel", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason", "maxLength": 1000 } } }, "example": { "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/complete": { "post": { "operationId": "processesRequestsComplete", "summary": "Complete the work step", "description": "Marks the active `task` step of the route as done; the request moves on.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_complete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment", "maxLength": 2000 } } }, "example": { "comment": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/decide": { "post": { "operationId": "processesRequestsDecide", "summary": "Approve, return or reject a request", "description": "Decision of the acting user on the active approval/review step. `return` sends the request back to the author for rework; `reject` is available on approval steps. A comment may be required on reject/return (see `can.comment_required`).", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_decide", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "return", "reject" ] }, "comment": { "type": "string", "description": "Comment", "maxLength": 2000 } }, "required": [ "decision" ] }, "example": { "decision": "approve", "comment": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/delegate": { "post": { "operationId": "processesRequestsDelegate", "summary": "Delegate my decision", "description": "Passes the acting user's decision on the active step to another employee (if the step allows delegation).", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_delegate", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Employee to delegate to" }, "comment": { "type": "string", "description": "Comment", "maxLength": 2000 } }, "required": [ "user_id" ] }, "example": { "user_id": 42, "comment": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/move": { "post": { "operationId": "processesRequestsMove", "summary": "Move a request to another step", "description": "Intervention: returns the request to a step of the route (`override_steps[].key`). Requires `processes.override`.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_move", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "string", "description": "Step key", "maxLength": 20 } }, "required": [ "step" ] }, "example": { "step": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/reassign": { "post": { "operationId": "processesRequestsReassign", "summary": "Replace people on the active step", "description": "Intervention: replaces approvers / executors of the active step. Requires `processes.override`.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_reassign", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 20 } }, "required": [ "user_ids" ] }, "example": { "user_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/resubmit": { "post": { "operationId": "processesRequestsResubmit", "summary": "Resubmit a returned request", "description": "The author sends a returned request again, optionally with corrected answers and title.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_resubmit", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Corrected answers: {\"\": value}" }, "title": { "type": "string", "maxLength": 512 } } }, "example": { "values": [], "title": "Replace the broken fridge seal" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/skip": { "post": { "operationId": "processesRequestsSkip", "summary": "Skip the active step", "description": "Intervention: skips the active step of the route. Requires `processes.override` for the request location.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_skip", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/requests/{uuid}/values": { "patch": { "operationId": "processesRequestsValues", "summary": "Edit request answers", "description": "Changes answers of an open request — allowed when `can.edit_values` is true (the author before decisions, or `processes.override`).", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_values", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Request (task) UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Answers to change: {\"\": value}" }, "title": { "type": "string", "maxLength": 512 } } }, "example": { "values": [], "title": "Replace the broken fridge seal" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/{id}": { "get": { "operationId": "processesGet", "summary": "Retrieve a process form", "description": "The published form of a process the acting user may submit. Field ids are the keys of `values` when submitting.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_get", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "location_ids": { "type": [ "string", "null" ] }, "route": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "location_ids": null, "route": [ { "type": "approval", "name": "Manager approval" }, { "type": "task", "name": "Purchase" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "processesDefinitionsDelete", "summary": "Delete a process", "description": "Only a process without requests can be deleted; otherwise archive it.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_delete", "x-permissions": [ "processes.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/{id}/archive": { "post": { "operationId": "processesDefinitionsArchive", "summary": "Archive or restore a process", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_archive", "x-permissions": [ "processes.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean", "default": true, "description": "`true` — archive, `false` — restore" } } }, "example": { "archived": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "has_unpublished_changes": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "flow": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "approvers": { "type": "object", "properties": { "kind": { "type": "string" } } }, "rule": { "type": "string" }, "hours": { "type": "integer" } } } } } }, "settings": { "type": "object", "properties": { "submit": { "type": "object", "properties": { "mode": { "type": "string" } } }, "locations": { "type": [ "string", "null" ] }, "watchers": { "type": "array" }, "author_cancel": { "type": "boolean" }, "show_route": { "type": "boolean" } } }, "errors": { "type": "array" }, "has_requests": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "status": "active", "version": 3, "has_unpublished_changes": false, "published_at": "2026-10-20T09:00:00+05:00", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "flow": { "steps": [ { "id": "s_approve", "type": "approval", "approvers": { "kind": "manager" }, "rule": "any", "hours": 24 } ] }, "settings": { "submit": { "mode": "all" }, "locations": null, "watchers": [], "author_cancel": true, "show_route": true }, "errors": [], "has_requests": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/{id}/definition": { "get": { "operationId": "processesDefinitionsGet", "summary": "Retrieve a process definition", "description": "Draft form, route and settings of a process, validation errors that block publishing and whether it has unpublished changes.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_get", "x-permissions": [ "processes.manage" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "has_unpublished_changes": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "flow": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "approvers": { "type": "object", "properties": { "kind": { "type": "string" } } }, "rule": { "type": "string" }, "hours": { "type": "integer" } } } } } }, "settings": { "type": "object", "properties": { "submit": { "type": "object", "properties": { "mode": { "type": "string" } } }, "locations": { "type": [ "string", "null" ] }, "watchers": { "type": "array" }, "author_cancel": { "type": "boolean" }, "show_route": { "type": "boolean" } } }, "errors": { "type": "array" }, "has_requests": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "status": "active", "version": 3, "has_unpublished_changes": false, "published_at": "2026-10-20T09:00:00+05:00", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "flow": { "steps": [ { "id": "s_approve", "type": "approval", "approvers": { "kind": "manager" }, "rule": "any", "hours": 24 } ] }, "settings": { "submit": { "mode": "all" }, "locations": null, "watchers": [], "author_cancel": true, "show_route": true }, "errors": [], "has_requests": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "processesDefinitionsUpdate", "summary": "Save a process draft", "description": "Replaces the draft definition. Requests keep using the published version until `processes.definitions.publish`.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_update", "x-permissions": [ "processes.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Process name", "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "icon": { "type": "string", "description": "Material Symbols icon name", "maxLength": 40 }, "color": { "type": "string", "description": "Hex color", "maxLength": 9 }, "prefix": { "type": "string", "description": "Request number prefix, e.g. `BUY` → BUY-42", "maxLength": 8 }, "form": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Request form: title mode/template, description/location/priority/due settings and `fields` (types: text, textarea, number, money, date, datetime, select, multiselect, checkbox, user, location, file, url, phone, heading, note). Same format as returned by `processes.definitions.get`" }, "flow": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Route: {\"steps\": [...]} with step types approval, task, review, condition, notify, set, watchers, finish. Conditions and timeout actions require the paid feature `processes_pro`" }, "settings": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Who may submit (`submit`), available locations, default watchers, author cancel, route visibility" } }, "required": [ "name", "form", "flow", "settings" ] }, "example": { "name": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "icon": "string", "color": "string", "form": [], "flow": [], "settings": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "has_unpublished_changes": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "flow": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "approvers": { "type": "object", "properties": { "kind": { "type": "string" } } }, "rule": { "type": "string" }, "hours": { "type": "integer" } } } } } }, "settings": { "type": "object", "properties": { "submit": { "type": "object", "properties": { "mode": { "type": "string" } } }, "locations": { "type": [ "string", "null" ] }, "watchers": { "type": "array" }, "author_cancel": { "type": "boolean" }, "show_route": { "type": "boolean" } } }, "errors": { "type": "array" }, "has_requests": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "status": "active", "version": 3, "has_unpublished_changes": false, "published_at": "2026-10-20T09:00:00+05:00", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "flow": { "steps": [ { "id": "s_approve", "type": "approval", "approvers": { "kind": "manager" }, "rule": "any", "hours": 24 } ] }, "settings": { "submit": { "mode": "all" }, "locations": null, "watchers": [], "author_cancel": true, "show_route": true }, "errors": [], "has_requests": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/{id}/duplicate": { "post": { "operationId": "processesDefinitionsDuplicate", "summary": "Duplicate a process", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_duplicate", "x-permissions": [ "processes.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "has_unpublished_changes": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "flow": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "approvers": { "type": "object", "properties": { "kind": { "type": "string" } } }, "rule": { "type": "string" }, "hours": { "type": "integer" } } } } } }, "settings": { "type": "object", "properties": { "submit": { "type": "object", "properties": { "mode": { "type": "string" } } }, "locations": { "type": [ "string", "null" ] }, "watchers": { "type": "array" }, "author_cancel": { "type": "boolean" }, "show_route": { "type": "boolean" } } }, "errors": { "type": "array" }, "has_requests": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "status": "active", "version": 3, "has_unpublished_changes": false, "published_at": "2026-10-20T09:00:00+05:00", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "flow": { "steps": [ { "id": "s_approve", "type": "approval", "approvers": { "kind": "manager" }, "rule": "any", "hours": 24 } ] }, "settings": { "submit": { "mode": "all" }, "locations": null, "watchers": [], "author_cancel": true, "show_route": true }, "errors": [], "has_requests": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/{id}/publish": { "post": { "operationId": "processesDefinitionsPublish", "summary": "Publish a process", "description": "Validates and publishes the draft; new requests use the new version. Returns 422 with the list of problems if the definition is not valid.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_definitions_publish", "x-permissions": [ "processes.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "has_unpublished_changes": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "form": { "type": "object", "properties": { "title": { "type": "object", "properties": { "mode": { "type": "string" }, "template": { "type": "string" } } }, "description": { "type": "boolean" }, "location": { "type": "string" }, "priority": { "type": "string" }, "priority_value": { "type": "string" }, "due": { "type": "string" }, "sla_hours": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "photo": { "type": "boolean" } } } } } }, "flow": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "approvers": { "type": "object", "properties": { "kind": { "type": "string" } } }, "rule": { "type": "string" }, "hours": { "type": "integer" } } } } } }, "settings": { "type": "object", "properties": { "submit": { "type": "object", "properties": { "mode": { "type": "string" } } }, "locations": { "type": [ "string", "null" ] }, "watchers": { "type": "array" }, "author_cancel": { "type": "boolean" }, "show_route": { "type": "boolean" } } }, "errors": { "type": "array" }, "has_requests": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 7, "name": "Purchase request", "description": "Buying equipment and supplies", "icon": "shopping_cart", "color": "#5b54e8", "prefix": "BUY", "status": "active", "version": 3, "has_unpublished_changes": false, "published_at": "2026-10-20T09:00:00+05:00", "form": { "title": { "mode": "template", "template": "{process} {number}: {f_item}" }, "description": true, "location": "required", "priority": "input", "priority_value": "medium", "due": "input", "sla_hours": null, "fields": [ { "id": "f_item", "type": "text", "label": "What to buy", "required": true }, { "id": "f_sum", "type": "money", "label": "Amount", "required": true }, { "id": "f_invoice", "type": "file", "label": "Invoice", "required": false, "photo": false } ] }, "flow": { "steps": [ { "id": "s_approve", "type": "approval", "approvers": { "kind": "manager" }, "rule": "any", "hours": 24 } ] }, "settings": { "submit": { "mode": "all" }, "locations": null, "watchers": [], "author_cancel": true, "show_route": true }, "errors": [], "has_requests": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/{id}/requests": { "post": { "operationId": "processesRequestsCreate", "summary": "Submit a request", "description": "Creates a request (a task with an approval route) by the published form. `values` — answers by field id. Files for `file` fields: multipart `files[]` (in MCP — objects with `name` and `content_base64`) plus `file_fields[]` with the field id of each file; if the form has one file field, `file_fields` may be omitted. Repeating the call with the same `client_uuid` returns the same request.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_requests_create", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title (when the form asks for it; otherwise generated by the template)", "maxLength": 512 }, "description": { "type": "string", "description": "Description (when the form has it)", "maxLength": 20000 }, "location_id": { "type": [ "integer", "null" ], "description": "Location (required if the form says so)" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date (when the form asks for it)" }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low" ], "description": "Priority (when the form lets the author choose)" }, "values": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Answers: {\"\": value}" }, "watcher_ids": { "type": "array", "items": { "type": "integer" }, "description": "Additional watchers", "maxItems": 50 }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Files for `file` fields", "maxItems": 10 }, "file_fields": { "type": "array", "items": { "type": "string" }, "description": "Field id for each file in `files` (same order)", "maxItems": 10 }, "client_uuid": { "type": "string", "format": "uuid", "description": "Idempotency key" } } } }, "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title (when the form asks for it; otherwise generated by the template)", "maxLength": 512 }, "description": { "type": "string", "description": "Description (when the form has it)", "maxLength": 20000 }, "location_id": { "type": [ "integer", "null" ], "description": "Location (required if the form says so)" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date (when the form asks for it)" }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low" ], "description": "Priority (when the form lets the author choose)" }, "values": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Answers: {\"\": value}" }, "watcher_ids": { "type": "array", "items": { "type": "integer" }, "description": "Additional watchers", "maxItems": 50 }, "files": { "type": "array", "items": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } } }, "description": "Files for `file` fields", "maxItems": 10 }, "file_fields": { "type": "array", "items": { "type": "string" }, "description": "Field id for each file in `files` (same order)", "maxItems": 10 }, "client_uuid": { "type": "string", "format": "uuid", "description": "Idempotency key" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "process": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" } } }, "version": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array" } } } }, "route": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "rule": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "decision": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "delegated_from": { "type": [ "string", "null" ] } } } } } } }, "ahead": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } }, "active_step": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "rule": { "type": "string" }, "mine": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ] }, "require_photo": { "type": "boolean" } } }, "can": { "type": "object", "properties": { "decide": { "type": "boolean" }, "delegate": { "type": "boolean" }, "reject": { "type": "boolean" }, "comment_required": { "type": "boolean" }, "complete": { "type": "boolean" }, "resubmit": { "type": "boolean" }, "cancel": { "type": "boolean" }, "edit_values": { "type": "boolean" }, "override": { "type": "boolean" }, "move_to": { "type": "boolean" } } }, "override_steps": { "type": "array" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "status": "approval", "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 12, "name": "Abay Ave" }, "process": { "id": 7, "name": "Purchase request", "icon": "shopping_cart", "color": "#5b54e8" }, "version": 3, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "values": [ { "id": "f_item", "label": "What to buy", "type": "text", "value": "Coffee grinder", "text": "Coffee grinder", "files": [] }, { "id": "f_invoice", "label": "Invoice", "type": "file", "value": [ 77 ], "text": "1", "files": [ { "id": 77, "name": "invoice.pdf", "is_image": false, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…" } ] } ], "route": [ { "id": 901, "key": "s_approve", "type": "approval", "name": "Manager approval", "state": "active", "rule": "any", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null, "due_at": "2026-11-04T10:00:00+05:00", "overdue": false, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "decision": null, "comment": null, "decided_at": null, "delegated_from": null } ] } ], "ahead": [ { "key": "s_buy", "type": "task", "name": "Purchase", "users": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ] } ], "active_step": { "id": 901, "type": "approval", "name": "Manager approval", "rule": "any", "mine": true, "instructions": null, "require_photo": false }, "can": { "decide": true, "delegate": true, "reject": true, "comment_required": true, "complete": false, "resubmit": false, "cancel": false, "edit_values": false, "override": false, "move_to": false }, "override_steps": [], "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/processes/{id}/stats": { "get": { "operationId": "processesStats", "summary": "Get process analytics", "description": "Requests by state, durations (average and median), time per stage, slowest approvers, who has requests waiting, by location and by week, recent requests. Limited to the locations of `processes.reports`.", "tags": [ "Processes & requests" ], "x-mcp-tool": "processes_stats", "x-permissions": [ "processes.reports" ], "x-plan-feature": "processes_pro", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Process id", "schema": { "type": "integer" } }, { "name": "days", "in": "query", "description": "Period, days", "schema": { "type": "integer", "enum": [ 7, 30, 90, 365 ], "default": 90 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "days": { "type": "integer" }, "total": { "type": "integer" }, "states": { "type": "object", "properties": { "done": { "type": "integer" }, "running": { "type": "integer" }, "rejected": { "type": "integer" } } }, "avg_minutes": { "type": "integer" }, "median_minutes": { "type": "integer" }, "overdue_steps": { "type": "integer" }, "rejected_share": { "type": "integer" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "count": { "type": "integer" }, "avg_minutes": { "type": "integer" }, "late": { "type": "integer" }, "returned": { "type": "integer" }, "rejected": { "type": "integer" } } } }, "approvers": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "count": { "type": "integer" }, "avg_minutes": { "type": "integer" }, "rejected": { "type": "integer" }, "returned": { "type": "integer" } } } }, "waiting": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "count": { "type": "integer" }, "oldest": { "type": "string", "format": "date-time" } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "count": { "type": "integer" }, "open": { "type": "integer" } } } }, "weeks": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string" }, "from": { "type": "string", "format": "date" }, "count": { "type": "integer" } } } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "title": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ] } } } } } } }, "required": [ "data" ] }, "example": { "data": { "days": 90, "total": 120, "states": { "done": 100, "running": 12, "rejected": 8 }, "avg_minutes": 1440, "median_minutes": 900, "overdue_steps": 1, "rejected_share": 7, "stages": [ { "key": "s_approve", "name": "Manager approval", "type": "approval", "count": 118, "avg_minutes": 300, "late": 4, "returned": 6, "rejected": 8 } ], "approvers": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "count": 50, "avg_minutes": 420, "rejected": 3, "returned": 2 } ], "waiting": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "count": 3, "oldest": "2026-11-01T09:00:00+05:00" } ], "locations": [ { "location": { "id": 12, "name": "Abay Ave" }, "count": 40, "open": 3 } ], "weeks": [ { "week": "2026-44", "from": "2026-10-26", "count": 9 } ], "recent": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "number": "BUY-42", "title": "Purchase request BUY-42: coffee grinder", "location": { "id": 12, "name": "Abay Ave" }, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "state": "running", "started_at": "2026-11-03T10:00:00+05:00", "finished_at": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects": { "get": { "operationId": "projectsList", "summary": "List projects", "description": "Projects the token can open: where it is a member or owner, projects open to the whole company, and with `projects.manage` — all projects. Ordered by status (active first), then by last change.", "tags": [ "Projects" ], "x-mcp-tool": "projects_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "status[]", "in": "query", "description": "Filter by status: active, paused, done, archived", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "starred", "in": "query", "description": "Only projects starred by the acting user", "schema": { "type": "boolean" } }, { "name": "member", "in": "query", "description": "Only projects where the acting user is a member or owner", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search in name and key", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "visibility": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "progress": { "type": "integer" } } }, "members_count": { "type": "integer" }, "guests_count": { "type": "integer" }, "starred": { "type": "boolean" }, "last_update_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave", "description": "Launch of the new coffee shop on Abay Ave.", "icon": "rocket_launch", "color": "#5b54e8", "status": "active", "health": "on_track", "visibility": "members", "start_date": "2026-11-01", "due_date": "2026-12-15", "owner": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin", "created_at": "2026-10-28T09:00:00+05:00", "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/projects/8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "progress": 44 }, "members_count": 6, "guests_count": 1, "starred": true, "last_update_at": "2026-11-02T18:00:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "projectsCreate", "summary": "Create a project", "description": "Creates a project, empty or from a template (see `projects.templates.list`). The creator and the owner become project admins. Requires `projects.create`.", "tags": [ "Projects" ], "x-mcp-tool": "projects_create", "x-permissions": [ "projects.create" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name", "minLength": 2, "maxLength": 200 }, "key": { "type": "string", "description": "Task number prefix: 2–10 Latin letters/digits starting with a letter (e.g. `OPEN`). Generated from the name if omitted", "maxLength": 10 }, "description": { "type": [ "string", "null" ], "description": "Description", "maxLength": 20000 }, "icon": { "type": "string", "description": "Material Symbols icon name, e.g. `rocket_launch`", "maxLength": 40 }, "color": { "type": "string", "description": "Hex color, e.g. `#5b54e8`", "maxLength": 9 }, "visibility": { "type": "string", "enum": [ "members", "company" ], "description": "`members` — only members see the project; `company` — every employee can open it and join" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date" }, "owner_id": { "type": "integer", "description": "Owner (user id); always an admin of the project" }, "template": { "type": "string", "description": "Template id: a built-in template key or a company template UUID", "maxLength": 64 }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "User id" }, "role": { "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "description": "Project role, default `editor`" } }, "required": [ "user_id" ] }, "description": "Members to add", "maxItems": 200 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "key": "string", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "icon": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "visibility": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "completed_at": { "type": [ "string", "null" ] }, "starred": { "type": "boolean" }, "settings": { "type": "object", "properties": { "guest_scope": { "type": "string" }, "time_tracking": { "type": "boolean" } } }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "comment": { "type": "boolean" }, "manage": { "type": "boolean" }, "invite_guests": { "type": "boolean" }, "join": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } }, "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave", "description": "Launch of the new coffee shop on Abay Ave.", "icon": "rocket_launch", "color": "#5b54e8", "status": "active", "health": "on_track", "visibility": "members", "start_date": "2026-11-01", "due_date": "2026-12-15", "owner": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin", "created_at": "2026-10-28T09:00:00+05:00", "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/projects/8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "completed_at": null, "starred": true, "settings": { "guest_scope": "all", "time_tracking": true }, "permissions": { "edit": true, "comment": true, "manage": true, "invite_guests": true, "join": false }, "sections": [ { "id": 201, "name": "Equipment" } ], "columns": [ { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } ], "milestones": [ { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } ], "fields": [ { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } ], "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin" } ], "guests": [ { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } ], "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "unassigned": 2, "progress": 44, "forecast": "2026-12-20" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/tasks/{uuid}": { "get": { "operationId": "projectsTasksGet", "summary": "Get the project part of a task", "description": "Project-specific data of a task: section, column, milestone, custom field values, guests, links to other tasks and time logs.", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID (the task must belong to a project)", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "task_uuid": { "type": "string", "format": "uuid" }, "project": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "section_id": { "type": "integer" }, "column_id": { "type": "integer" }, "milestone_id": { "type": "integer" }, "fields": { "type": "object", "properties": { "501": { "type": "string" } } }, "guest_ids": { "type": "array", "items": { "type": "integer" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "due_date": { "type": "string", "format": "date" } } } } } }, "time_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "minutes": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest_name": { "type": [ "string", "null" ] } } } }, "spent_minutes": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "project": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave" }, "role": "editor", "section_id": 201, "column_id": 301, "milestone_id": 401, "fields": { "501": "o_k2m9qa" }, "guest_ids": [ 12 ], "links": [ { "id": 77, "type": "blocked_by", "task": { "uuid": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d", "key": "OPEN-9", "title": "Deliver the machine", "status": "done", "due_date": "2026-11-05" } } ], "time_logs": [ { "id": 901, "minutes": 90, "date": "2026-11-03", "note": "Plumbing", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest_name": null } ], "spent_minutes": 90 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "projectsTasksUpdate", "summary": "Update the project part of a task", "description": "Sets section, milestone, board column, custom field values (`fields`: field id → value; `null` clears; select — option id, multiselect — array of option ids, user — user id) and assigned guests. Requires the editor role.", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID (the task must belong to a project)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section_id": { "type": [ "integer", "null" ] }, "milestone_id": { "type": [ "integer", "null" ] }, "column_id": { "type": "integer", "description": "Board column (changes the status as on the board)" }, "fields": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Custom field values: {\"\": value}" }, "guest_ids": { "type": "array", "items": { "type": "integer" }, "description": "Project guests assigned to the task (replaces the list)", "maxItems": 20 } } }, "example": { "section_id": 42, "milestone_id": 42, "column_id": 42, "fields": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "task_uuid": { "type": "string", "format": "uuid" }, "project": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "section_id": { "type": "integer" }, "column_id": { "type": "integer" }, "milestone_id": { "type": "integer" }, "fields": { "type": "object", "properties": { "501": { "type": "string" } } }, "guest_ids": { "type": "array", "items": { "type": "integer" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "due_date": { "type": "string", "format": "date" } } } } } }, "time_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "minutes": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest_name": { "type": [ "string", "null" ] } } } }, "spent_minutes": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "project": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave" }, "role": "editor", "section_id": 201, "column_id": 301, "milestone_id": 401, "fields": { "501": "o_k2m9qa" }, "guest_ids": [ 12 ], "links": [ { "id": 77, "type": "blocked_by", "task": { "uuid": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d", "key": "OPEN-9", "title": "Deliver the machine", "status": "done", "due_date": "2026-11-05" } } ], "time_logs": [ { "id": 901, "minutes": 90, "date": "2026-11-03", "note": "Plumbing", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest_name": null } ], "spent_minutes": 90 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/tasks/{uuid}/links": { "post": { "operationId": "projectsTasksLinksCreate", "summary": "Link two tasks", "description": "Adds a dependency or relation: `blocks`, `blocked_by`, `relates`, `duplicates`. Cycles of `blocks` are rejected.", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_links_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID (the task must belong to a project)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "other_uuid": { "type": "string", "format": "uuid", "description": "The other task UUID" }, "type": { "type": "string", "enum": [ "blocks", "blocked_by", "relates", "duplicates" ] } }, "required": [ "other_uuid", "type" ] }, "example": { "other_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "type": "blocks" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "task_uuid": { "type": "string", "format": "uuid" }, "project": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "section_id": { "type": "integer" }, "column_id": { "type": "integer" }, "milestone_id": { "type": "integer" }, "fields": { "type": "object", "properties": { "501": { "type": "string" } } }, "guest_ids": { "type": "array", "items": { "type": "integer" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "due_date": { "type": "string", "format": "date" } } } } } }, "time_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "minutes": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest_name": { "type": [ "string", "null" ] } } } }, "spent_minutes": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "project": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave" }, "role": "editor", "section_id": 201, "column_id": 301, "milestone_id": 401, "fields": { "501": "o_k2m9qa" }, "guest_ids": [ 12 ], "links": [ { "id": 77, "type": "blocked_by", "task": { "uuid": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d", "key": "OPEN-9", "title": "Deliver the machine", "status": "done", "due_date": "2026-11-05" } } ], "time_logs": [ { "id": 901, "minutes": 90, "date": "2026-11-03", "note": "Plumbing", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest_name": null } ], "spent_minutes": 90 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/tasks/{uuid}/links/{id}": { "delete": { "operationId": "projectsTasksLinksDelete", "summary": "Remove a task link", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_links_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID (the task must belong to a project)", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Link id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/tasks/{uuid}/time": { "post": { "operationId": "projectsTasksTimeCreate", "summary": "Log time on a task", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_time_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID (the task must belong to a project)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minutes": { "type": "integer", "description": "Minutes spent (1–1440)", "minimum": 1, "maximum": 1440 }, "date": { "type": "string", "format": "date", "description": "Day of work, default today" }, "note": { "type": "string", "description": "Note", "maxLength": 500 } }, "required": [ "minutes" ] }, "example": { "minutes": 42, "date": "2026-11-01", "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "task_uuid": { "type": "string", "format": "uuid" }, "project": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "section_id": { "type": "integer" }, "column_id": { "type": "integer" }, "milestone_id": { "type": "integer" }, "fields": { "type": "object", "properties": { "501": { "type": "string" } } }, "guest_ids": { "type": "array", "items": { "type": "integer" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "due_date": { "type": "string", "format": "date" } } } } } }, "time_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "minutes": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest_name": { "type": [ "string", "null" ] } } } }, "spent_minutes": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "project": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave" }, "role": "editor", "section_id": 201, "column_id": 301, "milestone_id": 401, "fields": { "501": "o_k2m9qa" }, "guest_ids": [ 12 ], "links": [ { "id": 77, "type": "blocked_by", "task": { "uuid": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d", "key": "OPEN-9", "title": "Deliver the machine", "status": "done", "due_date": "2026-11-05" } } ], "time_logs": [ { "id": 901, "minutes": 90, "date": "2026-11-03", "note": "Plumbing", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest_name": null } ], "spent_minutes": 90 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/tasks/{uuid}/time/{id}": { "delete": { "operationId": "projectsTasksTimeDelete", "summary": "Delete a time log", "description": "Own time logs can be deleted by their author; any — by project admins.", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_time_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID (the task must belong to a project)", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Time log id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/templates": { "get": { "operationId": "projectsTemplatesList", "summary": "List project templates", "description": "Built-in templates and the company's own templates (saved from projects). Pass the template `id` as `template` when creating a project. Company templates are listed only with `projects.create`.", "tags": [ "Projects" ], "x-mcp-tool": "projects_templates_list", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "company": { "type": "boolean" }, "tasks_count": { "type": "integer" }, "days": { "type": "integer" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "opening", "name": "Opening a new location", "description": "Everything from lease to soft opening", "icon": "storefront", "company": false, "tasks_count": 34, "days": 60 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/templates/{template_uuid}": { "delete": { "operationId": "projectsTemplatesDelete", "summary": "Delete a company template", "tags": [ "Projects" ], "x-mcp-tool": "projects_templates_delete", "x-scope": "write", "parameters": [ { "name": "template_uuid", "in": "path", "required": true, "description": "Company template UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}": { "get": { "operationId": "projectsGet", "summary": "Retrieve a project", "description": "Project card with the acting user's role and permissions, sections, board columns, milestones, custom fields, members, guests (only for project admins with `projects.guests`) and progress figures.", "tags": [ "Projects" ], "x-mcp-tool": "projects_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "visibility": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "completed_at": { "type": [ "string", "null" ] }, "starred": { "type": "boolean" }, "settings": { "type": "object", "properties": { "guest_scope": { "type": "string" }, "time_tracking": { "type": "boolean" } } }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "comment": { "type": "boolean" }, "manage": { "type": "boolean" }, "invite_guests": { "type": "boolean" }, "join": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } }, "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave", "description": "Launch of the new coffee shop on Abay Ave.", "icon": "rocket_launch", "color": "#5b54e8", "status": "active", "health": "on_track", "visibility": "members", "start_date": "2026-11-01", "due_date": "2026-12-15", "owner": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin", "created_at": "2026-10-28T09:00:00+05:00", "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/projects/8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "completed_at": null, "starred": true, "settings": { "guest_scope": "all", "time_tracking": true }, "permissions": { "edit": true, "comment": true, "manage": true, "invite_guests": true, "join": false }, "sections": [ { "id": 201, "name": "Equipment" } ], "columns": [ { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } ], "milestones": [ { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } ], "fields": [ { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } ], "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin" } ], "guests": [ { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } ], "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "unassigned": 2, "progress": 44, "forecast": "2026-12-20" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "projectsUpdate", "summary": "Update a project", "description": "Partial update of project settings. Requires the admin role in the project (or `projects.manage`). Setting `status` to `done` stamps the completion time.", "tags": [ "Projects" ], "x-mcp-tool": "projects_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name", "minLength": 2, "maxLength": 200 }, "key": { "type": "string", "description": "Task number prefix: 2–10 Latin letters/digits starting with a letter (e.g. `OPEN`). Generated from the name if omitted", "maxLength": 10 }, "description": { "type": [ "string", "null" ], "description": "Description", "maxLength": 20000 }, "icon": { "type": "string", "description": "Material Symbols icon name, e.g. `rocket_launch`", "maxLength": 40 }, "color": { "type": "string", "description": "Hex color, e.g. `#5b54e8`", "maxLength": 9 }, "visibility": { "type": "string", "enum": [ "members", "company" ], "description": "`members` — only members see the project; `company` — every employee can open it and join" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date" }, "owner_id": { "type": "integer", "description": "Owner (user id); always an admin of the project" }, "status": { "type": "string", "enum": [ "active", "paused", "done", "archived" ], "description": "Project status" }, "health": { "type": [ "string", "null" ], "enum": [ "on_track", "at_risk", "off_track" ], "description": "Health indicator" }, "guest_scope": { "type": "string", "enum": [ "all", "assigned" ], "description": "What guests see: all tasks or only tasks assigned to them" }, "time_tracking": { "type": "boolean", "description": "Enable time logging in tasks" } } }, "example": { "name": "Replace the broken fridge seal", "key": "string", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "icon": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "visibility": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "completed_at": { "type": [ "string", "null" ] }, "starred": { "type": "boolean" }, "settings": { "type": "object", "properties": { "guest_scope": { "type": "string" }, "time_tracking": { "type": "boolean" } } }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "comment": { "type": "boolean" }, "manage": { "type": "boolean" }, "invite_guests": { "type": "boolean" }, "join": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } }, "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave", "description": "Launch of the new coffee shop on Abay Ave.", "icon": "rocket_launch", "color": "#5b54e8", "status": "active", "health": "on_track", "visibility": "members", "start_date": "2026-11-01", "due_date": "2026-12-15", "owner": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin", "created_at": "2026-10-28T09:00:00+05:00", "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/projects/8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "completed_at": null, "starred": true, "settings": { "guest_scope": "all", "time_tracking": true }, "permissions": { "edit": true, "comment": true, "manage": true, "invite_guests": true, "join": false }, "sections": [ { "id": 201, "name": "Equipment" } ], "columns": [ { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } ], "milestones": [ { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } ], "fields": [ { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } ], "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin" } ], "guests": [ { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } ], "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "unassigned": 2, "progress": 44, "forecast": "2026-12-20" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsDelete", "summary": "Delete a project", "description": "Deletes the project together with its tasks (soft delete) and revokes guest links. Requires the admin role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/activity": { "get": { "operationId": "projectsActivity", "summary": "List project activity", "description": "Latest project and task events (up to 60), newest first. Page back with `before` = `at` of the last event.", "tags": [ "Projects" ], "x-mcp-tool": "projects_activity", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "before", "in": "query", "description": "Only events before this moment", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "type": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest_name": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" } } }, "at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "scope": "task", "type": "status", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest_name": null, "payload": { "from": "new", "to": "in_progress" }, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPEN-12", "title": "Install the espresso machine" }, "at": "2026-11-03T12:01:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/archive": { "post": { "operationId": "projectsArchive", "summary": "Archive a project", "description": "Moves the project to the archive (status `archived`). Restore it with `projects.update` and `status: active`. Requires the admin role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_archive", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "visibility": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "completed_at": { "type": [ "string", "null" ] }, "starred": { "type": "boolean" }, "settings": { "type": "object", "properties": { "guest_scope": { "type": "string" }, "time_tracking": { "type": "boolean" } } }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "comment": { "type": "boolean" }, "manage": { "type": "boolean" }, "invite_guests": { "type": "boolean" }, "join": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } }, "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave", "description": "Launch of the new coffee shop on Abay Ave.", "icon": "rocket_launch", "color": "#5b54e8", "status": "active", "health": "on_track", "visibility": "members", "start_date": "2026-11-01", "due_date": "2026-12-15", "owner": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin", "created_at": "2026-10-28T09:00:00+05:00", "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/projects/8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "completed_at": null, "starred": true, "settings": { "guest_scope": "all", "time_tracking": true }, "permissions": { "edit": true, "comment": true, "manage": true, "invite_guests": true, "join": false }, "sections": [ { "id": 201, "name": "Equipment" } ], "columns": [ { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } ], "milestones": [ { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } ], "fields": [ { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } ], "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin" } ], "guests": [ { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } ], "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "unassigned": 2, "progress": 44, "forecast": "2026-12-20" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/columns": { "post": { "operationId": "projectsColumnsCreate", "summary": "Create a column", "description": "Adds a column to the project. Requires the admin role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_columns_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Column name", "minLength": 1, "maxLength": 60 }, "status": { "type": "string", "enum": [ "new", "in_progress", "review", "done", "rejected" ], "description": "Task status the column stands for" }, "color": { "type": [ "string", "null" ], "description": "Hex color", "maxLength": 9 }, "wip_limit": { "type": [ "integer", "null" ], "description": "Work-in-progress limit", "minimum": 1, "maximum": 999 } }, "required": [ "name", "status" ] }, "example": { "name": "Replace the broken fridge seal", "status": "new", "color": "string", "wip_limit": 42 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/columns/order": { "put": { "operationId": "projectsColumnsReorder", "summary": "Reorder columns", "tags": [ "Projects" ], "x-mcp-tool": "projects_columns_reorder", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "All ids in the new order", "minItems": 1 } }, "required": [ "ids" ] }, "example": { "ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/columns/{id}": { "patch": { "operationId": "projectsColumnsUpdate", "summary": "Update a column", "description": "Changing the column status moves its tasks to that status (normal status change with notifications).", "tags": [ "Projects" ], "x-mcp-tool": "projects_columns_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Board column id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Column name", "minLength": 1, "maxLength": 60 }, "status": { "type": "string", "enum": [ "new", "in_progress", "review", "done", "rejected" ], "description": "Task status the column stands for" }, "color": { "type": [ "string", "null" ], "description": "Hex color", "maxLength": 9 }, "wip_limit": { "type": [ "integer", "null" ], "description": "Work-in-progress limit", "minimum": 1, "maximum": 999 } } }, "example": { "name": "Replace the broken fridge seal", "status": "new", "color": "string", "wip_limit": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsColumnsDelete", "summary": "Delete a column", "description": "Tasks of the column move to `move_to_id` (or a column with the same status). The last column cannot be deleted.", "tags": [ "Projects" ], "x-mcp-tool": "projects_columns_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Board column id", "schema": { "type": "integer" } }, { "name": "move_to_id", "in": "query", "description": "Where to move its tasks", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/duplicate": { "post": { "operationId": "projectsDuplicate", "summary": "Duplicate a project", "description": "Creates a copy with the same structure and, optionally, tasks (dates shift relative to the new start date) and people. Requires `projects.create`.", "tags": [ "Projects" ], "x-mcp-tool": "projects_duplicate", "x-permissions": [ "projects.create" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the copy, default \" (copy)\"", "minLength": 2, "maxLength": 200 }, "start_date": { "type": "string", "format": "date", "description": "Start date of the copy, default today" }, "tasks": { "type": "boolean", "default": true, "description": "Copy tasks" }, "people": { "type": "boolean", "default": false, "description": "Keep assignees in copied tasks" } } }, "example": { "name": "Replace the broken fridge seal", "start_date": "2026-11-01", "tasks": true, "people": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "visibility": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "completed_at": { "type": [ "string", "null" ] }, "starred": { "type": "boolean" }, "settings": { "type": "object", "properties": { "guest_scope": { "type": "string" }, "time_tracking": { "type": "boolean" } } }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "comment": { "type": "boolean" }, "manage": { "type": "boolean" }, "invite_guests": { "type": "boolean" }, "join": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } }, "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave", "description": "Launch of the new coffee shop on Abay Ave.", "icon": "rocket_launch", "color": "#5b54e8", "status": "active", "health": "on_track", "visibility": "members", "start_date": "2026-11-01", "due_date": "2026-12-15", "owner": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin", "created_at": "2026-10-28T09:00:00+05:00", "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/projects/8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "completed_at": null, "starred": true, "settings": { "guest_scope": "all", "time_tracking": true }, "permissions": { "edit": true, "comment": true, "manage": true, "invite_guests": true, "join": false }, "sections": [ { "id": 201, "name": "Equipment" } ], "columns": [ { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } ], "milestones": [ { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } ], "fields": [ { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } ], "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin" } ], "guests": [ { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } ], "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "unassigned": 2, "progress": 44, "forecast": "2026-12-20" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/fields": { "post": { "operationId": "projectsFieldsCreate", "summary": "Create a field", "description": "Adds a field to the project. Requires the admin role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_fields_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name", "minLength": 1, "maxLength": 80 }, "type": { "type": "string", "enum": [ "text", "number", "money", "select", "multiselect", "date", "checkbox", "user", "url" ], "description": "Field type (cannot be changed later)" }, "options": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Existing option id (keep it to preserve values)" }, "label": { "type": "string", "maxLength": 60 }, "color": { "type": "string", "maxLength": 9 } }, "required": [ "label" ] }, "description": "Options for select / multiselect (replaces the list)", "maxItems": 50 }, "on_card": { "type": "boolean", "description": "Show on the board card" } }, "required": [ "name", "type" ] }, "example": { "name": "Replace the broken fridge seal", "type": "text", "options": [ { "id": "string", "label": "string", "color": "string" } ], "on_card": true } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/fields/order": { "put": { "operationId": "projectsFieldsReorder", "summary": "Reorder fields", "tags": [ "Projects" ], "x-mcp-tool": "projects_fields_reorder", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "All ids in the new order", "minItems": 1 } }, "required": [ "ids" ] }, "example": { "ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/fields/{id}": { "patch": { "operationId": "projectsFieldsUpdate", "summary": "Update a field", "description": "Partial update. Requires the admin role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_fields_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Custom field id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name", "minLength": 1, "maxLength": 80 }, "options": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Existing option id (keep it to preserve values)" }, "label": { "type": "string", "maxLength": 60 }, "color": { "type": "string", "maxLength": 9 } }, "required": [ "label" ] }, "description": "Options for select / multiselect (replaces the list)", "maxItems": 50 }, "on_card": { "type": "boolean", "description": "Show on the board card" } } }, "example": { "name": "Replace the broken fridge seal", "options": [ { "id": "string", "label": "string", "color": "string" } ], "on_card": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsFieldsDelete", "summary": "Delete a field", "description": "Deletes the field and its values in all tasks.", "tags": [ "Projects" ], "x-mcp-tool": "projects_fields_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Custom field id", "schema": { "type": "integer" } }, { "name": "move_to_id", "in": "query", "description": "Where to move its tasks", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/guests": { "get": { "operationId": "projectsGuestsList", "summary": "List project guests", "description": "External participants with personal links (`url` gives access without an account — keep it secret). Requires the admin role in the project and `projects.guests`.", "tags": [ "Projects" ], "x-mcp-tool": "projects_guests_list", "x-permissions": [ "projects.guests" ], "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "projectsGuestsInvite", "summary": "Invite a project guest", "description": "Invites a contractor or client by e-mail: they get a personal link to the project (up to 50 guests per project). Requires the admin role in the project and `projects.guests`.", "tags": [ "Projects" ], "x-mcp-tool": "projects_guests_invite", "x-permissions": [ "projects.guests" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Guest name", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "description": "Guest e-mail", "maxLength": 190 }, "company": { "type": "string", "description": "Guest company", "maxLength": 120 }, "role": { "type": "string", "enum": [ "editor", "commenter", "viewer" ], "default": "editor", "description": "Guest role" }, "message": { "type": "string", "description": "Personal message in the invitation", "maxLength": 2000 }, "locale": { "type": "string", "description": "Invitation language (ru, en, kk, …), default — company language", "maxLength": 5 }, "send": { "type": "boolean", "default": true, "description": "Send the invitation e-mail" } }, "required": [ "name", "email" ] }, "example": { "name": "Replace the broken fridge seal", "email": "anna@example.com", "company": "string", "role": "editor" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/guests/{guest_id}": { "patch": { "operationId": "projectsGuestsUpdate", "summary": "Update a project guest", "description": "Changes the role, name or company; `resend` re-sends the invitation, `rotate` issues a new link (the old one stops working).", "tags": [ "Projects" ], "x-mcp-tool": "projects_guests_update", "x-permissions": [ "projects.guests" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "guest_id", "in": "path", "required": true, "description": "Guest id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "editor", "commenter", "viewer" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "company": { "type": [ "string", "null" ], "maxLength": 120 }, "resend": { "type": "boolean", "description": "Re-send the invitation e-mail" }, "rotate": { "type": "boolean", "description": "Issue a new personal link" } } }, "example": { "role": "editor", "name": "Replace the broken fridge seal", "company": "string", "resend": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsGuestsRevoke", "summary": "Revoke a guest link", "tags": [ "Projects" ], "x-mcp-tool": "projects_guests_revoke", "x-permissions": [ "projects.guests" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "guest_id", "in": "path", "required": true, "description": "Guest id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/join": { "post": { "operationId": "projectsJoin", "summary": "Join a project", "description": "Joins a project open to the whole company as an editor.", "tags": [ "Projects" ], "x-mcp-tool": "projects_join", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string" }, "health": { "type": "string" }, "visibility": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "completed_at": { "type": [ "string", "null" ] }, "starred": { "type": "boolean" }, "settings": { "type": "object", "properties": { "guest_scope": { "type": "string" }, "time_tracking": { "type": "boolean" } } }, "permissions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "comment": { "type": "boolean" }, "manage": { "type": "boolean" }, "invite_guests": { "type": "boolean" }, "join": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "wip_limit": { "type": "integer" } } } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "on_card": { "type": "boolean" } } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } }, "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "tasks_count": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "invited_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "key": "OPEN", "name": "Opening: Abay Ave", "description": "Launch of the new coffee shop on Abay Ave.", "icon": "rocket_launch", "color": "#5b54e8", "status": "active", "health": "on_track", "visibility": "members", "start_date": "2026-11-01", "due_date": "2026-12-15", "owner": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin", "created_at": "2026-10-28T09:00:00+05:00", "updated_at": "2026-11-03T12:10:00+05:00", "url": "https://app.jecheck.io/ui/projects/8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "completed_at": null, "starred": true, "settings": { "guest_scope": "all", "time_tracking": true }, "permissions": { "edit": true, "comment": true, "manage": true, "invite_guests": true, "join": false }, "sections": [ { "id": 201, "name": "Equipment" } ], "columns": [ { "id": 301, "name": "In progress", "status": "in_progress", "color": "#f59e0b", "wip_limit": 5 } ], "milestones": [ { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } ], "fields": [ { "id": 501, "name": "Supplier", "type": "select", "options": [ { "id": "o_k2m9qa", "label": "Metro", "color": "#22c55e" } ], "on_card": true } ], "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin" } ], "guests": [ { "id": 12, "name": "Ivan Petrov", "email": "ivan@buildco.kz", "company": "BuildCo", "role": "editor", "tasks_count": 4, "last_seen_at": "2026-11-02T15:30:00+05:00", "invited_at": "2026-10-29T10:00:00+05:00", "url": "https://app.jecheck.io/pg/Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" } ], "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "unassigned": 2, "progress": 44, "forecast": "2026-12-20" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/members": { "get": { "operationId": "projectsMembersList", "summary": "List project members", "tags": [ "Projects" ], "x-mcp-tool": "projects_members_list", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "admin" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "projectsMembersAdd", "summary": "Add project members", "description": "Adds employees with one project role (default `editor`); existing members get the new role. Added people are notified. Requires the admin role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_members_add", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "integer" }, "description": "User ids", "minItems": 1, "maxItems": 200 }, "role": { "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ], "default": "editor", "description": "Project role" } }, "required": [ "user_ids" ] }, "example": { "user_ids": [ 12, 14 ], "role": "editor" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "editor" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/members/{user_id}": { "patch": { "operationId": "projectsMembersUpdate", "summary": "Change a member's project role", "tags": [ "Projects" ], "x-mcp-tool": "projects_members_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "description": "User id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ] } }, "required": [ "role" ] }, "example": { "role": "admin" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "role": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "role": "commenter" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsMembersRemove", "summary": "Remove a project member", "description": "Removes a member (admin role required) or leaves the project when `user_id` is the acting user. The owner cannot be removed.", "tags": [ "Projects" ], "x-mcp-tool": "projects_members_remove", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "description": "User id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/milestones": { "post": { "operationId": "projectsMilestonesCreate", "summary": "Create a milestone", "description": "Adds a milestone to the project. Requires the editor role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_milestones_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Milestone title", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "done": { "type": "boolean", "description": "Mark as reached" } }, "required": [ "title" ] }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "due_date": "2026-11-01", "done": true } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/milestones/order": { "put": { "operationId": "projectsMilestonesReorder", "summary": "Reorder milestones", "tags": [ "Projects" ], "x-mcp-tool": "projects_milestones_reorder", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "All ids in the new order", "minItems": 1 } }, "required": [ "ids" ] }, "example": { "ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/milestones/{id}": { "patch": { "operationId": "projectsMilestonesUpdate", "summary": "Update a milestone", "description": "Partial update. Requires the editor role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_milestones_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Milestone id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Milestone title", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "done": { "type": "boolean", "description": "Mark as reached" } } }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "due_date": "2026-11-01", "done": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 401, "title": "Soft opening", "description": "", "due_date": "2026-12-01", "done": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsMilestonesDelete", "summary": "Delete a milestone", "description": "Tasks of the milestone move to `move_to_id` or are left without a milestone.", "tags": [ "Projects" ], "x-mcp-tool": "projects_milestones_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Milestone id", "schema": { "type": "integer" } }, { "name": "move_to_id", "in": "query", "description": "Where to move its tasks", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/rules": { "get": { "operationId": "projectsRulesList", "summary": "List automation rules", "description": "Project automation rules (\"when … if … then …\"). Requires the admin role in the project. Ids inside `trigger`, `conditions` and `actions` refer to columns, sections, milestones, fields and users of this project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_rules_list", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "column": { "type": "string" } } }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" } } } }, "runs": { "type": "integer" }, "last_run_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 14, "name": "Done → notify the owner", "enabled": true, "trigger": { "type": "column_changed", "column": "305" }, "conditions": [ { "field": "priority", "op": "is", "value": "urgent" } ], "actions": [ { "type": "notify", "to": [ "owner" ], "text": "Urgent task closed" } ], "runs": 12, "last_run_at": "2026-11-03T12:01:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "projectsRulesCreate", "summary": "Create an automation rule", "description": "Triggers: task_created, column_changed, status_changed, section_changed, assigned, field_changed, commented, subtasks_done, unblocked, due_soon, overdue. Conditions (up to 10) on: priority, column, section, milestone, assignee, tag, title, field with op is/not/empty/not_empty/contains. Actions (1–12): move_column, move_section, set_milestone, assign, unassign, watchers, priority, due, start, tags, field, subtasks, comment, notify, create_task. Up to 50 rules per project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_rules_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Rule name", "maxLength": 200 }, "trigger": { "type": "object", "properties": {}, "additionalProperties": true, "description": "{\"type\": \"\", ...}: `column` for column_changed, `section` for section_changed, `status` for status_changed, `field`+`value` for field_changed, `days` for due_soon, `guest: true` for commented" }, "conditions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "[{\"field\", \"op\", \"value\", \"id\"}]; `id` — custom field id when field = `field`", "maxItems": 10 }, "actions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "[{\"type\", ...}], e.g. {\"type\": \"move_column\", \"column\": 301}, {\"type\": \"assign\", \"users\": [311], \"mode\": \"add\"}, {\"type\": \"comment\", \"text\": \"…\"}", "minItems": 1, "maxItems": 12 }, "enabled": { "type": "boolean", "default": true } }, "required": [ "trigger", "actions" ] }, "example": { "name": "Replace the broken fridge seal", "trigger": [], "conditions": [ [] ], "actions": [ [] ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "column": { "type": "string" } } }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" } } } }, "runs": { "type": "integer" }, "last_run_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 14, "name": "Done → notify the owner", "enabled": true, "trigger": { "type": "column_changed", "column": "305" }, "conditions": [ { "field": "priority", "op": "is", "value": "urgent" } ], "actions": [ { "type": "notify", "to": [ "owner" ], "text": "Urgent task closed" } ], "runs": 12, "last_run_at": "2026-11-03T12:01:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/rules/{id}": { "put": { "operationId": "projectsRulesUpdate", "summary": "Replace an automation rule", "description": "Replaces the whole rule definition (same fields as on creation).", "tags": [ "Projects" ], "x-mcp-tool": "projects_rules_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Rule id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Rule name", "maxLength": 200 }, "trigger": { "type": "object", "properties": {}, "additionalProperties": true, "description": "{\"type\": \"\", ...}: `column` for column_changed, `section` for section_changed, `status` for status_changed, `field`+`value` for field_changed, `days` for due_soon, `guest: true` for commented" }, "conditions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "[{\"field\", \"op\", \"value\", \"id\"}]; `id` — custom field id when field = `field`", "maxItems": 10 }, "actions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "[{\"type\", ...}], e.g. {\"type\": \"move_column\", \"column\": 301}, {\"type\": \"assign\", \"users\": [311], \"mode\": \"add\"}, {\"type\": \"comment\", \"text\": \"…\"}", "minItems": 1, "maxItems": 12 }, "enabled": { "type": "boolean", "default": true } }, "required": [ "trigger", "actions" ] }, "example": { "name": "Replace the broken fridge seal", "trigger": [], "conditions": [ [] ], "actions": [ [] ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "column": { "type": "string" } } }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" } } } }, "runs": { "type": "integer" }, "last_run_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 14, "name": "Done → notify the owner", "enabled": true, "trigger": { "type": "column_changed", "column": "305" }, "conditions": [ { "field": "priority", "op": "is", "value": "urgent" } ], "actions": [ { "type": "notify", "to": [ "owner" ], "text": "Urgent task closed" } ], "runs": 12, "last_run_at": "2026-11-03T12:01:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsRulesDelete", "summary": "Delete an automation rule", "tags": [ "Projects" ], "x-mcp-tool": "projects_rules_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Rule id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/rules/{id}/runs": { "get": { "operationId": "projectsRulesRuns", "summary": "List rule runs", "description": "Last 50 runs of the rule: when, on which task, success or the reason of failure.", "tags": [ "Projects" ], "x-mcp-tool": "projects_rules_runs", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Rule id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "trigger": { "type": "string" }, "ok": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "task": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" } } }, "at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "trigger": "column_changed", "ok": true, "note": null, "task": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPEN-12", "title": "Install the espresso machine" }, "at": "2026-11-03T12:01:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/rules/{id}/toggle": { "post": { "operationId": "projectsRulesToggle", "summary": "Enable or disable a rule", "tags": [ "Projects" ], "x-mcp-tool": "projects_rules_toggle", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Rule id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "column": { "type": "string" } } }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "value": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" } } } }, "runs": { "type": "integer" }, "last_run_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 14, "name": "Done → notify the owner", "enabled": true, "trigger": { "type": "column_changed", "column": "305" }, "conditions": [ { "field": "priority", "op": "is", "value": "urgent" } ], "actions": [ { "type": "notify", "to": [ "owner" ], "text": "Urgent task closed" } ], "runs": 12, "last_run_at": "2026-11-03T12:01:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/sections": { "post": { "operationId": "projectsSectionsCreate", "summary": "Create a section", "description": "Adds a section to the project. Requires the editor role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_sections_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Section name", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 201, "name": "Equipment" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/sections/order": { "put": { "operationId": "projectsSectionsReorder", "summary": "Reorder sections", "tags": [ "Projects" ], "x-mcp-tool": "projects_sections_reorder", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "All ids in the new order", "minItems": 1 } }, "required": [ "ids" ] }, "example": { "ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 201, "name": "Equipment" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/sections/{id}": { "patch": { "operationId": "projectsSectionsUpdate", "summary": "Update a section", "description": "Partial update. Requires the editor role in the project.", "tags": [ "Projects" ], "x-mcp-tool": "projects_sections_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Section id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Section name", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 201, "name": "Equipment" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "projectsSectionsDelete", "summary": "Delete a section", "description": "Tasks of the section move to `move_to_id` or are left without a section.", "tags": [ "Projects" ], "x-mcp-tool": "projects_sections_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Section id", "schema": { "type": "integer" } }, { "name": "move_to_id", "in": "query", "description": "Where to move its tasks", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/star": { "post": { "operationId": "projectsStar", "summary": "Star or unstar a project", "description": "Starred projects are shown in the side menu of the acting user.", "tags": [ "Projects" ], "x-mcp-tool": "projects_star", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "on": { "type": "boolean", "default": true, "description": "`true` — star, `false` — unstar" } } }, "example": { "on": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "starred": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "starred": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/stats": { "get": { "operationId": "projectsStats", "summary": "Get project statistics", "description": "Progress, workload by assignee, milestones progress, weekly velocity (8 weeks), burn-up and the completion forecast.", "tags": [ "Projects" ], "x-mcp-tool": "projects_stats", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "done_week": { "type": "integer" }, "created_week": { "type": "integer" }, "due_week": { "type": "integer" }, "progress": { "type": "integer" }, "estimate_minutes": { "type": "integer" }, "spent_minutes": { "type": "integer" }, "workload": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "open": { "type": "integer" }, "overdue": { "type": "integer" } } } }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "done": { "type": "boolean" }, "total": { "type": "integer" }, "closed": { "type": "integer" } } } }, "velocity": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string", "format": "date" }, "closed": { "type": "integer" } } } }, "burnup": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "scope": { "type": "integer" }, "done": { "type": "integer" } } } }, "forecast": { "type": "string", "format": "date" }, "avg_per_week": { "type": "number" } } } }, "required": [ "data" ] }, "example": { "data": { "total": 42, "done": 18, "open": 23, "overdue": 3, "unassigned": 2, "done_week": 5, "created_week": 7, "due_week": 6, "progress": 44, "estimate_minutes": 9600, "spent_minutes": 4100, "workload": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "open": 6, "overdue": 1 } ], "milestones": [ { "id": 401, "title": "Soft opening", "due_date": "2026-12-01", "done": false, "total": 12, "closed": 5 } ], "velocity": [ { "week": "2026-10-27", "closed": 5 } ], "burnup": [ { "date": "2026-11-01", "scope": 40, "done": 15 } ], "forecast": "2026-12-20", "avg_per_week": 4.5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/tasks": { "get": { "operationId": "projectsTasksList", "summary": "List project tasks (board)", "description": "Tasks of the project in board order (`rank`) with section, column, milestone, dates, estimate, logged time and custom field values (`fields`: field id → value). Closed tasks are included. Use the Tasks section for the full task card and changes.", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "section_id", "in": "query", "description": "Only this section", "schema": { "type": "integer" } }, { "name": "column_id", "in": "query", "description": "Only this board column", "schema": { "type": "integer" } }, { "name": "milestone_id", "in": "query", "description": "Only this milestone", "schema": { "type": "integer" } }, { "name": "status[]", "in": "query", "description": "Filter by status: new, in_progress, review, approval, done, rejected", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "assignee_id", "in": "query", "description": "Only tasks assigned to this user", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "section_id": { "type": "integer" }, "column_id": { "type": "integer" }, "milestone_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "estimate_minutes": { "type": "integer" }, "spent_minutes": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "object", "properties": { "501": { "type": "string" } } }, "guest_ids": { "type": "array", "items": { "type": "integer" } }, "blocked_by_open": { "type": "integer" }, "rank": { "type": "number" }, "completed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPEN-12", "title": "Install the espresso machine", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "section_id": 201, "column_id": 301, "milestone_id": 401, "start_date": "2026-11-04", "due_date": "2026-11-10", "estimate_minutes": 240, "spent_minutes": 90, "tags": [ "Equipment" ], "fields": { "501": "o_k2m9qa" }, "guest_ids": [ 12 ], "blocked_by_open": 0, "rank": 3.5, "completed_at": null, "updated_at": "2026-11-03T12:01:00+05:00", "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/tasks/{task_uuid}/move": { "post": { "operationId": "projectsTasksMove", "summary": "Move a task on the board", "description": "Same as drag and drop: puts the task between `before_uuid` and `after_uuid` (rank), and optionally into another column (its status changes accordingly — loop rules may keep it), section or milestone. Requires the editor role.", "tags": [ "Projects" ], "x-mcp-tool": "projects_tasks_move", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "task_uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "column_id": { "type": "integer", "description": "Target board column" }, "section_id": { "type": [ "integer", "null" ], "description": "Target section (`null` — no section)" }, "milestone_id": { "type": [ "integer", "null" ], "description": "Target milestone (`null` — none)" }, "before_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "Task that should end up right before this one" }, "after_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "Task that should end up right after this one" } } }, "example": { "column_id": 42, "section_id": 42, "milestone_id": 42, "before_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "column_id": { "type": "integer" }, "section_id": { "type": "integer" }, "milestone_id": { "type": "integer" }, "rank": { "type": "number" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "status": "in_progress", "column_id": 301, "section_id": 201, "milestone_id": 401, "rank": 3.5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/template": { "post": { "operationId": "projectsTemplatesCreate", "summary": "Save a project as a company template", "description": "Saves the project structure and tasks as a company template. Requires `projects.create`.", "tags": [ "Projects" ], "x-mcp-tool": "projects_templates_create", "x-permissions": [ "projects.create" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name, default — project name", "minLength": 2, "maxLength": 200 } } }, "example": { "name": "Replace the broken fridge seal" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "company": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a", "name": "Opening a location", "company": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/updates": { "get": { "operationId": "projectsUpdatesList", "summary": "List status updates", "tags": [ "Projects" ], "x-mcp-tool": "projects_updates_list", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "health": { "type": "string" }, "body": { "type": "string" }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 31, "health": "on_track", "body": "Equipment delivered, staff hired.", "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "progress": 44, "forecast": "2026-12-20" }, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "created_at": "2026-11-02T18:00:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "projectsUpdatesCreate", "summary": "Post a status update", "description": "Posts a status report with health; the project health changes and members are notified. Requires the editor role.", "tags": [ "Projects" ], "x-mcp-tool": "projects_updates_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "health": { "type": "string", "enum": [ "on_track", "at_risk", "off_track" ] }, "body": { "type": "string", "description": "Report text", "minLength": 2, "maxLength": 10000 } }, "required": [ "health", "body" ] }, "example": { "health": "on_track", "body": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "health": { "type": "string" }, "body": { "type": "string" }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "done": { "type": "integer" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "progress": { "type": "integer" }, "forecast": { "type": "string", "format": "date" } } }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 31, "health": "on_track", "body": "Equipment delivered, staff hired.", "stats": { "total": 42, "done": 18, "open": 23, "overdue": 3, "progress": 44, "forecast": "2026-12-20" }, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "created_at": "2026-11-02T18:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{uuid}/updates/{id}": { "delete": { "operationId": "projectsUpdatesDelete", "summary": "Delete a status update", "description": "The author or a project admin can delete an update.", "tags": [ "Projects" ], "x-mcp-tool": "projects_updates_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Project UUID", "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "description": "Update id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines": { "get": { "operationId": "routinesList", "summary": "List routines", "description": "Routine templates of the company (the library), in display order, with today's progress across all locations.", "tags": [ "Routines" ], "x-mcp-tool": "routines_list", "x-permissions": [ "routines.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "active", "in": "query", "description": "Only enabled (`true`) or disabled (`false`) routines", "schema": { "type": "boolean" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "opening", "closing", "cleaning", "shift", "safety", "maintenance", "service", "other" ] } }, { "name": "trigger_type", "in": "query", "schema": { "type": "string", "enum": [ "schedule", "after", "on_issue", "manual" ] } }, { "name": "location_id", "in": "query", "description": "Only routines that run at this location", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search in title", "schema": { "type": "string", "maxLength": 200 } }, { "name": "updated_since", "in": "query", "description": "Only routines changed after this moment", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_text": { "type": "string" }, "parent_routine_id": { "type": [ "string", "null" ] }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "steps_count": { "type": "integer" }, "approval": { "type": "boolean" }, "manual_start": { "type": "boolean" }, "today": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 12, "uuid": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "title": "Opening the shift", "description": "Everything that must be done before the first guest arrives.", "category": "opening", "color": "#f59e0b", "active": true, "trigger_type": "schedule", "trigger_text": "Daily, 08:00–09:00", "parent_routine_id": null, "location_ids": null, "position_ids": [], "steps_count": 8, "approval": false, "manual_start": false, "today": { "done": 3, "total": 4 }, "created_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-11-01T12:30:00+05:00", "url": "https://app.jecheck.io/ui/routines/12/edit" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "routinesCreate", "summary": "Create a routine", "description": "Creates a routine with the same validation as the web builder. It is created disabled unless `active` is `true`; enabling lays out today's and tomorrow's runs (past windows are never created).", "tags": [ "Routines" ], "x-mcp-tool": "routines_create", "x-permissions": [ "routines.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Routine title", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "category": { "type": "string", "enum": [ "opening", "closing", "cleaning", "shift", "safety", "maintenance", "service", "other" ] }, "color": { "type": "string", "description": "Hex color, e.g. `#f59e0b`" }, "active": { "type": "boolean", "description": "Enable right away (default `false`: created disabled, no runs)" }, "location_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "Locations; `null` — all locations of the company" }, "position_ids": { "type": "array", "items": { "type": "integer" }, "description": "Job positions that perform the routine; empty — any staff of the location" }, "trigger": { "type": "object", "properties": {}, "additionalProperties": true, "description": "When it runs. `{type: schedule, repeat: daily|weekdays|monthly|dates|every_n_days, weekdays?, month_days?, dates?, every_days?, start_date?, windows: [{from: \"08:00\", to: \"09:00\", label?}] | interval: {from, to, every_minutes, duration_minutes}}`, `{type: after, routine_id, when: completed|ended, delay_minutes, duration_minutes}`, `{type: on_issue, routine_id, step_id?, duration_minutes}`, `{type: manual, duration_minutes}`. Local time of the location" }, "conditions": { "type": "object", "properties": {}, "additionalProperties": true, "description": "`{date_from, date_to, skip_if_no_shift, manual_start}`" }, "options": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Control: `{grace_minutes, late_hours, remind_open, remind_before, notify_missed, approval: none|manager, sequential, allow_na, photo_from_camera, issue_task: {mode: none|critical|all, assignee: manager|position|user|team, assignee_id, due_hours, priority}}`" }, "instruction_id": { "type": [ "integer", "null" ], "description": "Knowledge-base article id" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Existing section id; omit for a new section" }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "position_ids": { "type": "array", "items": { "type": "integer" }, "description": "Positions that perform this section" }, "repeat_for": { "type": "array", "items": { "type": "string" }, "description": "Repeat the steps for each object (e.g. room names)", "maxItems": 200 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Existing step id — keep it to preserve marks history; omit for a new step" }, "key": { "type": "string", "description": "Client key of a new step, used by `show_if.step_ref`", "maxLength": 40 }, "title": { "type": "string", "maxLength": 500 }, "hint": { "type": [ "string", "null" ], "maxLength": 5000 }, "type": { "type": "string", "enum": [ "check", "number", "choice", "text", "photo", "signature", "scan", "timer", "info" ], "description": "Step type, default `check`" }, "settings": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Type settings: number — `unit`, `min`, `max`, `warn_min`, `warn_max`; choice — `options` [{key, label, issue}]; photo — `min_photos`; scan — `code`; timer — `minutes`; text — `placeholder`" }, "photo": { "type": "string", "enum": [ "none", "optional", "required", "on_issue" ] }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "show_if": { "type": [ "object", "null" ], "properties": {}, "additionalProperties": true, "description": "Show only if a step above in the same section matches: {step_ref (id or key), op: done|issue|equals|lt|gt, value}" }, "instruction_id": { "type": [ "integer", "null" ] } }, "required": [ "title" ] } } }, "required": [ "steps" ] }, "description": "Sections with steps. Omitted — one placeholder step is created", "maxItems": 50 } }, "required": [ "title" ] }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "category": "opening", "color": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_text": { "type": "string" }, "parent_routine_id": { "type": [ "string", "null" ] }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "steps_count": { "type": "integer" }, "approval": { "type": "boolean" }, "manual_start": { "type": "boolean" }, "today": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "repeat": { "type": "string" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "label": { "type": "string" } } } } } }, "conditions": { "type": "object", "properties": { "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "skip_if_no_shift": { "type": "boolean" }, "manual_start": { "type": "boolean" } } }, "options": { "type": "object", "properties": { "grace_minutes": { "type": "integer" }, "late_hours": { "type": "integer" }, "approval": { "type": "string" }, "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "photo_from_camera": { "type": "boolean" }, "issue_task": { "type": "object", "properties": { "mode": { "type": "string" }, "assignee": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_hours": { "type": "integer" }, "priority": { "type": "string" } } } } }, "instruction_id": { "type": [ "string", "null" ] }, "template_key": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "position_ids": { "type": "array" }, "repeat_for": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "show_if": { "type": [ "string", "null" ] }, "instruction_id": { "type": [ "string", "null" ] } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "uuid": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "title": "Opening the shift", "description": "Everything that must be done before the first guest arrives.", "category": "opening", "color": "#f59e0b", "active": true, "trigger_type": "schedule", "trigger_text": "Daily, 08:00–09:00", "parent_routine_id": null, "location_ids": null, "position_ids": [], "steps_count": 8, "approval": false, "manual_start": false, "today": { "done": 3, "total": 4 }, "created_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-11-01T12:30:00+05:00", "url": "https://app.jecheck.io/ui/routines/12/edit", "trigger": { "type": "schedule", "repeat": "daily", "windows": [ { "from": "08:00", "to": "09:00", "label": "Morning" } ] }, "conditions": { "date_from": null, "date_to": null, "skip_if_no_shift": false, "manual_start": false }, "options": { "grace_minutes": 15, "late_hours": 2, "approval": "none", "sequential": false, "allow_na": true, "photo_from_camera": true, "issue_task": { "mode": "critical", "assignee": "manager", "assignee_id": null, "due_hours": 4, "priority": "high" } }, "instruction_id": null, "template_key": "restaurant.opening", "sections": [ { "id": 31, "title": "Restrooms", "position_ids": [], "repeat_for": [ "Men", "Women" ], "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "show_if": null, "instruction_id": null } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/analytics": { "get": { "operationId": "routinesAnalytics", "summary": "Get routine analytics", "description": "Discipline metrics for runs whose due time has passed (skipped runs excluded): totals vs previous period, trend, by location (with the average audit score), by routine, by employee, problem steps, start hours, recent failures and insights. Locations follow `analytics.view`.", "tags": [ "Routines" ], "x-mcp-tool": "routines_analytics", "x-permissions": [ "analytics.view" ], "x-scope": "read", "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "12m" ], "default": "30d" } }, { "name": "date_from", "in": "query", "description": "Custom period start (with `date_to`)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Custom period end", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "routine_id", "in": "query", "description": "Only this routine", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "totals": { "type": "object", "properties": { "due": { "type": "integer" }, "on_time": { "type": "integer" }, "late": { "type": "integer" }, "failed": { "type": "integer" }, "missed": { "type": "integer" }, "review": { "type": "integer" }, "issues": { "type": "integer" }, "rate": { "type": "integer" }, "done_rate": { "type": "integer" }, "steps_rate": { "type": "integer" } } }, "previous": { "type": "object", "properties": { "due": { "type": "integer" }, "on_time": { "type": "integer" }, "late": { "type": "integer" }, "failed": { "type": "integer" }, "missed": { "type": "integer" }, "review": { "type": "integer" }, "issues": { "type": "integer" }, "rate": { "type": "integer" }, "done_rate": { "type": "integer" }, "steps_rate": { "type": "integer" } } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string", "format": "date" }, "due": { "type": "integer" }, "on_time": { "type": "integer" }, "late": { "type": "integer" }, "failed": { "type": "integer" }, "missed": { "type": "integer" }, "review": { "type": "integer" }, "issues": { "type": "integer" }, "rate": { "type": "integer" }, "done_rate": { "type": "integer" }, "steps_rate": { "type": "integer" } } } }, "by_location": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "due": { "type": "integer" }, "on_time": { "type": "integer" }, "late": { "type": "integer" }, "failed": { "type": "integer" }, "missed": { "type": "integer" }, "review": { "type": "integer" }, "issues": { "type": "integer" }, "rate": { "type": "integer" }, "done_rate": { "type": "integer" }, "steps_rate": { "type": "integer" }, "audit": { "type": "object", "properties": { "avg": { "type": "integer" }, "count": { "type": "integer" } } } } } }, "by_routine": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "due": { "type": "integer" }, "on_time": { "type": "integer" }, "late": { "type": "integer" }, "failed": { "type": "integer" }, "missed": { "type": "integer" }, "review": { "type": "integer" }, "issues": { "type": "integer" }, "rate": { "type": "integer" }, "done_rate": { "type": "integer" }, "steps_rate": { "type": "integer" } } } }, "by_employee": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "runs": { "type": "integer" }, "on_time": { "type": "integer" }, "rate": { "type": "integer" }, "marks": { "type": "integer" }, "issues": { "type": "integer" }, "photos": { "type": "integer" } } } }, "problem_steps": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "integer" }, "step": { "type": "string" }, "routine": { "type": "string" }, "critical": { "type": "boolean" }, "count": { "type": "integer" }, "points": { "type": "integer" }, "tasks": { "type": "integer" }, "reason": { "type": "string" } } } }, "hours": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer" }, "due": { "type": "integer" }, "rate": { "type": "integer" } } } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "routine": { "type": "string" }, "location": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" } } } }, "insights": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "location": { "type": "string" }, "rate": { "type": "integer" }, "audit": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "period": { "from": "2026-10-05", "to": "2026-11-03" }, "totals": { "due": 420, "on_time": 371, "late": 18, "failed": 31, "missed": 12, "review": 4, "issues": 57, "rate": 88, "done_rate": 93, "steps_rate": 95 }, "previous": { "due": 398, "on_time": 330, "late": 25, "failed": 43, "missed": 20, "review": 2, "issues": 61, "rate": 83, "done_rate": 89, "steps_rate": 92 }, "trend": [ { "bucket": "2026-11-03", "due": 14, "on_time": 12, "late": 1, "failed": 1, "missed": 0, "review": 0, "issues": 2, "rate": 86, "done_rate": 93, "steps_rate": 96 } ], "by_location": [ { "id": 4609, "name": "Abay Ave", "due": 140, "on_time": 130, "late": 4, "failed": 6, "missed": 2, "review": 0, "issues": 12, "rate": 93, "done_rate": 96, "steps_rate": 97, "audit": { "avg": 64, "count": 5 } } ], "by_routine": [ { "id": 12, "name": "Opening the shift", "due": 60, "on_time": 55, "late": 3, "failed": 2, "missed": 1, "review": 0, "issues": 5, "rate": 92, "done_rate": 97, "steps_rate": 98 } ], "by_employee": [ { "id": 311, "name": "Aigerim Sadykova", "runs": 40, "on_time": 37, "rate": 93, "marks": 380, "issues": 6, "photos": 44 } ], "problem_steps": [ { "step_id": 210, "step": "Liquid soap", "routine": "Opening the shift", "critical": false, "count": 9, "points": 3, "tasks": 4, "reason": "Out of consumables" } ], "hours": [ { "hour": 8, "due": 60, "rate": 92 } ], "failed": [ { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "date": "2026-11-02", "time": "23:00", "routine": "Closing", "location": "Abay Ave", "status": "missed", "progress": 0 } ], "insights": [ { "type": "gap", "location": "Abay Ave", "rate": 93, "audit": 64 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/board": { "get": { "operationId": "routinesBoard", "summary": "Get the day board", "description": "All runs of a day by location with totals (what the \"Daily schedule\" screen shows), plus routines the token may start manually.", "tags": [ "Routines" ], "x-mcp-tool": "routines_board", "x-permissions": [ "routines.view" ], "x-scope": "read", "parameters": [ { "name": "location_ids[]", "in": "query", "description": "Only these locations (default — all visible)", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "date", "in": "query", "description": "Local day, default — today of the company", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "due": { "type": "integer" }, "done": { "type": "integer" }, "on_time": { "type": "integer" }, "in_progress": { "type": "integer" }, "review": { "type": "integer" }, "failed": { "type": "integer" }, "issues": { "type": "integer" }, "steps_total": { "type": "integer" }, "steps_done": { "type": "integer" }, "skipped": { "type": "integer" } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "timezone": { "type": "string" }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "due": { "type": "integer" }, "done": { "type": "integer" }, "on_time": { "type": "integer" }, "in_progress": { "type": "integer" }, "review": { "type": "integer" }, "failed": { "type": "integer" }, "issues": { "type": "integer" }, "steps_total": { "type": "integer" }, "steps_done": { "type": "integer" }, "skipped": { "type": "integer" } } }, "runs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } } } } }, "startable": { "type": "array", "items": { "type": "object", "properties": { "routine_id": { "type": "integer" }, "title": { "type": "string" }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "manual": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "day": "2026-11-03", "summary": { "total": 12, "due": 8, "done": 6, "on_time": 5, "in_progress": 1, "review": 1, "failed": 1, "issues": 2, "steps_total": 96, "steps_done": 70, "skipped": 0 }, "locations": [ { "location": { "id": 4609, "name": "Abay Ave" }, "timezone": "Asia/Almaty", "summary": { "total": 6, "due": 4, "done": 3, "on_time": 3, "in_progress": 1, "review": 0, "failed": 0, "issues": 1, "steps_total": 48, "steps_done": 35, "skipped": 0 }, "runs": [ { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d" } ] } ], "startable": [ { "routine_id": 15, "title": "Delivery acceptance", "category": "safety", "location": { "id": 4609, "name": "Abay Ave" }, "manual": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/from-checklist/{checklist_id}": { "post": { "operationId": "routinesFromChecklist", "summary": "Create a routine from an audit checklist", "description": "Converts checklist questions into routine steps without scores. The checklist is not changed; the routine is created disabled.", "tags": [ "Routines" ], "x-mcp-tool": "routines_from_checklist", "x-permissions": [ "routines.manage" ], "x-scope": "write", "parameters": [ { "name": "checklist_id", "in": "path", "required": true, "description": "Checklist id", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_text": { "type": "string" }, "parent_routine_id": { "type": [ "string", "null" ] }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "steps_count": { "type": "integer" }, "approval": { "type": "boolean" }, "manual_start": { "type": "boolean" }, "today": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "repeat": { "type": "string" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "label": { "type": "string" } } } } } }, "conditions": { "type": "object", "properties": { "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "skip_if_no_shift": { "type": "boolean" }, "manual_start": { "type": "boolean" } } }, "options": { "type": "object", "properties": { "grace_minutes": { "type": "integer" }, "late_hours": { "type": "integer" }, "approval": { "type": "string" }, "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "photo_from_camera": { "type": "boolean" }, "issue_task": { "type": "object", "properties": { "mode": { "type": "string" }, "assignee": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_hours": { "type": "integer" }, "priority": { "type": "string" } } } } }, "instruction_id": { "type": [ "string", "null" ] }, "template_key": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "position_ids": { "type": "array" }, "repeat_for": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "show_if": { "type": [ "string", "null" ] }, "instruction_id": { "type": [ "string", "null" ] } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "uuid": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "title": "Opening the shift", "description": "Everything that must be done before the first guest arrives.", "category": "opening", "color": "#f59e0b", "active": true, "trigger_type": "schedule", "trigger_text": "Daily, 08:00–09:00", "parent_routine_id": null, "location_ids": null, "position_ids": [], "steps_count": 8, "approval": false, "manual_start": false, "today": { "done": 3, "total": 4 }, "created_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-11-01T12:30:00+05:00", "url": "https://app.jecheck.io/ui/routines/12/edit", "trigger": { "type": "schedule", "repeat": "daily", "windows": [ { "from": "08:00", "to": "09:00", "label": "Morning" } ] }, "conditions": { "date_from": null, "date_to": null, "skip_if_no_shift": false, "manual_start": false }, "options": { "grace_minutes": 15, "late_hours": 2, "approval": "none", "sequential": false, "allow_na": true, "photo_from_camera": true, "issue_task": { "mode": "critical", "assignee": "manager", "assignee_id": null, "due_hours": 4, "priority": "high" } }, "instruction_id": null, "template_key": "restaurant.opening", "sections": [ { "id": 31, "title": "Restrooms", "position_ids": [], "repeat_for": [ "Men", "Women" ], "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "show_if": null, "instruction_id": null } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/issues": { "get": { "operationId": "routinesIssues", "summary": "List routine step issues", "description": "Step marks with problems (\"cannot do\", out-of-range values, wrong code) at visible locations, newest first, with the follow-up task if one was created.", "tags": [ "Routines" ], "x-mcp-tool": "routines_issues", "x-permissions": [ "routines.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "date", "in": "query", "description": "Only this local day", "schema": { "type": "string", "format": "date" } }, { "name": "date_from", "in": "query", "description": "Local day from (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Local day to (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "routine_id", "in": "query", "description": "Only runs of this routine", "schema": { "type": "integer" } }, { "name": "critical", "in": "query", "description": "Only critical steps", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "run_uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "step": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "critical": { "type": "boolean" } } }, "item": { "type": "integer" }, "value": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "run_uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "step": { "id": 210, "title": "Liquid soap", "critical": false }, "item": 0, "value": "none", "reason": null, "comment": "Ordered from the warehouse", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/media": { "post": { "operationId": "routinesMediaUpload", "summary": "Upload a routine photo or signature", "description": "Uploads an image (jpg, png, webp, heic, up to 15 MB) and returns its `path` to pass in `photos` of a step mark (or as `value` of a signature step).", "tags": [ "Routines" ], "x-mcp-tool": "routines_media_upload", "x-permissions": [ "routines.fill" ], "x-scope": "write", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Image file (multipart; in MCP — object with `name` and `content_base64`)" }, "kind": { "type": "string", "enum": [ "photo", "signature" ], "default": "photo" } }, "required": [ "file" ] } }, "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "Image file (multipart; in MCP — object with `name` and `content_base64`)" }, "kind": { "type": "string", "enum": [ "photo", "signature" ], "default": "photo" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/my": { "get": { "operationId": "routinesMy", "summary": "List my routine runs", "description": "Runs the acting user performs (permission `routines.fill` and the job position of the routine/section): today, yesterday's still workable and night windows opening within 2 hours; plus routines the user may start manually.", "tags": [ "Routines" ], "x-mcp-tool": "routines_my", "x-permissions": [ "routines.fill" ], "x-scope": "read", "parameters": [ { "name": "location_id", "in": "query", "description": "Only this location", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "startable": { "type": "array", "items": { "type": "object", "properties": { "routine_id": { "type": "integer" }, "title": { "type": "string" }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "manual": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "runs": [ { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d" } ], "startable": [ { "routine_id": 15, "title": "Delivery acceptance", "category": "safety", "location": { "id": 4609, "name": "Abay Ave" }, "manual": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/runs": { "get": { "operationId": "routinesRunsList", "summary": "List routine runs", "description": "Runs at the locations visible to the token (`routines.view`), newest window first. `overdue` is computed: the due time passed but the run is not closed yet.", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_list", "x-permissions": [ "routines.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "date", "in": "query", "description": "Only this local day", "schema": { "type": "string", "format": "date" } }, { "name": "date_from", "in": "query", "description": "Local day from (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Local day to (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "routine_id", "in": "query", "description": "Only runs of this routine", "schema": { "type": "integer" } }, { "name": "status[]", "in": "query", "description": "Filter by status: pending, in_progress, review, done, overdue, incomplete, missed, skipped", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "user_id", "in": "query", "description": "Only runs started, completed or marked by this user", "schema": { "type": "integer" } }, { "name": "trigger_type", "in": "query", "schema": { "type": "string", "enum": [ "schedule", "after", "on_issue", "manual" ] } }, { "name": "updated_since", "in": "query", "description": "Only runs changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/runs/{uuid}": { "get": { "operationId": "routinesRunsGet", "summary": "Retrieve a routine run", "description": "Run with sections, steps and marks (photos as signed links valid for 1 hour), required steps still missing and the actions the token may perform now (`can`).", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_get", "x-permissions": [ "routines.view", "routines.fill" ], "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Run UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "instruction": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "options": { "type": "object", "properties": { "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "approval": { "type": "string" }, "photo_from_camera": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "integer" }, "title": { "type": "string" }, "item": { "type": "integer" }, "item_name": { "type": "string" }, "can_fill": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "conditional": { "type": "boolean" }, "instruction": { "type": [ "string", "null" ] }, "mark": { "type": "object", "properties": { "status": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" }, "flag": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" }, "spawned_run_uuid": { "type": [ "string", "null" ] } } } } } } } } }, "missing_required": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } } } }, "can": { "type": "object", "properties": { "fill": { "type": "boolean" }, "complete": { "type": "boolean" }, "accept": { "type": "boolean" }, "return": { "type": "boolean" }, "skip": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "description": "Everything that must be done before the first guest arrives.", "instruction": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "title": "Opening standard" }, "options": { "sequential": false, "allow_na": true, "approval": "none", "photo_from_camera": true }, "sections": [ { "section_id": 31, "title": "Restrooms", "item": 0, "item_name": "Men", "can_fill": true, "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "conditional": false, "instruction": null, "mark": { "status": "issue", "value": "none", "display": "Out of soap", "flag": null, "reason": null, "comment": "Ordered from the warehouse", "photos": [ { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } ], "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "spawned_run_uuid": null } } ] } ], "missing_required": [ "Restrooms (Women): Liquid soap" ], "children": [ { "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "title": "Restock consumables", "status": "pending", "trigger_type": "on_issue" } ], "can": { "fill": true, "complete": true, "accept": false, "return": false, "skip": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/runs/{uuid}/accept": { "post": { "operationId": "routinesRunsAccept", "summary": "Accept a routine run", "description": "Manager approval of a run in `review` (`routines.control` at the location). Chained routines start.", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_accept", "x-permissions": [ "routines.control" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Run UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "instruction": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "options": { "type": "object", "properties": { "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "approval": { "type": "string" }, "photo_from_camera": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "integer" }, "title": { "type": "string" }, "item": { "type": "integer" }, "item_name": { "type": "string" }, "can_fill": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "conditional": { "type": "boolean" }, "instruction": { "type": [ "string", "null" ] }, "mark": { "type": "object", "properties": { "status": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" }, "flag": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" }, "spawned_run_uuid": { "type": [ "string", "null" ] } } } } } } } } }, "missing_required": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } } } }, "can": { "type": "object", "properties": { "fill": { "type": "boolean" }, "complete": { "type": "boolean" }, "accept": { "type": "boolean" }, "return": { "type": "boolean" }, "skip": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "description": "Everything that must be done before the first guest arrives.", "instruction": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "title": "Opening standard" }, "options": { "sequential": false, "allow_na": true, "approval": "none", "photo_from_camera": true }, "sections": [ { "section_id": 31, "title": "Restrooms", "item": 0, "item_name": "Men", "can_fill": true, "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "conditional": false, "instruction": null, "mark": { "status": "issue", "value": "none", "display": "Out of soap", "flag": null, "reason": null, "comment": "Ordered from the warehouse", "photos": [ { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } ], "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "spawned_run_uuid": null } } ] } ], "missing_required": [ "Restrooms (Women): Liquid soap" ], "children": [ { "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "title": "Restock consumables", "status": "pending", "trigger_type": "on_issue" } ], "can": { "fill": true, "complete": true, "accept": false, "return": false, "skip": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/runs/{uuid}/complete": { "post": { "operationId": "routinesRunsComplete", "summary": "Complete a routine run", "description": "Completes the run when all visible required steps are marked. With manager approval enabled, the run goes to `review`. Optional `marks` are recorded first in the same call.", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_complete", "x-permissions": [ "routines.fill", "routines.control" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Run UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "marks": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "integer" } }, "required": [ "step_id" ] }, "description": "Last marks, same format as `routines.runs.mark`", "maxItems": 300 } } }, "example": { "marks": [ { "step_id": 42 } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "instruction": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "options": { "type": "object", "properties": { "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "approval": { "type": "string" }, "photo_from_camera": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "integer" }, "title": { "type": "string" }, "item": { "type": "integer" }, "item_name": { "type": "string" }, "can_fill": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "conditional": { "type": "boolean" }, "instruction": { "type": [ "string", "null" ] }, "mark": { "type": "object", "properties": { "status": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" }, "flag": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" }, "spawned_run_uuid": { "type": [ "string", "null" ] } } } } } } } } }, "missing_required": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } } } }, "can": { "type": "object", "properties": { "fill": { "type": "boolean" }, "complete": { "type": "boolean" }, "accept": { "type": "boolean" }, "return": { "type": "boolean" }, "skip": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "description": "Everything that must be done before the first guest arrives.", "instruction": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "title": "Opening standard" }, "options": { "sequential": false, "allow_na": true, "approval": "none", "photo_from_camera": true }, "sections": [ { "section_id": 31, "title": "Restrooms", "item": 0, "item_name": "Men", "can_fill": true, "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "conditional": false, "instruction": null, "mark": { "status": "issue", "value": "none", "display": "Out of soap", "flag": null, "reason": null, "comment": "Ordered from the warehouse", "photos": [ { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } ], "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "spawned_run_uuid": null } } ] } ], "missing_required": [ "Restrooms (Women): Liquid soap" ], "children": [ { "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "title": "Restock consumables", "status": "pending", "trigger_type": "on_issue" } ], "can": { "fill": true, "complete": true, "accept": false, "return": false, "skip": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/runs/{uuid}/marks": { "post": { "operationId": "routinesRunsMark", "summary": "Mark routine steps", "description": "Records step marks in a batch (offline-friendly, like the mobile app). Each mark: `step_id`, `item` (repeat object index, default 0), `status` (`done` default, `issue` — cannot do, reason required; `na`), `value` (string or number — measurement, choice key, text, scanned code), `reason`, `comment`, `photos` (paths from `routines.media.upload`), `marked_at` (device time), `client_uuid` — repeating the same `client_uuid` does not change the mark. Issues create tasks and chained runs as configured.", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_mark", "x-permissions": [ "routines.fill", "routines.control" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Run UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "marks": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "integer" }, "item": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "done", "issue", "na" ] }, "reason": { "type": "string", "maxLength": 255 }, "comment": { "type": "string", "maxLength": 2000 }, "photos": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "marked_at": { "type": "string", "format": "date-time" }, "client_uuid": { "type": "string", "format": "uuid" } }, "required": [ "step_id" ] }, "minItems": 1, "maxItems": 300 } }, "required": [ "marks" ] }, "example": { "marks": [ { "step_id": 42, "item": 42, "status": "done" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "instruction": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "options": { "type": "object", "properties": { "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "approval": { "type": "string" }, "photo_from_camera": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "integer" }, "title": { "type": "string" }, "item": { "type": "integer" }, "item_name": { "type": "string" }, "can_fill": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "conditional": { "type": "boolean" }, "instruction": { "type": [ "string", "null" ] }, "mark": { "type": "object", "properties": { "status": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" }, "flag": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" }, "spawned_run_uuid": { "type": [ "string", "null" ] } } } } } } } } }, "missing_required": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } } } }, "can": { "type": "object", "properties": { "fill": { "type": "boolean" }, "complete": { "type": "boolean" }, "accept": { "type": "boolean" }, "return": { "type": "boolean" }, "skip": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "description": "Everything that must be done before the first guest arrives.", "instruction": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "title": "Opening standard" }, "options": { "sequential": false, "allow_na": true, "approval": "none", "photo_from_camera": true }, "sections": [ { "section_id": 31, "title": "Restrooms", "item": 0, "item_name": "Men", "can_fill": true, "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "conditional": false, "instruction": null, "mark": { "status": "issue", "value": "none", "display": "Out of soap", "flag": null, "reason": null, "comment": "Ordered from the warehouse", "photos": [ { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } ], "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "spawned_run_uuid": null } } ] } ], "missing_required": [ "Restrooms (Women): Liquid soap" ], "children": [ { "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "title": "Restock consumables", "status": "pending", "trigger_type": "on_issue" } ], "can": { "fill": true, "complete": true, "accept": false, "return": false, "skip": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/runs/{uuid}/return": { "post": { "operationId": "routinesRunsReturn", "summary": "Return a routine run for rework", "description": "Returns a completed run to `in_progress` with a note; the performer is notified.", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_return", "x-permissions": [ "routines.control" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Run UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "note" ] }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "instruction": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "options": { "type": "object", "properties": { "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "approval": { "type": "string" }, "photo_from_camera": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "integer" }, "title": { "type": "string" }, "item": { "type": "integer" }, "item_name": { "type": "string" }, "can_fill": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "conditional": { "type": "boolean" }, "instruction": { "type": [ "string", "null" ] }, "mark": { "type": "object", "properties": { "status": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" }, "flag": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" }, "spawned_run_uuid": { "type": [ "string", "null" ] } } } } } } } } }, "missing_required": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } } } }, "can": { "type": "object", "properties": { "fill": { "type": "boolean" }, "complete": { "type": "boolean" }, "accept": { "type": "boolean" }, "return": { "type": "boolean" }, "skip": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "description": "Everything that must be done before the first guest arrives.", "instruction": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "title": "Opening standard" }, "options": { "sequential": false, "allow_na": true, "approval": "none", "photo_from_camera": true }, "sections": [ { "section_id": 31, "title": "Restrooms", "item": 0, "item_name": "Men", "can_fill": true, "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "conditional": false, "instruction": null, "mark": { "status": "issue", "value": "none", "display": "Out of soap", "flag": null, "reason": null, "comment": "Ordered from the warehouse", "photos": [ { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } ], "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "spawned_run_uuid": null } } ] } ], "missing_required": [ "Restrooms (Women): Liquid soap" ], "children": [ { "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "title": "Restock consumables", "status": "pending", "trigger_type": "on_issue" } ], "can": { "fill": true, "complete": true, "accept": false, "return": false, "skip": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/runs/{uuid}/skip": { "post": { "operationId": "routinesRunsSkip", "summary": "Skip a routine run", "description": "Cancels a run with a reason (location closed, sanitary day). Skipped runs are not counted in analytics.", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_skip", "x-permissions": [ "routines.control" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Run UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "reason" ] }, "example": { "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "instruction": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "options": { "type": "object", "properties": { "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "approval": { "type": "string" }, "photo_from_camera": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "integer" }, "title": { "type": "string" }, "item": { "type": "integer" }, "item_name": { "type": "string" }, "can_fill": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "conditional": { "type": "boolean" }, "instruction": { "type": [ "string", "null" ] }, "mark": { "type": "object", "properties": { "status": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" }, "flag": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" }, "spawned_run_uuid": { "type": [ "string", "null" ] } } } } } } } } }, "missing_required": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } } } }, "can": { "type": "object", "properties": { "fill": { "type": "boolean" }, "complete": { "type": "boolean" }, "accept": { "type": "boolean" }, "return": { "type": "boolean" }, "skip": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "description": "Everything that must be done before the first guest arrives.", "instruction": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "title": "Opening standard" }, "options": { "sequential": false, "allow_na": true, "approval": "none", "photo_from_camera": true }, "sections": [ { "section_id": 31, "title": "Restrooms", "item": 0, "item_name": "Men", "can_fill": true, "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "conditional": false, "instruction": null, "mark": { "status": "issue", "value": "none", "display": "Out of soap", "flag": null, "reason": null, "comment": "Ordered from the warehouse", "photos": [ { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } ], "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "spawned_run_uuid": null } } ] } ], "missing_required": [ "Restrooms (Women): Liquid soap" ], "children": [ { "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "title": "Restock consumables", "status": "pending", "trigger_type": "on_issue" } ], "can": { "fill": true, "complete": true, "accept": false, "return": false, "skip": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/templates": { "get": { "operationId": "routinesTemplatesList", "summary": "List routine templates", "description": "Ready-made routine packs by business type (restaurant, shop, hotel, …) that can be installed with `routines.templates.install`.", "tags": [ "Routines" ], "x-mcp-tool": "routines_templates_list", "x-permissions": [ "routines.manage" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "routines": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "trigger": { "type": "string" }, "trigger_type": { "type": "string" }, "steps": { "type": "integer" }, "repeat": { "type": "boolean" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "key": "restaurant", "title": "Restaurant / cafe", "description": "Opening, cleaning, closing and deliveries", "icon": "restaurant", "routines": [ { "key": "opening", "title": "Opening the shift", "category": "opening", "trigger": "Daily, 08:00–09:00", "trigger_type": "schedule", "steps": 12, "repeat": false } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/templates/install": { "post": { "operationId": "routinesTemplatesInstall", "summary": "Install a routine template", "description": "Installs a whole pack, or one routine of it (`routine_key`) together with its chain parent. Routines are created disabled.", "tags": [ "Routines" ], "x-mcp-tool": "routines_templates_install", "x-permissions": [ "routines.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pack": { "type": "string", "description": "Pack key from `routines.templates.list`", "maxLength": 60 }, "routine_key": { "type": "string", "description": "Install only this routine of the pack", "maxLength": 60 } }, "required": [ "pack" ] }, "example": { "pack": "string", "routine_key": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_text": { "type": "string" }, "parent_routine_id": { "type": [ "string", "null" ] }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "steps_count": { "type": "integer" }, "approval": { "type": "boolean" }, "manual_start": { "type": "boolean" }, "today": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 12, "uuid": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "title": "Opening the shift", "description": "Everything that must be done before the first guest arrives.", "category": "opening", "color": "#f59e0b", "active": true, "trigger_type": "schedule", "trigger_text": "Daily, 08:00–09:00", "parent_routine_id": null, "location_ids": null, "position_ids": [], "steps_count": 8, "approval": false, "manual_start": false, "today": { "done": 3, "total": 4 }, "created_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-11-01T12:30:00+05:00", "url": "https://app.jecheck.io/ui/routines/12/edit" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/{id}": { "get": { "operationId": "routinesGet", "summary": "Retrieve a routine", "description": "Full routine: trigger, conditions, control options, sections and steps with settings and display conditions.", "tags": [ "Routines" ], "x-mcp-tool": "routines_get", "x-permissions": [ "routines.view" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_text": { "type": "string" }, "parent_routine_id": { "type": [ "string", "null" ] }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "steps_count": { "type": "integer" }, "approval": { "type": "boolean" }, "manual_start": { "type": "boolean" }, "today": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "repeat": { "type": "string" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "label": { "type": "string" } } } } } }, "conditions": { "type": "object", "properties": { "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "skip_if_no_shift": { "type": "boolean" }, "manual_start": { "type": "boolean" } } }, "options": { "type": "object", "properties": { "grace_minutes": { "type": "integer" }, "late_hours": { "type": "integer" }, "approval": { "type": "string" }, "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "photo_from_camera": { "type": "boolean" }, "issue_task": { "type": "object", "properties": { "mode": { "type": "string" }, "assignee": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_hours": { "type": "integer" }, "priority": { "type": "string" } } } } }, "instruction_id": { "type": [ "string", "null" ] }, "template_key": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "position_ids": { "type": "array" }, "repeat_for": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "show_if": { "type": [ "string", "null" ] }, "instruction_id": { "type": [ "string", "null" ] } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "uuid": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "title": "Opening the shift", "description": "Everything that must be done before the first guest arrives.", "category": "opening", "color": "#f59e0b", "active": true, "trigger_type": "schedule", "trigger_text": "Daily, 08:00–09:00", "parent_routine_id": null, "location_ids": null, "position_ids": [], "steps_count": 8, "approval": false, "manual_start": false, "today": { "done": 3, "total": 4 }, "created_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-11-01T12:30:00+05:00", "url": "https://app.jecheck.io/ui/routines/12/edit", "trigger": { "type": "schedule", "repeat": "daily", "windows": [ { "from": "08:00", "to": "09:00", "label": "Morning" } ] }, "conditions": { "date_from": null, "date_to": null, "skip_if_no_shift": false, "manual_start": false }, "options": { "grace_minutes": 15, "late_hours": 2, "approval": "none", "sequential": false, "allow_na": true, "photo_from_camera": true, "issue_task": { "mode": "critical", "assignee": "manager", "assignee_id": null, "due_hours": 4, "priority": "high" } }, "instruction_id": null, "template_key": "restaurant.opening", "sections": [ { "id": 31, "title": "Restrooms", "position_ids": [], "repeat_for": [ "Men", "Women" ], "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "show_if": null, "instruction_id": null } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "routinesUpdate", "summary": "Update a routine", "description": "Partial update: send only the fields to change. `sections` replaces the whole structure — pass existing `id`s of sections and steps to keep them. Future runs without marks are rebuilt.", "tags": [ "Routines" ], "x-mcp-tool": "routines_update", "x-permissions": [ "routines.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Routine title", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "category": { "type": "string", "enum": [ "opening", "closing", "cleaning", "shift", "safety", "maintenance", "service", "other" ] }, "color": { "type": "string", "description": "Hex color, e.g. `#f59e0b`" }, "active": { "type": "boolean", "description": "Enable / disable the routine" }, "location_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "Locations; `null` — all locations of the company" }, "position_ids": { "type": "array", "items": { "type": "integer" }, "description": "Job positions that perform the routine; empty — any staff of the location" }, "trigger": { "type": "object", "properties": {}, "additionalProperties": true, "description": "When it runs. `{type: schedule, repeat: daily|weekdays|monthly|dates|every_n_days, weekdays?, month_days?, dates?, every_days?, start_date?, windows: [{from: \"08:00\", to: \"09:00\", label?}] | interval: {from, to, every_minutes, duration_minutes}}`, `{type: after, routine_id, when: completed|ended, delay_minutes, duration_minutes}`, `{type: on_issue, routine_id, step_id?, duration_minutes}`, `{type: manual, duration_minutes}`. Local time of the location" }, "conditions": { "type": "object", "properties": {}, "additionalProperties": true, "description": "`{date_from, date_to, skip_if_no_shift, manual_start}`" }, "options": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Control: `{grace_minutes, late_hours, remind_open, remind_before, notify_missed, approval: none|manager, sequential, allow_na, photo_from_camera, issue_task: {mode: none|critical|all, assignee: manager|position|user|team, assignee_id, due_hours, priority}}`" }, "instruction_id": { "type": [ "integer", "null" ], "description": "Knowledge-base article id" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Existing section id; omit for a new section" }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "position_ids": { "type": "array", "items": { "type": "integer" }, "description": "Positions that perform this section" }, "repeat_for": { "type": "array", "items": { "type": "string" }, "description": "Repeat the steps for each object (e.g. room names)", "maxItems": 200 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Existing step id — keep it to preserve marks history; omit for a new step" }, "key": { "type": "string", "description": "Client key of a new step, used by `show_if.step_ref`", "maxLength": 40 }, "title": { "type": "string", "maxLength": 500 }, "hint": { "type": [ "string", "null" ], "maxLength": 5000 }, "type": { "type": "string", "enum": [ "check", "number", "choice", "text", "photo", "signature", "scan", "timer", "info" ], "description": "Step type, default `check`" }, "settings": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Type settings: number — `unit`, `min`, `max`, `warn_min`, `warn_max`; choice — `options` [{key, label, issue}]; photo — `min_photos`; scan — `code`; timer — `minutes`; text — `placeholder`" }, "photo": { "type": "string", "enum": [ "none", "optional", "required", "on_issue" ] }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "show_if": { "type": [ "object", "null" ], "properties": {}, "additionalProperties": true, "description": "Show only if a step above in the same section matches: {step_ref (id or key), op: done|issue|equals|lt|gt, value}" }, "instruction_id": { "type": [ "integer", "null" ] } }, "required": [ "title" ] } } }, "required": [ "steps" ] }, "description": "Full structure: replaces sections and steps (steps with marks that are dropped go to the archive)", "maxItems": 50 } } }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "category": "opening", "color": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_text": { "type": "string" }, "parent_routine_id": { "type": [ "string", "null" ] }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "steps_count": { "type": "integer" }, "approval": { "type": "boolean" }, "manual_start": { "type": "boolean" }, "today": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "repeat": { "type": "string" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "label": { "type": "string" } } } } } }, "conditions": { "type": "object", "properties": { "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "skip_if_no_shift": { "type": "boolean" }, "manual_start": { "type": "boolean" } } }, "options": { "type": "object", "properties": { "grace_minutes": { "type": "integer" }, "late_hours": { "type": "integer" }, "approval": { "type": "string" }, "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "photo_from_camera": { "type": "boolean" }, "issue_task": { "type": "object", "properties": { "mode": { "type": "string" }, "assignee": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_hours": { "type": "integer" }, "priority": { "type": "string" } } } } }, "instruction_id": { "type": [ "string", "null" ] }, "template_key": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "position_ids": { "type": "array" }, "repeat_for": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "show_if": { "type": [ "string", "null" ] }, "instruction_id": { "type": [ "string", "null" ] } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "uuid": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "title": "Opening the shift", "description": "Everything that must be done before the first guest arrives.", "category": "opening", "color": "#f59e0b", "active": true, "trigger_type": "schedule", "trigger_text": "Daily, 08:00–09:00", "parent_routine_id": null, "location_ids": null, "position_ids": [], "steps_count": 8, "approval": false, "manual_start": false, "today": { "done": 3, "total": 4 }, "created_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-11-01T12:30:00+05:00", "url": "https://app.jecheck.io/ui/routines/12/edit", "trigger": { "type": "schedule", "repeat": "daily", "windows": [ { "from": "08:00", "to": "09:00", "label": "Morning" } ] }, "conditions": { "date_from": null, "date_to": null, "skip_if_no_shift": false, "manual_start": false }, "options": { "grace_minutes": 15, "late_hours": 2, "approval": "none", "sequential": false, "allow_na": true, "photo_from_camera": true, "issue_task": { "mode": "critical", "assignee": "manager", "assignee_id": null, "due_hours": 4, "priority": "high" } }, "instruction_id": null, "template_key": "restaurant.opening", "sections": [ { "id": 31, "title": "Restrooms", "position_ids": [], "repeat_for": [ "Men", "Women" ], "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "show_if": null, "instruction_id": null } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "routinesDelete", "summary": "Delete a routine", "description": "Disables and deletes the routine; unstarted runs are removed, history is kept. Not allowed while other routines are chained to it (`after` / `on_issue`).", "tags": [ "Routines" ], "x-mcp-tool": "routines_delete", "x-permissions": [ "routines.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/{id}/duplicate": { "post": { "operationId": "routinesDuplicate", "summary": "Duplicate a routine", "description": "Creates a disabled copy with the same structure and settings.", "tags": [ "Routines" ], "x-mcp-tool": "routines_duplicate", "x-permissions": [ "routines.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "color": { "type": "string" }, "active": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_text": { "type": "string" }, "parent_routine_id": { "type": [ "string", "null" ] }, "location_ids": { "type": [ "string", "null" ] }, "position_ids": { "type": "array" }, "steps_count": { "type": "integer" }, "approval": { "type": "boolean" }, "manual_start": { "type": "boolean" }, "today": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "repeat": { "type": "string" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "label": { "type": "string" } } } } } }, "conditions": { "type": "object", "properties": { "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "skip_if_no_shift": { "type": "boolean" }, "manual_start": { "type": "boolean" } } }, "options": { "type": "object", "properties": { "grace_minutes": { "type": "integer" }, "late_hours": { "type": "integer" }, "approval": { "type": "string" }, "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "photo_from_camera": { "type": "boolean" }, "issue_task": { "type": "object", "properties": { "mode": { "type": "string" }, "assignee": { "type": "string" }, "assignee_id": { "type": [ "string", "null" ] }, "due_hours": { "type": "integer" }, "priority": { "type": "string" } } } } }, "instruction_id": { "type": [ "string", "null" ] }, "template_key": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "position_ids": { "type": "array" }, "repeat_for": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "show_if": { "type": [ "string", "null" ] }, "instruction_id": { "type": [ "string", "null" ] } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 12, "uuid": "5b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "title": "Opening the shift", "description": "Everything that must be done before the first guest arrives.", "category": "opening", "color": "#f59e0b", "active": true, "trigger_type": "schedule", "trigger_text": "Daily, 08:00–09:00", "parent_routine_id": null, "location_ids": null, "position_ids": [], "steps_count": 8, "approval": false, "manual_start": false, "today": { "done": 3, "total": 4 }, "created_at": "2026-10-20T09:00:00+05:00", "updated_at": "2026-11-01T12:30:00+05:00", "url": "https://app.jecheck.io/ui/routines/12/edit", "trigger": { "type": "schedule", "repeat": "daily", "windows": [ { "from": "08:00", "to": "09:00", "label": "Morning" } ] }, "conditions": { "date_from": null, "date_to": null, "skip_if_no_shift": false, "manual_start": false }, "options": { "grace_minutes": 15, "late_hours": 2, "approval": "none", "sequential": false, "allow_na": true, "photo_from_camera": true, "issue_task": { "mode": "critical", "assignee": "manager", "assignee_id": null, "due_hours": 4, "priority": "high" } }, "instruction_id": null, "template_key": "restaurant.opening", "sections": [ { "id": 31, "title": "Restrooms", "position_ids": [], "repeat_for": [ "Men", "Women" ], "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "show_if": null, "instruction_id": null } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/routines/{id}/start": { "post": { "operationId": "routinesRunsStart", "summary": "Start a routine run", "description": "Starts a run now at a location. Performers may start routines with manual start allowed; `routines.control` at the location may start any routine out of schedule. Performers are notified.", "tags": [ "Routines" ], "x-mcp-tool": "routines_runs_start", "x-permissions": [ "routines.fill", "routines.control" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer", "description": "Location id" } }, "required": [ "location_id" ] }, "example": { "location_id": 12 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "routine": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "category": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "day": { "type": "string", "format": "date" }, "trigger_type": { "type": "string" }, "label": { "type": "string" }, "opens_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "late": { "type": "boolean" }, "progress": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "issues": { "type": "integer" } } }, "started_at": { "type": "string", "format": "date-time" }, "started_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "completed_at": { "type": [ "string", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "review_note": { "type": [ "string", "null" ] }, "skip_reason": { "type": [ "string", "null" ] }, "parent_run_uuid": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "instruction": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "options": { "type": "object", "properties": { "sequential": { "type": "boolean" }, "allow_na": { "type": "boolean" }, "approval": { "type": "string" }, "photo_from_camera": { "type": "boolean" } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "integer" }, "title": { "type": "string" }, "item": { "type": "integer" }, "item_name": { "type": "string" }, "can_fill": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "hint": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "issue": { "type": "boolean" } } } } } }, "photo": { "type": "string" }, "required": { "type": "boolean" }, "critical": { "type": "boolean" }, "conditional": { "type": "boolean" }, "instruction": { "type": [ "string", "null" ] }, "mark": { "type": "object", "properties": { "status": { "type": "string" }, "value": { "type": "string" }, "display": { "type": "string" }, "flag": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "marked_at": { "type": "string", "format": "date-time" }, "task_uuid": { "type": "string", "format": "uuid" }, "spawned_run_uuid": { "type": [ "string", "null" ] } } } } } } } } }, "missing_required": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } } } }, "can": { "type": "object", "properties": { "fill": { "type": "boolean" }, "complete": { "type": "boolean" }, "accept": { "type": "boolean" }, "return": { "type": "boolean" }, "skip": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "routine": { "id": 12, "title": "Opening the shift" }, "category": "opening", "location": { "id": 4609, "name": "Abay Ave" }, "day": "2026-11-03", "trigger_type": "schedule", "label": "Morning", "opens_at": "2026-11-03T08:00:00+05:00", "due_at": "2026-11-03T09:00:00+05:00", "status": "in_progress", "late": false, "progress": { "done": 5, "total": 8, "issues": 1 }, "started_at": "2026-11-03T08:04:00+05:00", "started_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "completed_at": null, "completed_by": null, "reviewed_at": null, "reviewed_by": null, "review_note": null, "skip_reason": null, "parent_run_uuid": null, "updated_at": "2026-11-03T08:31:00+05:00", "url": "https://app.jecheck.io/ui/routines?run=9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "description": "Everything that must be done before the first guest arrives.", "instruction": { "uuid": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "title": "Opening standard" }, "options": { "sequential": false, "allow_na": true, "approval": "none", "photo_from_camera": true }, "sections": [ { "section_id": 31, "title": "Restrooms", "item": 0, "item_name": "Men", "can_fill": true, "steps": [ { "id": 210, "title": "Liquid soap", "hint": "Refill if less than a third is left", "type": "choice", "settings": { "options": [ { "key": "ok", "label": "Enough", "issue": false }, { "key": "none", "label": "Out of soap", "issue": true } ] }, "photo": "on_issue", "required": true, "critical": false, "conditional": false, "instruction": null, "mark": { "status": "issue", "value": "none", "display": "Out of soap", "flag": null, "reason": null, "comment": "Ordered from the warehouse", "photos": [ { "path": "routines/761/photos/2026/11/7f1e.jpg", "url": "https://storage.example.com/routines/761/photos/2026/11/7f1e.jpg?X-Amz-Signature=…" } ], "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "marked_at": "2026-11-03T08:12:00+05:00", "task_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "spawned_run_uuid": null } } ] } ], "missing_required": [ "Restrooms (Women): Liquid soap" ], "children": [ { "uuid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "title": "Restock consumables", "status": "pending", "trigger_type": "on_issue" } ], "can": { "fill": true, "complete": true, "accept": false, "return": false, "skip": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/absences": { "post": { "operationId": "scheduleAbsencesCreate", "summary": "Create an absence", "description": "Without `user_id` (or with the acting user) — a request of the acting user, goes to the manager. For another employee — recorded by the manager and approved right away (`schedule.requests` at the employee's location; `release_shifts` turns their shifts into open ones).", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_absences_create", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Employee, default — the acting user" }, "type": { "type": "string", "enum": [ "vacation", "sick", "day_off", "unpaid", "business_trip", "study", "maternity", "truancy", "other" ] }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date", "description": "Default — same day" }, "comment": { "type": "string", "maxLength": 1000 }, "paid": { "type": "boolean", "description": "Manager only: override whether the absence is paid" }, "file": { "type": "string", "description": "Document path from `schedule.media.upload` (`kind=absence`)" }, "release_shifts": { "type": "boolean" } }, "required": [ "type", "date_from" ] }, "example": { "user_id": 42, "type": "vacation", "date_from": "2026-11-01", "date_to": "2026-11-30" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 912, "uuid": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "pending", "paid": true, "comment": "Family trip", "file": null, "decided_by": null, "decided_at": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/absences/{uuid}/cancel": { "post": { "operationId": "scheduleAbsencesCancel", "summary": "Cancel an absence", "description": "The employee cancels their pending request; a manager with `schedule.requests` can cancel any absence of their employees.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_absences_cancel", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Absence UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 912, "uuid": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "pending", "paid": true, "comment": "Family trip", "file": null, "decided_by": null, "decided_at": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/absences/{uuid}/decide": { "post": { "operationId": "scheduleAbsencesDecide", "summary": "Approve or reject an absence request", "description": "Manager decision; the employee is notified. `release_shifts` makes their shifts in these days open.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_absences_decide", "x-permissions": [ "schedule.requests" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Absence UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean" }, "note": { "type": "string", "maxLength": 500 }, "release_shifts": { "type": "boolean" }, "paid": { "type": "boolean" } }, "required": [ "approve" ] }, "example": { "approve": true, "note": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "release_shifts": true, "paid": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 912, "uuid": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "pending", "paid": true, "comment": "Family trip", "file": null, "decided_by": null, "decided_at": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/attendance": { "get": { "operationId": "scheduleAttendance", "summary": "Get who is on shift", "description": "Attendance board by location: every published shift of the day with status (`upcoming`, `late`, `working`, `break`, `done`, `absent`, `missed`) and clock-ins without a shift. Phones only with `users.contacts`. Default — today at each location.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_attendance", "x-permissions": [ "schedule.attendance" ], "x-scope": "read", "parameters": [ { "name": "location_ids[]", "in": "query", "description": "Only these locations (default — all with `schedule.attendance`)", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "date", "in": "query", "description": "Day, default — today", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "date": { "type": "string", "format": "date" }, "now": { "type": "string" }, "counts": { "type": "object", "properties": { "working": { "type": "integer" }, "late": { "type": "integer" }, "upcoming": { "type": "integer" }, "total": { "type": "integer" } } }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "shift": { "type": "object", "properties": { "id": { "type": "integer" }, "start": { "type": "string" }, "end": { "type": "string" } } }, "attendance": { "type": "object", "properties": { "id": { "type": "integer" }, "in": { "type": "string" }, "out": { "type": [ "string", "null" ] }, "late_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "method": { "type": "string" }, "flags": { "type": "array", "items": { "type": "string" } } } }, "late_now_minutes": { "type": [ "string", "null" ] }, "absence": { "type": [ "string", "null" ] } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "location": { "id": 4609, "name": "Abay Ave" }, "date": "2026-11-03", "now": "09:15", "counts": { "working": 3, "late": 1, "upcoming": 2, "total": 6 }, "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position": "Barista", "phone": null, "status": "working", "shift": { "id": 70211, "start": "09:00", "end": "18:00" }, "attendance": { "id": 55120, "in": "09:04", "out": null, "late_minutes": 4, "worked_minutes": 11, "method": "app", "flags": [ "late" ] }, "late_now_minutes": null, "absence": null } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/attendance/records": { "get": { "operationId": "scheduleAttendanceList", "summary": "List attendance records", "description": "Clock-in/out journal at locations with `schedule.attendance`, newest first (max 1000 per period). `flag`: `late`, `early`, `out_of_zone`, `manual`, `offline`, `auto_closed`, `unapproved`. Default period — last 7 days.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_attendance_list", "x-permissions": [ "schedule.attendance" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "flag", "in": "query", "schema": { "type": "string", "maxLength": 30 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "date": { "type": "string", "format": "date" }, "clock_in": { "type": "string" }, "clock_out": { "type": "string" }, "shift": { "type": "object", "properties": { "id": { "type": "integer" }, "start": { "type": "string" }, "end": { "type": "string" }, "minutes": { "type": "integer" } } }, "break_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "approved": { "type": "boolean" }, "status": { "type": "string" }, "in_method": { "type": "string" }, "out_method": { "type": "string" }, "in_distance": { "type": "integer" }, "out_distance": { "type": "integer" }, "in_photo": { "type": [ "string", "null" ] }, "out_photo": { "type": [ "string", "null" ] }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "flags": { "type": "array", "items": { "type": "string" } }, "note": { "type": [ "string", "null" ] }, "edits": { "type": "integer" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 55120, "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "location": { "id": 4609, "name": "Abay Ave" }, "date": "2026-11-03", "clock_in": "2026-11-03 09:04", "clock_out": "2026-11-03 18:02", "shift": { "id": 70211, "start": "09:00", "end": "18:00", "minutes": 480 }, "break_minutes": 30, "worked_minutes": 508, "approved_minutes": null, "approved": false, "status": "closed", "in_method": "app", "out_method": "app", "in_distance": 12, "out_distance": 20, "in_photo": null, "out_photo": null, "late_minutes": 4, "early_minutes": 0, "flags": [ "late" ], "note": null, "edits": 0 } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "scheduleAttendanceCreate", "summary": "Add an attendance record", "description": "Manual attendance for an employee (forgot to clock in) with a reason; written to the edit history. Times are local wall time `YYYY-MM-DD HH:MM`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_attendance_create", "x-permissions": [ "schedule.attendance" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "location_id": { "type": "integer" }, "shift_id": { "type": "integer" }, "clock_in": { "type": "string", "description": "`YYYY-MM-DD HH:MM`, local" }, "clock_out": { "type": [ "string", "null" ], "description": "`YYYY-MM-DD HH:MM`, local" }, "break_minutes": { "type": "integer", "minimum": 0 }, "approved_minutes": { "type": [ "integer", "null" ], "minimum": 0 }, "note": { "type": "string", "maxLength": 500 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "user_id", "location_id", "clock_in", "reason" ] }, "example": { "user_id": 42, "location_id": 12, "shift_id": 42, "clock_in": "string", "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 55121 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/attendance/records/approve": { "post": { "operationId": "scheduleAttendanceApprove", "summary": "Approve attendance records", "description": "Approves worked minutes of closed records (they go to the timesheet as approved). `minutes` overrides the value when approving one record.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_attendance_approve", "x-permissions": [ "schedule.attendance" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 500 }, "minutes": { "type": "integer", "minimum": 0 } }, "required": [ "ids" ] }, "example": { "ids": [ 12, 14 ], "minutes": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "approved": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "approved": 12 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/attendance/records/{id}": { "patch": { "operationId": "scheduleAttendanceUpdate", "summary": "Correct an attendance record", "description": "Corrects times of an attendance record with a reason (kept in history). Rejected in a closed month.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_attendance_update", "x-permissions": [ "schedule.attendance" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Attendance id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clock_in": { "type": "string", "description": "`YYYY-MM-DD HH:MM`, local" }, "clock_out": { "type": [ "string", "null" ] }, "break_minutes": { "type": "integer", "minimum": 0 }, "approved_minutes": { "type": [ "integer", "null" ], "minimum": 0 }, "note": { "type": "string", "maxLength": 500 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "reason" ] }, "example": { "clock_in": "string", "clock_out": "string", "break_minutes": 42, "approved_minutes": 42, "reason": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "updated": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 55120, "updated": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "scheduleAttendanceDelete", "summary": "Delete an attendance record", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_attendance_delete", "x-permissions": [ "schedule.attendance" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Attendance id", "schema": { "type": "integer" } }, { "name": "reason", "in": "query", "required": true, "description": "Why the record is deleted", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/autofill": { "post": { "operationId": "scheduleAutofill", "summary": "Auto-fill the schedule", "description": "Assigns employees to shifts by demand, availability, absences and rules; unfilled demand becomes open shifts (unless `create_open=false`).", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_autofill", "x-permissions": [ "schedule.edit" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "create_open": { "type": "boolean" } }, "required": [ "location_id", "date_from", "date_to" ] }, "example": { "location_id": 12, "date_from": "2026-11-01", "date_to": "2026-11-30", "create_open": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assigned": { "type": "integer" }, "open": { "type": "integer" }, "unfilled": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "assigned": 18, "open": 2, "unfilled": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/availability": { "get": { "operationId": "scheduleAvailabilityGet", "summary": "Get availability", "description": "Weekly / dated availability preferences of the acting user, or of an employee the token manages (`schedule.edit`).", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_availability_get", "x-scope": "read", "parameters": [ { "name": "user_id", "in": "query", "description": "Employee, default — the acting user", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "weekday": { "type": "integer" }, "date": { "type": [ "string", "null" ] }, "start_time": { "type": [ "string", "null" ] }, "end_time": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "note": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 15, "weekday": 6, "date": null, "start_time": null, "end_time": null, "kind": "unavailable", "note": "University" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "scheduleAvailabilitySet", "summary": "Replace availability", "description": "Replaces all availability items of the acting user (or a managed employee). Each item: `weekday` (1–7) or `date`, optional `start_time`/`end_time` `HH:MM`, `kind` `unavailable` | `preferred`, `note`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_availability_set", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Employee, default — the acting user" }, "items": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": 1, "maximum": 7 }, "date": { "type": "string", "format": "date" }, "start_time": { "type": "string" }, "end_time": { "type": "string" }, "kind": { "type": "string", "enum": [ "unavailable", "preferred" ] }, "note": { "type": "string", "maxLength": 255 } } }, "maxItems": 100 } }, "required": [ "items" ] }, "example": { "user_id": 42, "items": [ { "weekday": 42, "date": "2026-11-01", "start_time": "string" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "weekday": { "type": "integer" }, "date": { "type": [ "string", "null" ] }, "start_time": { "type": [ "string", "null" ] }, "end_time": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "note": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 15, "weekday": 6, "date": null, "start_time": null, "end_time": null, "kind": "unavailable", "note": "University" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/board": { "get": { "operationId": "scheduleBoard", "summary": "Get the schedule board of a location", "description": "What the schedule grid shows for one location: employees with hour totals, shifts with warnings and attendance, absences, availability, demand coverage and totals. Shift cost, employee rates and the budget are included only with `pay.rates.view` at the location.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_board", "x-permissions": [ "schedule.view" ], "x-scope": "read", "parameters": [ { "name": "location_id", "in": "query", "required": true, "description": "Location id", "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "weekday": { "type": "integer" }, "holiday": { "type": [ "string", "null" ] } } } }, "employees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "totals": { "type": "object", "properties": { "minutes": { "type": "integer" }, "shifts": { "type": "integer" }, "cost": { "type": "integer" } } } } } }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "template_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "overnight": { "type": "boolean" }, "break_minutes": { "type": "integer" }, "minutes": { "type": "integer" }, "status": { "type": "string" }, "published": { "type": "boolean" }, "removed": { "type": "boolean" }, "open": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "warnings": { "type": "array" }, "cost": { "type": "integer" }, "attendance": { "type": [ "string", "null" ] } } } }, "absences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "type": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "status": { "type": "string" } } } }, "availability": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "kind": { "type": "string" }, "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "note": { "type": "string" } } } }, "coverage": { "type": "object", "properties": { "2026-11-02": { "type": "array", "items": { "type": "object", "properties": { "position_id": { "type": "integer" }, "start": { "type": "string" }, "end": { "type": "string" }, "need": { "type": "integer" }, "have": { "type": "integer" } } } } } }, "totals": { "type": "object", "properties": { "minutes": { "type": "integer" }, "cost": { "type": "integer" }, "budget": { "type": "integer" } } }, "unpublished": { "type": "integer" }, "warnings_count": { "type": "integer" }, "can_pay": { "type": "boolean" }, "can_edit": { "type": "boolean" }, "can_publish": { "type": "boolean" }, "currency": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "location": { "id": 4609, "name": "Abay Ave" }, "date_from": "2026-11-02", "date_to": "2026-11-08", "days": [ { "date": "2026-11-02", "weekday": 1, "holiday": null } ], "employees": [ { "id": 311, "name": "Aigerim Sadykova", "position_id": 12, "position": "Barista", "pay_type": "hourly", "rate": 1500, "totals": { "minutes": 2400, "shifts": 5, "cost": 60000 } } ], "shifts": [ { "id": 70211, "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "location": { "id": 4609, "name": "Abay Ave" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position_id": 12, "template_id": 3, "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "overnight": false, "break_minutes": 60, "minutes": 480, "status": "published", "published": true, "removed": false, "open": false, "note": null, "color": null, "updated_at": "2026-11-01T12:00:00+05:00", "warnings": [], "cost": 12000, "attendance": null } ], "absences": [ { "id": 912, "user_id": 311, "type": "vacation", "from": "2026-12-01", "to": "2026-12-14", "status": "approved" } ], "availability": [ { "user_id": 311, "date": "2026-11-06", "kind": "unavailable", "start": null, "end": null, "note": "University" } ], "coverage": { "2026-11-02": [ { "position_id": 12, "start": "08:00", "end": "12:00", "need": 2, "have": 1 } ] }, "totals": { "minutes": 9600, "cost": 240000, "budget": 300000 }, "unpublished": 3, "warnings_count": 1, "can_pay": true, "can_edit": true, "can_publish": true, "currency": "KZT" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/clear": { "post": { "operationId": "scheduleClear", "summary": "Clear shifts of a period", "description": "Deletes the shifts of a location for a period (published ones are marked removed until publishing).", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_clear", "x-permissions": [ "schedule.edit" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" } }, "required": [ "location_id", "date_from", "date_to" ] }, "example": { "location_id": 12, "date_from": "2026-11-01", "date_to": "2026-11-30" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cleared": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "cleared": 12 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/clock": { "get": { "operationId": "scheduleClockState", "summary": "Get my clock state", "description": "Whether the acting user is on shift / on a break, the open attendance, current and next shift, clock-in locations with geofence and the company clock rules.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_clock_state", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "on_shift": { "type": "boolean" }, "on_break": { "type": "boolean" }, "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "current_shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer" }, "hours": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "open": { "type": "boolean" } } }, "next_shift": { "type": [ "string", "null" ] }, "sites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "radius": { "type": "integer" } } } }, "rules": { "type": "object", "properties": { "require_geo": { "type": "boolean" }, "require_photo": { "type": "boolean" }, "block_out_of_zone": { "type": "boolean" }, "allow_without_shift": { "type": "boolean" }, "early_clock_in_minutes": { "type": "integer" }, "allow_web_clock": { "type": "boolean" } } }, "server_time": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "on_shift": true, "on_break": false, "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "current_shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "break_minutes": 60, "hours": 8, "location": { "id": 4609, "name": "Abay Ave" }, "position_id": 12, "position": "Barista", "note": null, "open": false }, "next_shift": null, "sites": [ { "id": 4609, "name": "Abay Ave", "latitude": 43.2389, "longitude": 76.8897, "radius": 150 } ], "rules": { "require_geo": true, "require_photo": false, "block_out_of_zone": false, "allow_without_shift": true, "early_clock_in_minutes": 30, "allow_web_clock": false }, "server_time": "2026-11-03T09:05:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/clock/break-end": { "post": { "operationId": "scheduleClockBreakEnd", "summary": "End a break", "description": "Ends the current break. Errors: `not_in`, `no_break`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_clock_break_end", "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Client UUID of the clock-in, for safe retries" }, "attendance_uuid": { "type": "string", "format": "uuid", "description": "Attendance to close (clock-out); default — the open one" }, "location_id": { "type": "integer", "description": "Location; default — from the shift or geolocation" }, "shift_uuid": { "type": "string", "format": "uuid", "description": "Shift being worked" }, "qr": { "type": "string", "description": "Scanned QR content (link `/clock/{token}` or the token)", "maxLength": 500 }, "lat": { "type": "number" }, "lng": { "type": "number" }, "photo": { "type": "string", "description": "Photo path from `schedule.media.upload`" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Device time for offline sync" }, "note": { "type": "string", "maxLength": 500 } } }, "example": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "attendance_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "location_id": 12, "shift_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "clock": { "type": "object", "properties": { "on_shift": { "type": "boolean" }, "on_break": { "type": "boolean" }, "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "current_shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer" }, "hours": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "open": { "type": "boolean" } } }, "next_shift": { "type": [ "string", "null" ] }, "sites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "radius": { "type": "integer" } } } }, "rules": { "type": "object", "properties": { "require_geo": { "type": "boolean" }, "require_photo": { "type": "boolean" }, "block_out_of_zone": { "type": "boolean" }, "allow_without_shift": { "type": "boolean" }, "early_clock_in_minutes": { "type": "integer" }, "allow_web_clock": { "type": "boolean" } } }, "server_time": { "type": "string", "format": "date-time" } } } } } }, "required": [ "data" ] }, "example": { "data": { "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "clock": { "on_shift": true, "on_break": false, "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "current_shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "break_minutes": 60, "hours": 8, "location": { "id": 4609, "name": "Abay Ave" }, "position_id": 12, "position": "Barista", "note": null, "open": false }, "next_shift": null, "sites": [ { "id": 4609, "name": "Abay Ave", "latitude": 43.2389, "longitude": 76.8897, "radius": 150 } ], "rules": { "require_geo": true, "require_photo": false, "block_out_of_zone": false, "allow_without_shift": true, "early_clock_in_minutes": 30, "allow_web_clock": false }, "server_time": "2026-11-03T09:05:00+05:00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/clock/break-start": { "post": { "operationId": "scheduleClockBreakStart", "summary": "Start a break", "description": "Starts a break in the open attendance. Errors: `not_in`, `break_open`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_clock_break_start", "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Client UUID of the clock-in, for safe retries" }, "attendance_uuid": { "type": "string", "format": "uuid", "description": "Attendance to close (clock-out); default — the open one" }, "location_id": { "type": "integer", "description": "Location; default — from the shift or geolocation" }, "shift_uuid": { "type": "string", "format": "uuid", "description": "Shift being worked" }, "qr": { "type": "string", "description": "Scanned QR content (link `/clock/{token}` or the token)", "maxLength": 500 }, "lat": { "type": "number" }, "lng": { "type": "number" }, "photo": { "type": "string", "description": "Photo path from `schedule.media.upload`" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Device time for offline sync" }, "note": { "type": "string", "maxLength": 500 } } }, "example": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "attendance_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "location_id": 12, "shift_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "clock": { "type": "object", "properties": { "on_shift": { "type": "boolean" }, "on_break": { "type": "boolean" }, "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "current_shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer" }, "hours": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "open": { "type": "boolean" } } }, "next_shift": { "type": [ "string", "null" ] }, "sites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "radius": { "type": "integer" } } } }, "rules": { "type": "object", "properties": { "require_geo": { "type": "boolean" }, "require_photo": { "type": "boolean" }, "block_out_of_zone": { "type": "boolean" }, "allow_without_shift": { "type": "boolean" }, "early_clock_in_minutes": { "type": "integer" }, "allow_web_clock": { "type": "boolean" } } }, "server_time": { "type": "string", "format": "date-time" } } } } } }, "required": [ "data" ] }, "example": { "data": { "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "clock": { "on_shift": true, "on_break": false, "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "current_shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "break_minutes": 60, "hours": 8, "location": { "id": 4609, "name": "Abay Ave" }, "position_id": 12, "position": "Barista", "note": null, "open": false }, "next_shift": null, "sites": [ { "id": 4609, "name": "Abay Ave", "latitude": 43.2389, "longitude": 76.8897, "radius": 150 } ], "rules": { "require_geo": true, "require_photo": false, "block_out_of_zone": false, "allow_without_shift": true, "early_clock_in_minutes": 30, "allow_web_clock": false }, "server_time": "2026-11-03T09:05:00+05:00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/clock/in": { "post": { "operationId": "scheduleClockIn", "summary": "Clock in", "description": "Starts attendance for the acting user (same rules as the mobile app: geofence, photo, early clock-in limit, matching shift). Repeating the same `uuid` returns the existing record. Errors carry a reason code: `already_in`, `no_shift`, `too_early`, `geo_required`, `out_of_zone`, `photo_required`, `qr_invalid`, `department_required`, `bad_time`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_clock_in", "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Client UUID of the clock-in, for safe retries" }, "attendance_uuid": { "type": "string", "format": "uuid", "description": "Attendance to close (clock-out); default — the open one" }, "location_id": { "type": "integer", "description": "Location; default — from the shift or geolocation" }, "shift_uuid": { "type": "string", "format": "uuid", "description": "Shift being worked" }, "qr": { "type": "string", "description": "Scanned QR content (link `/clock/{token}` or the token)", "maxLength": 500 }, "lat": { "type": "number" }, "lng": { "type": "number" }, "photo": { "type": "string", "description": "Photo path from `schedule.media.upload`" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Device time for offline sync" }, "note": { "type": "string", "maxLength": 500 } } }, "example": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "attendance_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "location_id": 12, "shift_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "clock": { "type": "object", "properties": { "on_shift": { "type": "boolean" }, "on_break": { "type": "boolean" }, "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "current_shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer" }, "hours": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "open": { "type": "boolean" } } }, "next_shift": { "type": [ "string", "null" ] }, "sites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "radius": { "type": "integer" } } } }, "rules": { "type": "object", "properties": { "require_geo": { "type": "boolean" }, "require_photo": { "type": "boolean" }, "block_out_of_zone": { "type": "boolean" }, "allow_without_shift": { "type": "boolean" }, "early_clock_in_minutes": { "type": "integer" }, "allow_web_clock": { "type": "boolean" } } }, "server_time": { "type": "string", "format": "date-time" } } } } } }, "required": [ "data" ] }, "example": { "data": { "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "clock": { "on_shift": true, "on_break": false, "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "current_shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "break_minutes": 60, "hours": 8, "location": { "id": 4609, "name": "Abay Ave" }, "position_id": 12, "position": "Barista", "note": null, "open": false }, "next_shift": null, "sites": [ { "id": 4609, "name": "Abay Ave", "latitude": 43.2389, "longitude": 76.8897, "radius": 150 } ], "rules": { "require_geo": true, "require_photo": false, "block_out_of_zone": false, "allow_without_shift": true, "early_clock_in_minutes": 30, "allow_web_clock": false }, "server_time": "2026-11-03T09:05:00+05:00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/clock/out": { "post": { "operationId": "scheduleClockOut", "summary": "Clock out", "description": "Closes the open attendance of the acting user and computes worked minutes. Errors: `not_in`, `break_open`, `bad_time`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_clock_out", "x-scope": "write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Client UUID of the clock-in, for safe retries" }, "attendance_uuid": { "type": "string", "format": "uuid", "description": "Attendance to close (clock-out); default — the open one" }, "location_id": { "type": "integer", "description": "Location; default — from the shift or geolocation" }, "shift_uuid": { "type": "string", "format": "uuid", "description": "Shift being worked" }, "qr": { "type": "string", "description": "Scanned QR content (link `/clock/{token}` or the token)", "maxLength": 500 }, "lat": { "type": "number" }, "lng": { "type": "number" }, "photo": { "type": "string", "description": "Photo path from `schedule.media.upload`" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Device time for offline sync" }, "note": { "type": "string", "maxLength": 500 } } }, "example": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "attendance_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "location_id": 12, "shift_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "clock": { "type": "object", "properties": { "on_shift": { "type": "boolean" }, "on_break": { "type": "boolean" }, "attendance": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "clock_in_at": { "type": "string", "format": "date-time" }, "clock_out_at": { "type": [ "string", "null" ] }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } }, "status": { "type": "string" }, "late_minutes": { "type": "integer" }, "early_minutes": { "type": "integer" }, "worked_minutes": { "type": "integer" }, "approved_minutes": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } } } }, "current_shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer" }, "hours": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "open": { "type": "boolean" } } }, "next_shift": { "type": [ "string", "null" ] }, "sites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "radius": { "type": "integer" } } } }, "rules": { "type": "object", "properties": { "require_geo": { "type": "boolean" }, "require_photo": { "type": "boolean" }, "block_out_of_zone": { "type": "boolean" }, "allow_without_shift": { "type": "boolean" }, "early_clock_in_minutes": { "type": "integer" }, "allow_web_clock": { "type": "boolean" } } }, "server_time": { "type": "string", "format": "date-time" } } } } } }, "required": [ "data" ] }, "example": { "data": { "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "clock": { "on_shift": true, "on_break": false, "attendance": { "uuid": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "date": "2026-11-03", "location": { "id": 4609, "name": "Abay Ave" }, "clock_in_at": "2026-11-03T09:04:00+05:00", "clock_out_at": null, "breaks": [ { "start": "13:00", "end": "13:30" } ], "status": "open", "late_minutes": 4, "early_minutes": 0, "worked_minutes": 0, "approved_minutes": null, "flags": [ "late" ] }, "current_shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "break_minutes": 60, "hours": 8, "location": { "id": 4609, "name": "Abay Ave" }, "position_id": 12, "position": "Barista", "note": null, "open": false }, "next_shift": null, "sites": [ { "id": 4609, "name": "Abay Ave", "latitude": 43.2389, "longitude": 76.8897, "radius": 150 } ], "rules": { "require_geo": true, "require_photo": false, "block_out_of_zone": false, "allow_without_shift": true, "early_clock_in_minutes": 30, "allow_web_clock": false }, "server_time": "2026-11-03T09:05:00+05:00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/copy": { "post": { "operationId": "scheduleCopy", "summary": "Copy shifts to another period", "description": "Copies the shifts of `days` days starting at `date_from` to `target_date`, optionally repeated. Absent employees are skipped. Copies are drafts.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_copy", "x-permissions": [ "schedule.edit" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer" }, "date_from": { "type": "string", "format": "date" }, "days": { "type": "integer", "minimum": 1, "maximum": 31 }, "target_date": { "type": "string", "format": "date" }, "repeat": { "type": "integer", "description": "How many times to repeat, default 1", "minimum": 1, "maximum": 12 }, "replace": { "type": "boolean", "description": "Replace existing shifts in the target period" } }, "required": [ "location_id", "date_from", "days", "target_date" ] }, "example": { "location_id": 12, "date_from": "2026-11-01", "days": 42, "target_date": "2026-11-01" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "created": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "created": 35 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/kpi": { "get": { "operationId": "scheduleKpi", "summary": "Get the KPI scorecard", "description": "KPI metrics and each employee's values, achievement and total score for a month. The KPI bonus base is included only with `pay.rates.view`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_kpi", "x-permissions": [ "schedule.kpi" ], "x-plan-feature": "payroll", "x-scope": "read", "parameters": [ { "name": "month", "in": "query", "description": "Month `YYYY-MM`, default — current", "schema": { "type": "string" } }, { "name": "location_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "month": { "type": "string" }, "closed": { "type": "boolean" }, "threshold": { "type": "integer" }, "cap": { "type": "integer" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "unit": { "type": "string" }, "source": { "type": "string" }, "direction": { "type": "string" }, "target": { "type": "integer" }, "weight": { "type": "integer" }, "position_ids": { "type": "array" }, "active": { "type": "boolean" } } } }, "people": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position": { "type": "string" }, "kpi_bonus": { "type": "integer" }, "kpi_bonus_type": { "type": "string" }, "score": { "type": "number" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "metric_id": { "type": "integer" }, "value": { "type": "integer" }, "auto": { "type": "integer" }, "manual": { "type": "boolean" }, "comment": { "type": [ "string", "null" ] }, "achievement": { "type": "number" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "month": "2026-11", "closed": false, "threshold": 70, "cap": 120, "metrics": [ { "id": 4, "name": "Punctuality", "description": null, "unit": "%", "source": "punctuality", "direction": "up", "target": 95, "weight": 30, "position_ids": [], "active": true } ], "people": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position": "Barista", "kpi_bonus": 20000, "kpi_bonus_type": "fixed", "score": 96.5, "metrics": [ { "metric_id": 4, "value": 98, "auto": 98, "manual": false, "comment": null, "achievement": 103.2 } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/kpi/values": { "post": { "operationId": "scheduleKpiValuesSet", "summary": "Set a KPI value", "description": "Sets (or overrides an automatic) value of a metric for an employee and month. `value: null` clears the manual value.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_kpi_values_set", "x-permissions": [ "schedule.kpi" ], "x-plan-feature": "payroll", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metric_id": { "type": "integer" }, "user_id": { "type": "integer" }, "month": { "type": "string", "description": "`YYYY-MM`" }, "value": { "type": [ "number", "null" ] }, "comment": { "type": "string", "maxLength": 500 } }, "required": [ "metric_id", "user_id", "month" ] }, "example": { "metric_id": 42, "user_id": 42, "month": "string", "value": 4.5 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "saved": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "saved": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/media": { "post": { "operationId": "scheduleMediaUpload", "summary": "Upload a clock photo or request file", "description": "`kind=clock` — selfie for clock-in/out (image up to 8 MB); `kind=absence` — document for an absence request (image or PDF up to 10 MB). Returns the `path` to pass as `photo` / `file`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_media_upload", "x-scope": "write", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File (multipart; in MCP — object with `name` and `content_base64`)" }, "kind": { "type": "string", "enum": [ "clock", "absence" ], "default": "clock" } }, "required": [ "file" ] } }, "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } }, "description": "File (multipart; in MCP — object with `name` and `content_base64`)" }, "kind": { "type": "string", "enum": [ "clock", "absence" ], "default": "clock" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "path": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "path": "staff/761/clock/2026/11/0f1e.jpg" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/my/month": { "get": { "operationId": "scheduleMyMonth", "summary": "Get my hours for a month", "description": "Timesheet of the acting user for a month: totals and day codes; accrued pay only if the company shows pay to staff.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_my_month", "x-scope": "read", "parameters": [ { "name": "month", "in": "query", "description": "Month `YYYY-MM`, default — current", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "month": { "type": "string" }, "totals": { "type": "object", "properties": { "planned_hours": { "type": "integer" }, "hours": { "type": "number" }, "night_hours": { "type": "integer" }, "holiday_hours": { "type": "integer" }, "overtime_hours": { "type": "integer" }, "days": { "type": "integer" }, "late_count": { "type": "integer" }, "late_minutes": { "type": "integer" }, "absences": { "type": "array" } } }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "code": { "type": "string" }, "planned": { "type": "integer" }, "hours": { "type": "number" }, "late": { "type": "integer" } } } }, "pay": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "month": "2026-11", "totals": { "planned_hours": 168, "hours": 52.5, "night_hours": 0, "holiday_hours": 0, "overtime_hours": 0, "days": 7, "late_count": 1, "late_minutes": 4, "absences": [] }, "days": [ { "date": "2026-11-03", "code": "Я", "planned": 480, "hours": 7.5, "late": 4 } ], "pay": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/my/requests": { "get": { "operationId": "scheduleMyRequests", "summary": "List my requests", "description": "Absences of the acting user (last 60 days and future) and swap requests — own and incoming (`can_answer`).", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_my_requests", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "absences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "swaps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" }, "from_user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "to_user": { "type": [ "string", "null" ] }, "shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "to_shift": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "mine": { "type": "boolean" }, "can_answer": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "absences": [ { "id": 912, "uuid": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "pending", "paid": true, "comment": "Family trip", "file": null, "decided_by": null, "decided_at": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } ], "swaps": [ { "id": 340, "uuid": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a", "type": "give", "status": "pending_peer", "note": "Doctor appointment", "from_user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "to_user": null, "shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "location": { "id": 4609, "name": "Abay Ave" } }, "to_shift": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00", "mine": true, "can_answer": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/my/shifts": { "get": { "operationId": "scheduleMyShifts", "summary": "List my shifts", "description": "Published shifts of the acting user with attendance and (if enabled by the company) colleagues on the same shift. Default — current week, max 62 days.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_my_shifts", "x-scope": "read", "parameters": [ { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer" }, "hours": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "open": { "type": "boolean" }, "pending_change": { "type": "boolean" }, "attendance": { "type": [ "string", "null" ] }, "colleagues": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "position": { "type": "string" }, "shift_uuid": { "type": "string", "format": "uuid" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "break_minutes": 60, "hours": 8, "location": { "id": 4609, "name": "Abay Ave" }, "position_id": 12, "position": "Barista", "note": null, "open": false, "pending_change": false, "attendance": null, "colleagues": [ { "user_id": 312, "name": "Arman Bekov", "start": "09:00", "end": "18:00", "position": "Cashier", "shift_uuid": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/open-shifts": { "get": { "operationId": "scheduleOpenShiftsList", "summary": "List open shifts I can take", "description": "Published unassigned future shifts at locations where the acting user may work, matching the position and without overlaps.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_open_shifts_list", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "break_minutes": { "type": "integer" }, "hours": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "position": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "open": { "type": "boolean" }, "requested": { "type": "boolean" }, "taken": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "break_minutes": 60, "hours": 8, "location": { "id": 4609, "name": "Abay Ave" }, "position_id": 12, "position": "Barista", "note": null, "open": false, "requested": false, "taken": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/open-shifts/{uuid}/claim": { "post": { "operationId": "scheduleOpenShiftsClaim", "summary": "Claim an open shift", "description": "Takes an open shift: assigned right away or sent to the manager, depending on company rules.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_open_shifts_claim", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Shift UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500 } } }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "status": "approved" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/payroll": { "get": { "operationId": "schedulePayroll", "summary": "Get the payroll", "description": "Payroll for a month by employee: hours, amounts (base, night, holiday, overtime, KPI, adjustments, deductions, payable) and status (`draft`, `approved`, `paid`). Sensitive: requires `pay.payroll.view` (locations of the employees); each call is written to the access log. `rate` / `pay_type` are omitted for employees of locations without `pay.rates.view`.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_payroll", "x-permissions": [ "pay.payroll.view" ], "x-plan-feature": "payroll", "x-scope": "read", "parameters": [ { "name": "month", "in": "query", "description": "Month `YYYY-MM`, default — current", "schema": { "type": "string" } }, { "name": "location_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "month": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "approved_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "string" }, "personnel_no": { "type": "string" }, "location_ids": { "type": "array", "items": { "type": "integer" } } } }, "pay_type": { "type": "string" }, "rate": { "type": "integer" }, "hours": { "type": "object", "properties": { "planned": { "type": "integer" }, "payable": { "type": "number" }, "night": { "type": "integer" }, "holiday": { "type": "integer" }, "overtime": { "type": "number" } } }, "days": { "type": "integer" }, "shifts": { "type": "integer" }, "late_count": { "type": "integer" }, "no_show": { "type": "integer" }, "paid_absence_days": { "type": "integer" }, "absences": { "type": "array" }, "kpi_score": { "type": "number" }, "amounts": { "type": "object", "properties": { "base": { "type": "integer" }, "night": { "type": "integer" }, "holiday": { "type": "integer" }, "overtime": { "type": "integer" }, "absence": { "type": "integer" }, "kpi": { "type": "integer" }, "bonus": { "type": "integer" }, "compensation": { "type": "integer" }, "accrued": { "type": "integer" }, "penalty": { "type": "integer" }, "deduction": { "type": "integer" }, "advance": { "type": "integer" }, "percent": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "percent": { "type": "integer" }, "amount": { "type": "number" } } } }, "deducted": { "type": "number" }, "payable": { "type": "number" } } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "amount": { "type": "integer" }, "comment": { "type": "string" } } } }, "norm_hours": { "type": "integer" } } } }, "totals": { "type": "object", "properties": { "base": { "type": "integer" }, "night": { "type": "integer" }, "holiday": { "type": "integer" }, "overtime": { "type": "integer" }, "absence": { "type": "integer" }, "kpi": { "type": "integer" }, "bonus": { "type": "integer" }, "compensation": { "type": "integer" }, "accrued": { "type": "integer" }, "penalty": { "type": "integer" }, "deduction": { "type": "integer" }, "advance": { "type": "integer" }, "deducted": { "type": "number" }, "payable": { "type": "number" }, "hours": { "type": "number" }, "people": { "type": "integer" } } } } } }, "required": [ "data" ] }, "example": { "data": { "month": "2026-10", "currency": "KZT", "status": "approved", "approved_at": "2026-11-02T10:00:00+05:00", "paid_at": null, "lines": [ { "user": { "id": 311, "name": "Aigerim Sadykova", "position": "Barista", "personnel_no": "A-17", "location_ids": [ 4609 ] }, "pay_type": "hourly", "rate": 1500, "hours": { "planned": 168, "payable": 170.5, "night": 0, "holiday": 8, "overtime": 2.5 }, "days": 21, "shifts": 21, "late_count": 2, "no_show": 0, "paid_absence_days": 0, "absences": [], "kpi_score": 96.5, "amounts": { "base": 255750, "night": 0, "holiday": 12000, "overtime": 5625, "absence": 0, "kpi": 20000, "bonus": 0, "compensation": 0, "accrued": 293375, "penalty": 0, "deduction": 0, "advance": 50000, "percent": [ { "name": "IIT", "percent": 10, "amount": 29337.5 } ], "deducted": 79337.5, "payable": 214037.5 }, "adjustments": [ { "id": 81, "kind": "advance", "amount": 50000, "comment": "Mid-month advance" } ], "norm_hours": 168 } ], "totals": { "base": 255750, "night": 0, "holiday": 12000, "overtime": 5625, "absence": 0, "kpi": 20000, "bonus": 0, "compensation": 0, "accrued": 293375, "penalty": 0, "deduction": 0, "advance": 50000, "deducted": 79337.5, "payable": 214037.5, "hours": 170.5, "people": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/payroll/adjustments": { "post": { "operationId": "schedulePayrollAdjustmentsCreate", "summary": "Add a payroll adjustment", "description": "Bonus, compensation, penalty, deduction or advance for an employee in an open month.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_payroll_adjustments_create", "x-permissions": [ "pay.payroll.approve" ], "x-plan-feature": "payroll", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "month": { "type": "string", "description": "`YYYY-MM`" }, "kind": { "type": "string", "enum": [ "bonus", "compensation", "penalty", "deduction", "advance" ] }, "amount": { "type": "number", "minimum": 0.01 }, "comment": { "type": "string", "maxLength": 500 } }, "required": [ "user_id", "month", "kind", "amount" ] }, "example": { "user_id": 42, "month": "string", "kind": "bonus", "amount": 4.5 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "month": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": "integer" }, "comment": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 81, "user_id": 311, "month": "2026-11", "kind": "advance", "amount": 50000, "comment": "Mid-month advance" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/payroll/adjustments/{id}": { "delete": { "operationId": "schedulePayrollAdjustmentsDelete", "summary": "Delete a payroll adjustment", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_payroll_adjustments_delete", "x-permissions": [ "pay.payroll.approve" ], "x-plan-feature": "payroll", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Adjustment id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/payroll/approve": { "post": { "operationId": "schedulePayrollApprove", "summary": "Approve the payroll", "description": "Freezes the payroll of a month and closes the month for changes of shifts, attendance and absences. Requires `pay.payroll.approve` at all locations.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_payroll_approve", "x-permissions": [ "pay.payroll.approve" ], "x-plan-feature": "payroll", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`" } }, "required": [ "month" ] }, "example": { "month": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "month": { "type": "string" }, "status": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "month": "2026-10", "status": "approved" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/payroll/paid": { "post": { "operationId": "schedulePayrollPaid", "summary": "Mark the payroll as paid", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_payroll_paid", "x-permissions": [ "pay.payroll.approve" ], "x-plan-feature": "payroll", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`" }, "paid": { "type": "boolean", "description": "`false` — undo, default `true`" } }, "required": [ "month" ] }, "example": { "month": "string", "paid": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "month": { "type": "string" }, "paid": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "month": "2026-10", "paid": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/payroll/reopen": { "post": { "operationId": "schedulePayrollReopen", "summary": "Reopen the payroll", "description": "Reopens an approved month for corrections.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_payroll_reopen", "x-permissions": [ "pay.payroll.approve" ], "x-plan-feature": "payroll", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`" } }, "required": [ "month" ] }, "example": { "month": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "month": { "type": "string" }, "status": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "month": "2026-10", "status": "draft" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/publish": { "post": { "operationId": "schedulePublish", "summary": "Publish the schedule", "description": "Publishes drafts and changes of a location for a period; affected employees are notified (unless `notify=false`).", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_publish", "x-permissions": [ "schedule.publish" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "notify": { "type": "boolean", "description": "Notify employees, default `true`" } }, "required": [ "location_id", "date_from", "date_to" ] }, "example": { "location_id": 12, "date_from": "2026-11-01", "date_to": "2026-11-30", "notify": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "published": { "type": "integer" }, "removed": { "type": "integer" }, "notified": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "published": 24, "removed": 1, "notified": 9 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/requests": { "get": { "operationId": "scheduleRequestsList", "summary": "List absence and swap requests", "description": "Requests of employees of locations with `schedule.requests`: `pending` (default) or `history` (decided in the last 90 days).", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_requests_list", "x-permissions": [ "schedule.requests" ], "x-scope": "read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "history" ], "default": "pending" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "absences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "type": { "type": "string" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "status": { "type": "string" }, "paid": { "type": "boolean" }, "comment": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "swaps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" }, "from_user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "to_user": { "type": [ "string", "null" ] }, "shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "to_shift": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "absences": [ { "id": 912, "uuid": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f", "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "type": "vacation", "date_from": "2026-12-01", "date_to": "2026-12-14", "days": 14, "status": "pending", "paid": true, "comment": "Family trip", "file": null, "decided_by": null, "decided_at": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } ], "swaps": [ { "id": 340, "uuid": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a", "type": "give", "status": "pending_peer", "note": "Doctor appointment", "from_user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "to_user": null, "shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "location": { "id": 4609, "name": "Abay Ave" } }, "to_shift": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/shifts": { "get": { "operationId": "scheduleShiftsList", "summary": "List shifts", "description": "Shifts at locations where the token has `schedule.view`, by date. Drafts and unpublished changes are included (`status`: `draft`, `published`, `changed`; `removed` — deleted but not yet published). Default period — the current week, max 62 days.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_shifts_list", "x-permissions": [ "schedule.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "date_from", "in": "query", "description": "From (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "To (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "user_ids[]", "in": "query", "description": "Only these employees", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published", "changed" ] } }, { "name": "open", "in": "query", "description": "`true` — only open (unassigned) shifts", "schema": { "type": "boolean" } }, { "name": "include_removed", "in": "query", "description": "Include removed shifts awaiting publication", "schema": { "type": "boolean" } }, { "name": "updated_since", "in": "query", "description": "Only shifts changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "template_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "overnight": { "type": "boolean" }, "break_minutes": { "type": "integer" }, "minutes": { "type": "integer" }, "status": { "type": "string" }, "published": { "type": "boolean" }, "removed": { "type": "boolean" }, "open": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 70211, "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "location": { "id": 4609, "name": "Abay Ave" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position_id": 12, "template_id": 3, "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "overnight": false, "break_minutes": 60, "minutes": 480, "status": "published", "published": true, "removed": false, "open": false, "note": null, "color": null, "updated_at": "2026-11-01T12:00:00+05:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "scheduleShiftsCreate", "summary": "Create a shift", "description": "Creates a draft shift (employees see it after `schedule.publish`). Rejected in a closed month.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_shifts_create", "x-permissions": [ "schedule.edit" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer", "description": "Location id (`schedule.edit` there)" }, "user_id": { "type": [ "integer", "null" ], "description": "Employee; `null` — open shift anyone eligible can claim" }, "position_id": { "type": [ "integer", "null" ], "description": "Job position; default — the employee's position" }, "template_id": { "type": [ "integer", "null" ], "description": "Shift template: fills start, end, break and position" }, "date": { "type": "string", "format": "date", "description": "Shift date (local)" }, "start": { "type": "string", "description": "Start time `HH:MM` (local). Required without a template" }, "end": { "type": "string", "description": "End time `HH:MM`; earlier than start — ends next day" }, "break_minutes": { "type": "integer", "minimum": 0, "maximum": 600 }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "color": { "type": [ "string", "null" ], "maxLength": 20 } }, "required": [ "location_id", "date" ] }, "example": { "location_id": 12, "user_id": 42, "position_id": 42, "template_id": 42, "date": "2026-11-01" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "template_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "overnight": { "type": "boolean" }, "break_minutes": { "type": "integer" }, "minutes": { "type": "integer" }, "status": { "type": "string" }, "published": { "type": "boolean" }, "removed": { "type": "boolean" }, "open": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 70211, "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "location": { "id": 4609, "name": "Abay Ave" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position_id": 12, "template_id": 3, "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "overnight": false, "break_minutes": 60, "minutes": 480, "status": "published", "published": true, "removed": false, "open": false, "note": null, "color": null, "updated_at": "2026-11-01T12:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/shifts/{id}": { "patch": { "operationId": "scheduleShiftsUpdate", "summary": "Update a shift", "description": "Partial update. A published shift becomes `changed` until published again.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_shifts_update", "x-permissions": [ "schedule.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Shift id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "integer", "description": "Location id (`schedule.edit` there)" }, "user_id": { "type": [ "integer", "null" ], "description": "Employee; `null` — open shift anyone eligible can claim" }, "position_id": { "type": [ "integer", "null" ], "description": "Job position; default — the employee's position" }, "template_id": { "type": [ "integer", "null" ], "description": "Shift template: fills start, end, break and position" }, "date": { "type": "string", "format": "date", "description": "Shift date (local)" }, "start": { "type": "string", "description": "Start time `HH:MM` (local). Required without a template" }, "end": { "type": "string", "description": "End time `HH:MM`; earlier than start — ends next day" }, "break_minutes": { "type": "integer", "minimum": 0, "maximum": 600 }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "color": { "type": [ "string", "null" ], "maxLength": 20 } } }, "example": { "location_id": 12, "user_id": 42, "position_id": 42, "template_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position_id": { "type": "integer" }, "template_id": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "overnight": { "type": "boolean" }, "break_minutes": { "type": "integer" }, "minutes": { "type": "integer" }, "status": { "type": "string" }, "published": { "type": "boolean" }, "removed": { "type": "boolean" }, "open": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 70211, "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "location": { "id": 4609, "name": "Abay Ave" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position_id": 12, "template_id": 3, "date": "2026-11-04", "start": "09:00", "end": "18:00", "starts_at": "2026-11-04T09:00:00+05:00", "ends_at": "2026-11-04T18:00:00+05:00", "overnight": false, "break_minutes": 60, "minutes": 480, "status": "published", "published": true, "removed": false, "open": false, "note": null, "color": null, "updated_at": "2026-11-01T12:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "scheduleShiftsDelete", "summary": "Delete a shift", "description": "Deletes a draft shift; a published one is marked removed until the schedule is published again.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_shifts_delete", "x-permissions": [ "schedule.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Shift id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/swaps": { "post": { "operationId": "scheduleSwapsCreate", "summary": "Request a shift swap", "description": "`give` — give away own shift (to `to_user_id` or anyone eligible); `swap` — exchange with a colleague's shift `to_shift_uuid`. The colleague answers, then the manager decides.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_swaps_create", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "give", "swap" ] }, "shift_uuid": { "type": "string", "format": "uuid", "description": "Own published shift" }, "to_shift_uuid": { "type": "string", "format": "uuid", "description": "Colleague's shift (for `swap`)" }, "to_user_id": { "type": "integer", "description": "Colleague (for `give`)" }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "type", "shift_uuid" ] }, "example": { "type": "give", "shift_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "to_shift_uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "to_user_id": 42 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" }, "from_user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "to_user": { "type": [ "string", "null" ] }, "shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "to_shift": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 340, "uuid": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a", "type": "give", "status": "pending_peer", "note": "Doctor appointment", "from_user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "to_user": null, "shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "location": { "id": 4609, "name": "Abay Ave" } }, "to_shift": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/swaps/{uuid}/answer": { "post": { "operationId": "scheduleSwapsAnswer", "summary": "Answer a swap request", "description": "The colleague accepts or declines a swap / give-away addressed to them.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_swaps_answer", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Swap request UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept": { "type": "boolean" } }, "required": [ "accept" ] }, "example": { "accept": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" }, "from_user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "to_user": { "type": [ "string", "null" ] }, "shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "to_shift": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 340, "uuid": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a", "type": "give", "status": "pending_peer", "note": "Doctor appointment", "from_user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "to_user": null, "shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "location": { "id": 4609, "name": "Abay Ave" } }, "to_shift": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/swaps/{uuid}/cancel": { "post": { "operationId": "scheduleSwapsCancel", "summary": "Cancel a swap request", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_swaps_cancel", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Swap request UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" }, "from_user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "to_user": { "type": [ "string", "null" ] }, "shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "to_shift": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 340, "uuid": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a", "type": "give", "status": "pending_peer", "note": "Doctor appointment", "from_user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "to_user": null, "shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "location": { "id": 4609, "name": "Abay Ave" } }, "to_shift": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/swaps/{uuid}/decide": { "post": { "operationId": "scheduleSwapsDecide", "summary": "Approve or reject a swap request", "description": "Manager decision (`schedule.requests` at the shift location). Approval reassigns the shifts and notifies both employees.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_swaps_decide", "x-permissions": [ "schedule.requests" ], "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Swap request UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean" }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "approve" ] }, "example": { "approve": true, "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" }, "from_user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "to_user": { "type": [ "string", "null" ] }, "shift": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "to_shift": { "type": [ "string", "null" ] }, "decision_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 340, "uuid": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a", "type": "give", "status": "pending_peer", "note": "Doctor appointment", "from_user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "to_user": null, "shift": { "uuid": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "date": "2026-11-04", "start": "09:00", "end": "18:00", "location": { "id": 4609, "name": "Abay Ave" } }, "to_shift": null, "decision_note": null, "created_at": "2026-11-03T10:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/templates": { "get": { "operationId": "scheduleTemplatesList", "summary": "List shift templates", "description": "Company-wide shift templates and templates of the location.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_templates_list", "x-permissions": [ "schedule.view" ], "x-scope": "read", "parameters": [ { "name": "location_id", "in": "query", "description": "Include templates of this location", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "location_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "code": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "break_minutes": { "type": "integer" }, "position_id": { "type": [ "string", "null" ] }, "color": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 3, "location_id": null, "name": "Morning", "code": "M", "start": "08:00", "end": "16:00", "break_minutes": 30, "position_id": null, "color": "#fab005" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/schedule/timesheet": { "get": { "operationId": "scheduleTimesheet", "summary": "Get the timesheet", "description": "Planned and payable hours by employee and day (minutes), night/holiday/overtime, lateness, absences and day codes. A month, or `date_from`/`date_to` up to 62 days. `closed` — the month is locked.", "tags": [ "Schedule & attendance" ], "x-mcp-tool": "schedule_timesheet", "x-permissions": [ "schedule.timesheet" ], "x-scope": "read", "parameters": [ { "name": "month", "in": "query", "description": "Month `YYYY-MM`, default — current", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "location_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" }, "closed": { "type": "boolean" }, "holidays": { "type": "array" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "string" }, "personnel_no": { "type": "string" }, "location_ids": { "type": "array", "items": { "type": "integer" } } } }, "totals": { "type": "object", "properties": { "planned": { "type": "integer" }, "worked": { "type": "integer" }, "payable": { "type": "integer" }, "night": { "type": "integer" }, "holiday": { "type": "integer" }, "overtime": { "type": "integer" }, "late_count": { "type": "integer" }, "late": { "type": "integer" }, "days": { "type": "integer" }, "shifts": { "type": "integer" }, "no_show": { "type": "integer" }, "absences": { "type": "array" }, "paid_absence_days": { "type": "integer" } } }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "code": { "type": "string" }, "planned": { "type": "integer" }, "payable": { "type": "integer" }, "night": { "type": "integer" }, "holiday": { "type": "integer" }, "overtime": { "type": "integer" }, "late": { "type": "integer" }, "absence": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string" } }, "open": { "type": "boolean" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "date_from": "2026-11-01", "date_to": "2026-11-30", "closed": false, "holidays": [], "rows": [ { "user": { "id": 311, "name": "Aigerim Sadykova", "position": "Barista", "personnel_no": "A-17", "location_ids": [ 4609 ] }, "totals": { "planned": 10080, "worked": 3200, "payable": 3150, "night": 0, "holiday": 0, "overtime": 0, "late_count": 1, "late": 4, "days": 7, "shifts": 7, "no_show": 0, "absences": [], "paid_absence_days": 0 }, "days": [ { "date": "2026-11-03", "code": "Я", "planned": 480, "payable": 450, "night": 0, "holiday": 0, "overtime": 0, "late": 4, "absence": null, "flags": [ "late" ], "open": false } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks": { "get": { "operationId": "tasksList", "summary": "List tasks", "description": "Tasks visible to the token, newest first. Closed tasks are included; filter with `status`. Deleted tasks are never returned.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_list", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "status[]", "in": "query", "description": "Filter by status: new, in_progress, review, approval, done, rejected", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "priority[]", "in": "query", "description": "Filter by priority: urgent, high, medium, low", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "location_ids[]", "in": "query", "description": "Only these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "assignee_id", "in": "query", "description": "Only tasks where this user is an executor", "schema": { "type": "integer" } }, { "name": "author_id", "in": "query", "description": "Only tasks created by this user", "schema": { "type": "integer" } }, { "name": "team_id", "in": "query", "description": "Only tasks of this team", "schema": { "type": "integer" } }, { "name": "project_id", "in": "query", "description": "Only tasks of this project", "schema": { "type": "integer" } }, { "name": "source", "in": "query", "description": "How the task was created", "schema": { "type": "string", "enum": [ "manual", "auto", "haccp", "request", "hr", "process", "routine" ] } }, { "name": "due_from", "in": "query", "description": "Due date from (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "due_to", "in": "query", "description": "Due date to (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "overdue", "in": "query", "description": "Only open tasks past their due date", "schema": { "type": "boolean" } }, { "name": "updated_since", "in": "query", "description": "Only tasks changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } }, { "name": "search", "in": "query", "description": "Search in title and description", "schema": { "type": "string", "maxLength": 200 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created_desc", "created_asc", "updated_desc", "due_asc" ], "default": "created_desc" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "watchers": { "type": "array" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "due_date": { "type": "string", "format": "date" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "needs_photo": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "comments_count": { "type": "integer" }, "files_count": { "type": "integer" }, "subtasks": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "audit_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPS-42", "title": "Replace the broken fridge seal", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "watchers": [], "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "location": { "id": 12, "name": "Abay Ave" }, "team_id": null, "project_id": null, "due_date": "2026-11-10", "tags": [ "Equipment" ], "source": "auto", "needs_photo": true, "needs_review": true, "comments_count": 2, "files_count": 1, "subtasks": { "done": 1, "total": 3 }, "audit_id": 99812, "created_at": "2026-11-03T10:24:00+05:00", "updated_at": "2026-11-03T12:01:00+05:00", "completed_at": null, "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "tasksCreate", "summary": "Create a task", "description": "Creates a task with the same rules as the web app: notifications go to assignees, a task with a team and no assignee lands in the team queue (auto-assignment if enabled).", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_create", "x-scope": "write", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Task title", "minLength": 2, "maxLength": 512 }, "description": { "type": [ "string", "null" ], "description": "Plain-text description", "maxLength": 20000 }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low" ], "description": "Priority, default `medium`" }, "assignee_ids": { "type": "array", "items": { "type": "integer" }, "description": "Executors (user ids)", "maxItems": 20 }, "watcher_ids": { "type": "array", "items": { "type": "integer" }, "description": "Watchers (user ids)", "maxItems": 50 }, "location_id": { "type": [ "integer", "null" ], "description": "Location id. Must be one of the locations where the token may create tasks" }, "team_id": { "type": [ "integer", "null" ], "description": "Team (department) id — the task goes to the team queue if no assignee" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date, YYYY-MM-DD" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags, up to 10", "maxItems": 10 }, "project_id": { "type": [ "integer", "null" ], "description": "Project id (requires editor role in the project)" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date (projects, Gantt)" }, "estimate_minutes": { "type": [ "integer", "null" ], "description": "Estimate, minutes", "minimum": 0, "maximum": 100000 }, "status": { "type": "string", "enum": [ "new", "in_progress", "review", "done", "rejected" ], "description": "Initial status, default `new`" }, "subtasks": { "type": "array", "items": { "type": "string" }, "description": "Checklist items to create with the task", "maxItems": 50 }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Attachments (multipart `files[]`; in MCP — objects with `name` and `content_base64`)", "maxItems": 10 } }, "required": [ "title" ] } }, "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Task title", "minLength": 2, "maxLength": 512 }, "description": { "type": [ "string", "null" ], "description": "Plain-text description", "maxLength": 20000 }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low" ], "description": "Priority, default `medium`" }, "assignee_ids": { "type": "array", "items": { "type": "integer" }, "description": "Executors (user ids)", "maxItems": 20 }, "watcher_ids": { "type": "array", "items": { "type": "integer" }, "description": "Watchers (user ids)", "maxItems": 50 }, "location_id": { "type": [ "integer", "null" ], "description": "Location id. Must be one of the locations where the token may create tasks" }, "team_id": { "type": [ "integer", "null" ], "description": "Team (department) id — the task goes to the team queue if no assignee" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date, YYYY-MM-DD" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags, up to 10", "maxItems": 10 }, "project_id": { "type": [ "integer", "null" ], "description": "Project id (requires editor role in the project)" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date (projects, Gantt)" }, "estimate_minutes": { "type": [ "integer", "null" ], "description": "Estimate, minutes", "minimum": 0, "maximum": 100000 }, "status": { "type": "string", "enum": [ "new", "in_progress", "review", "done", "rejected" ], "description": "Initial status, default `new`" }, "subtasks": { "type": "array", "items": { "type": "string" }, "description": "Checklist items to create with the task", "maxItems": 50 }, "files": { "type": "array", "items": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } } }, "description": "Attachments (multipart `files[]`; in MCP — objects with `name` and `content_base64`)", "maxItems": 10 } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "watchers": { "type": "array" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "due_date": { "type": "string", "format": "date" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "needs_photo": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "comments_count": { "type": "integer" }, "files_count": { "type": "integer" }, "subtasks": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "audit_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "estimate_minutes": { "type": [ "string", "null" ] }, "allowed_statuses": { "type": "array", "items": { "type": "string" } }, "can_delete": { "type": "boolean" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "date": { "type": "string", "format": "date-time" } } }, "subtask_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPS-42", "title": "Replace the broken fridge seal", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "watchers": [], "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "location": { "id": 12, "name": "Abay Ave" }, "team_id": null, "project_id": null, "due_date": "2026-11-10", "tags": [ "Equipment" ], "source": "auto", "needs_photo": true, "needs_review": true, "comments_count": 2, "files_count": 1, "subtasks": { "done": 1, "total": 3 }, "audit_id": 99812, "created_at": "2026-11-03T10:24:00+05:00", "updated_at": "2026-11-03T12:01:00+05:00", "completed_at": null, "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "start_date": null, "estimate_minutes": null, "allowed_statuses": [ "in_progress", "review" ], "can_delete": false, "audit": { "id": 99812, "checklist": "Kitchen daily check", "score": 82, "date": "2026-11-03T09:40:00+05:00" }, "subtask_items": [ { "id": 501, "title": "Order the seal", "done": true } ], "files": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ], "comments": [ { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/bulk": { "post": { "operationId": "tasksBulk", "summary": "Bulk update tasks", "description": "Applies the same change to up to 200 tasks. Tasks that cannot be changed (rules of the loop, permissions) are skipped; the response says how many were updated.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_bulk", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Task UUIDs", "minItems": 1, "maxItems": 200 }, "status": { "type": "string", "enum": [ "new", "in_progress", "review", "done", "rejected" ] }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "assignee_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 20 }, "location_id": { "type": [ "integer", "null" ] }, "team_id": { "type": [ "integer", "null" ] }, "delete": { "type": "boolean", "description": "Delete the tasks instead of updating" } }, "required": [ "uuids" ] }, "example": { "uuids": [ "example" ], "status": "new", "priority": "urgent", "due_date": "2026-11-01" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "updated": { "type": "integer" }, "requested": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "updated": 18, "requested": 20 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/comments/{id}": { "patch": { "operationId": "tasksCommentsUpdate", "summary": "Edit a comment", "description": "Only the author of the comment can edit it.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_comments_update", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Comment id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "text" ] }, "example": { "text": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "tasksCommentsDelete", "summary": "Delete a comment", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_comments_delete", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Comment id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/files/{id}": { "delete": { "operationId": "tasksFilesDelete", "summary": "Delete a task file", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_files_delete", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "File id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/subtasks/{id}": { "patch": { "operationId": "tasksSubtasksUpdate", "summary": "Update a subtask", "description": "Rename a subtask or mark it done / not done.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_subtasks_update", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subtask id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "done": { "type": "boolean" } } }, "example": { "title": "Replace the broken fridge seal", "done": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 502, "title": "Install the seal", "done": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "tasksSubtasksDelete", "summary": "Delete a subtask", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_subtasks_delete", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subtask id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/tags": { "get": { "operationId": "tasksTags", "summary": "List task tags", "description": "Tag suggestions and tags already used in the company.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_tags", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] }, "example": { "data": [ "Equipment", "Kitchen", "Cleaning" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}": { "get": { "operationId": "tasksGet", "summary": "Retrieve a task", "description": "Full task card: description, subtasks, files (signed links valid for 1 hour), comments and the statuses the token may set now.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "watchers": { "type": "array" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "due_date": { "type": "string", "format": "date" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "needs_photo": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "comments_count": { "type": "integer" }, "files_count": { "type": "integer" }, "subtasks": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "audit_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "estimate_minutes": { "type": [ "string", "null" ] }, "allowed_statuses": { "type": "array", "items": { "type": "string" } }, "can_delete": { "type": "boolean" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "date": { "type": "string", "format": "date-time" } } }, "subtask_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPS-42", "title": "Replace the broken fridge seal", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "watchers": [], "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "location": { "id": 12, "name": "Abay Ave" }, "team_id": null, "project_id": null, "due_date": "2026-11-10", "tags": [ "Equipment" ], "source": "auto", "needs_photo": true, "needs_review": true, "comments_count": 2, "files_count": 1, "subtasks": { "done": 1, "total": 3 }, "audit_id": 99812, "created_at": "2026-11-03T10:24:00+05:00", "updated_at": "2026-11-03T12:01:00+05:00", "completed_at": null, "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "start_date": null, "estimate_minutes": null, "allowed_statuses": [ "in_progress", "review" ], "can_delete": false, "audit": { "id": 99812, "checklist": "Kitchen daily check", "score": 82, "date": "2026-11-03T09:40:00+05:00" }, "subtask_items": [ { "id": 501, "title": "Order the seal", "done": true } ], "files": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ], "comments": [ { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "tasksUpdate", "summary": "Update a task", "description": "Partial update: send only the fields to change. Arrays (`assignee_ids`, `watcher_ids`, `tags`) replace the current values.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_update", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Task title", "minLength": 2, "maxLength": 512 }, "description": { "type": [ "string", "null" ], "description": "Plain-text description", "maxLength": 20000 }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low" ], "description": "Priority" }, "assignee_ids": { "type": "array", "items": { "type": "integer" }, "description": "Executors (user ids)", "maxItems": 20 }, "watcher_ids": { "type": "array", "items": { "type": "integer" }, "description": "Watchers (user ids)", "maxItems": 50 }, "location_id": { "type": [ "integer", "null" ], "description": "Location id. Must be one of the locations where the token may create tasks" }, "team_id": { "type": [ "integer", "null" ], "description": "Team (department) id — the task goes to the team queue if no assignee" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Due date, YYYY-MM-DD" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags, up to 10", "maxItems": 10 }, "project_id": { "type": [ "integer", "null" ], "description": "Project id (requires editor role in the project)" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date (projects, Gantt)" }, "estimate_minutes": { "type": [ "integer", "null" ], "description": "Estimate, minutes", "minimum": 0, "maximum": 100000 } } }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "priority": "urgent", "assignee_ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "watchers": { "type": "array" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "due_date": { "type": "string", "format": "date" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "needs_photo": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "comments_count": { "type": "integer" }, "files_count": { "type": "integer" }, "subtasks": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "audit_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "estimate_minutes": { "type": [ "string", "null" ] }, "allowed_statuses": { "type": "array", "items": { "type": "string" } }, "can_delete": { "type": "boolean" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "date": { "type": "string", "format": "date-time" } } }, "subtask_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPS-42", "title": "Replace the broken fridge seal", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "watchers": [], "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "location": { "id": 12, "name": "Abay Ave" }, "team_id": null, "project_id": null, "due_date": "2026-11-10", "tags": [ "Equipment" ], "source": "auto", "needs_photo": true, "needs_review": true, "comments_count": 2, "files_count": 1, "subtasks": { "done": 1, "total": 3 }, "audit_id": 99812, "created_at": "2026-11-03T10:24:00+05:00", "updated_at": "2026-11-03T12:01:00+05:00", "completed_at": null, "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "start_date": null, "estimate_minutes": null, "allowed_statuses": [ "in_progress", "review" ], "can_delete": false, "audit": { "id": 99812, "checklist": "Kitchen daily check", "score": 82, "date": "2026-11-03T09:40:00+05:00" }, "subtask_items": [ { "id": 501, "title": "Order the seal", "done": true } ], "files": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ], "comments": [ { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "tasksDelete", "summary": "Delete a task", "description": "Soft-deletes the task. Allowed to the author or with the `tasks.delete` permission.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_delete", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}/comments": { "get": { "operationId": "tasksCommentsList", "summary": "List task comments", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_comments_list", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "tasksCommentsCreate", "summary": "Add a comment", "description": "Adds a comment from the acting user. Participants are notified as in the web app.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_comments_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "text" ] }, "example": { "text": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}/duplicate": { "post": { "operationId": "tasksDuplicate", "summary": "Duplicate a task", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_duplicate", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "watchers": { "type": "array" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "due_date": { "type": "string", "format": "date" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "needs_photo": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "comments_count": { "type": "integer" }, "files_count": { "type": "integer" }, "subtasks": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "audit_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "estimate_minutes": { "type": [ "string", "null" ] }, "allowed_statuses": { "type": "array", "items": { "type": "string" } }, "can_delete": { "type": "boolean" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "date": { "type": "string", "format": "date-time" } } }, "subtask_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPS-42", "title": "Replace the broken fridge seal", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "watchers": [], "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "location": { "id": 12, "name": "Abay Ave" }, "team_id": null, "project_id": null, "due_date": "2026-11-10", "tags": [ "Equipment" ], "source": "auto", "needs_photo": true, "needs_review": true, "comments_count": 2, "files_count": 1, "subtasks": { "done": 1, "total": 3 }, "audit_id": 99812, "created_at": "2026-11-03T10:24:00+05:00", "updated_at": "2026-11-03T12:01:00+05:00", "completed_at": null, "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "start_date": null, "estimate_minutes": null, "allowed_statuses": [ "in_progress", "review" ], "can_delete": false, "audit": { "id": 99812, "checklist": "Kitchen daily check", "score": 82, "date": "2026-11-03T09:40:00+05:00" }, "subtask_items": [ { "id": 501, "title": "Order the seal", "done": true } ], "files": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ], "comments": [ { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}/files": { "get": { "operationId": "tasksFilesList", "summary": "List task files", "description": "Attachments with signed download links (valid for 1 hour, no token needed).", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_files_list", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "tasksFilesUpload", "summary": "Upload files to a task", "description": "Multipart upload, field `files[]`, up to 10 files. In MCP pass `files` as objects with `name` and `content_base64`.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_files_upload", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 10 } }, "required": [ "files" ] } }, "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } } }, "minItems": 1, "maxItems": 10 } }, "required": [ "files" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}/history": { "get": { "operationId": "tasksHistory", "summary": "Get task history", "description": "Audit trail of the task: creation, status changes, reassignment, due date changes, comments by automation.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_history", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "payload": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "actor": { "type": "string" }, "user": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "type": "status", "payload": { "from": "new", "to": "in_progress" }, "actor": "user", "user": "Aigerim Sadykova", "created_at": "2026-11-03T11:00:00+05:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}/status": { "post": { "operationId": "tasksStatus", "summary": "Change task status", "description": "Moves the task to another status. Tasks of the corrective-action loop allow only `allowed_statuses` from the task card (e.g. a photo \"after\" is required before `review`). `approval` is set by process routes only.", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_status", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "new", "in_progress", "review", "done", "rejected" ] } }, "required": [ "status" ] }, "example": { "status": "new" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "watchers": { "type": "array" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "due_date": { "type": "string", "format": "date" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "needs_photo": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "comments_count": { "type": "integer" }, "files_count": { "type": "integer" }, "subtasks": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "audit_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "estimate_minutes": { "type": [ "string", "null" ] }, "allowed_statuses": { "type": "array", "items": { "type": "string" } }, "can_delete": { "type": "boolean" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "date": { "type": "string", "format": "date-time" } } }, "subtask_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPS-42", "title": "Replace the broken fridge seal", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "watchers": [], "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "location": { "id": 12, "name": "Abay Ave" }, "team_id": null, "project_id": null, "due_date": "2026-11-10", "tags": [ "Equipment" ], "source": "auto", "needs_photo": true, "needs_review": true, "comments_count": 2, "files_count": 1, "subtasks": { "done": 1, "total": 3 }, "audit_id": 99812, "created_at": "2026-11-03T10:24:00+05:00", "updated_at": "2026-11-03T12:01:00+05:00", "completed_at": null, "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "start_date": null, "estimate_minutes": null, "allowed_statuses": [ "in_progress", "review" ], "can_delete": false, "audit": { "id": 99812, "checklist": "Kitchen daily check", "score": 82, "date": "2026-11-03T09:40:00+05:00" }, "subtask_items": [ { "id": 501, "title": "Order the seal", "done": true } ], "files": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ], "comments": [ { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}/subtasks": { "post": { "operationId": "tasksSubtasksCreate", "summary": "Add a subtask", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_subtasks_create", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "title" ] }, "example": { "title": "Replace the broken fridge seal" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 502, "title": "Install the seal", "done": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks/{uuid}/take": { "post": { "operationId": "tasksTake", "summary": "Take a task from the team queue", "description": "Assigns a queued team task to the acting user (must be a member of the team).", "tags": [ "Tasks" ], "x-mcp-tool": "tasks_take", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "watchers": { "type": "array" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "due_date": { "type": "string", "format": "date" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "needs_photo": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "comments_count": { "type": "integer" }, "files_count": { "type": "integer" }, "subtasks": { "type": "object", "properties": { "done": { "type": "integer" }, "total": { "type": "integer" } } }, "audit_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "start_date": { "type": [ "string", "null" ] }, "estimate_minutes": { "type": [ "string", "null" ] }, "allowed_statuses": { "type": "array", "items": { "type": "string" } }, "can_delete": { "type": "boolean" }, "audit": { "type": "object", "properties": { "id": { "type": "integer" }, "checklist": { "type": "string" }, "score": { "type": "integer" }, "date": { "type": "string", "format": "date-time" } } }, "subtask_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "done": { "type": "boolean" } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "integer" }, "is_image": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "text": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "key": "OPS-42", "title": "Replace the broken fridge seal", "status": "in_progress", "priority": "high", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "watchers": [], "author": { "id": 120, "uuid": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "name": "Daniyar Omarov" }, "location": { "id": 12, "name": "Abay Ave" }, "team_id": null, "project_id": null, "due_date": "2026-11-10", "tags": [ "Equipment" ], "source": "auto", "needs_photo": true, "needs_review": true, "comments_count": 2, "files_count": 1, "subtasks": { "done": 1, "total": 3 }, "audit_id": 99812, "created_at": "2026-11-03T10:24:00+05:00", "updated_at": "2026-11-03T12:01:00+05:00", "completed_at": null, "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "start_date": null, "estimate_minutes": null, "allowed_statuses": [ "in_progress", "review" ], "can_delete": false, "audit": { "id": 99812, "checklist": "Kitchen daily check", "score": 82, "date": "2026-11-03T09:40:00+05:00" }, "subtask_items": [ { "id": 501, "title": "Order the seal", "done": true } ], "files": [ { "id": 77, "name": "fridge.jpg", "size": 184220, "is_image": true, "url": "https://app.jecheck.io/ui/tasks/files/77?signature=…", "created_at": "2026-11-03T10:30:00+05:00" } ], "comments": [ { "id": 9001, "author": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "text": "Seal ordered, arrives tomorrow.", "file": null, "created_at": "2026-11-03T11:00:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams": { "get": { "operationId": "teamsList", "summary": "List teams", "description": "With `org.view` — all teams of the company; otherwise the teams the acting user belongs to or heads.", "tags": [ "Teams" ], "x-mcp-tool": "teams_list", "x-scope": "read", "parameters": [ { "name": "kind", "in": "query", "description": "Only teams of this direction", "schema": { "type": "string", "maxLength": 80 } }, { "name": "location_id", "in": "query", "description": "Only teams serving this location", "schema": { "type": "integer" } }, { "name": "mine", "in": "query", "description": "Only teams the acting user belongs to", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "all_locations": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "routing": { "type": "string" }, "only_on_shift": { "type": "boolean" }, "notify": { "type": "string" }, "take_minutes": { "type": "integer" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_head": { "type": "boolean" } } } }, "members_count": { "type": "integer" }, "is_member": { "type": "boolean" }, "is_head": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 9, "uuid": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "name": "Maintenance", "kind": "Repairs", "color": "#5249e6", "icon": "build", "description": "Equipment repairs in all coffee shops", "all_locations": false, "locations": [ { "id": 12, "name": "Abay Ave" } ], "routing": "load", "only_on_shift": true, "notify": "heads", "take_minutes": 30, "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "is_head": true } ], "members_count": 1, "is_member": true, "is_head": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "teamsCreate", "summary": "Create a team", "tags": [ "Teams" ], "x-mcp-tool": "teams_create", "x-permissions": [ "org.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Team name", "minLength": 2, "maxLength": 120 }, "kind": { "type": [ "string", "null" ], "description": "Direction (e.g. \"Repairs\", \"IT\") — used by automation scenarios and QR points to find the team", "maxLength": 80 }, "color": { "type": "string", "description": "Hex color", "maxLength": 9 }, "icon": { "type": "string", "description": "Material Symbols icon name", "maxLength": 40 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "all_locations": { "type": "boolean", "description": "Serves all locations (default `true`)" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Served locations when `all_locations` is false" }, "routing": { "type": "string", "enum": [ "manual", "load", "round" ], "description": "Queue distribution: manual, by load, round robin (auto-distribution requires the paid feature `teams_pro`)" }, "only_on_shift": { "type": "boolean", "description": "Auto-assign only to members on shift" }, "notify": { "type": "string", "enum": [ "heads", "members" ], "description": "Who is notified about new queued tasks" }, "take_minutes": { "type": [ "integer", "null" ], "description": "Escalate to heads if nobody takes a task within N minutes", "minimum": 5, "maximum": 10080 }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer" }, "is_head": { "type": "boolean" } }, "required": [ "user_id" ] }, "description": "Full member list (replaces current members)", "maxItems": 500 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal", "kind": "string", "color": "string", "icon": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "all_locations": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "routing": { "type": "string" }, "only_on_shift": { "type": "boolean" }, "notify": { "type": "string" }, "take_minutes": { "type": "integer" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_head": { "type": "boolean" } } } }, "members_count": { "type": "integer" }, "is_member": { "type": "boolean" }, "is_head": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 9, "uuid": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "name": "Maintenance", "kind": "Repairs", "color": "#5249e6", "icon": "build", "description": "Equipment repairs in all coffee shops", "all_locations": false, "locations": [ { "id": 12, "name": "Abay Ave" } ], "routing": "load", "only_on_shift": true, "notify": "heads", "take_minutes": 30, "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "is_head": true } ], "members_count": 1, "is_member": true, "is_head": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/kinds": { "get": { "operationId": "teamsKinds", "summary": "List team directions", "description": "Distinct directions (`kind`) of the company teams — targets for automation scenarios and QR request points.", "tags": [ "Teams" ], "x-mcp-tool": "teams_kinds", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] }, "example": { "data": [ "Cleaning", "IT", "Repairs" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/order": { "put": { "operationId": "teamsReorder", "summary": "Reorder teams", "tags": [ "Teams" ], "x-mcp-tool": "teams_reorder", "x-permissions": [ "org.manage" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "Team ids in the new order", "minItems": 1 } }, "required": [ "ids" ] }, "example": { "ids": [ 12, 14 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "ok": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/queue": { "get": { "operationId": "teamsQueue", "summary": "List the team task queue", "description": "Open tasks waiting in the queue of the acting user's teams (nobody has taken them yet), oldest first. With `org.view` any team may be requested via `team_id`. Take one with `tasks.take`, or assign with `teams.queue.assign` (team heads).", "tags": [ "Teams" ], "x-mcp-tool": "teams_queue", "x-scope": "read", "parameters": [ { "name": "team_id", "in": "query", "description": "Only this team", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "team_id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "priority": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "queued_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Coffee machine leaks", "team_id": 9, "location": { "id": 12, "name": "Abay Ave" }, "priority": "high", "due_date": "2026-11-04", "queued_at": "2026-11-03T09:10:00+05:00", "source": "request", "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/queue/{uuid}/assign": { "post": { "operationId": "teamsQueueAssign", "summary": "Assign a queued task to a member", "description": "A team head (or administrator) assigns the task to a team member; the member is notified.", "tags": [ "Teams" ], "x-mcp-tool": "teams_queue_assign", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "Team member" } }, "required": [ "user_id" ] }, "example": { "user_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "team_id": { "type": "integer" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "priority": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "queued_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "taken_at": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Coffee machine leaks", "team_id": 9, "location": { "id": 12, "name": "Abay Ave" }, "priority": "high", "due_date": "2026-11-04", "queued_at": "2026-11-03T09:10:00+05:00", "source": "request", "url": "https://app.jecheck.io/ui/tasks?task=3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "assignees": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" } ], "taken_at": "2026-11-03T09:20:00+05:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/queue/{uuid}/candidates": { "get": { "operationId": "teamsQueueCandidates", "summary": "List candidates for a queued task", "description": "Members of the task's team with open tasks, shift status (`here` — on shift at the task location, `elsewhere`) and absence. For team heads and administrators.", "tags": [ "Teams" ], "x-mcp-tool": "teams_queue_candidates", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Task UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_head": { "type": "boolean" }, "open_tasks": { "type": "integer" }, "shift": { "type": "string" }, "absent": { "type": "boolean" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "is_head": false, "open_tasks": 3, "shift": "here", "absent": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/request-points": { "get": { "operationId": "teamsRequestPointsList", "summary": "List QR request points", "description": "QR codes placed at locations or equipment: guests and staff scan and leave a request that goes to the team queue. `url` is the public request page.", "tags": [ "Teams" ], "x-mcp-tool": "teams_request_points_list", "x-permissions": [ "org.manage" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": "integer" }, "kind": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "requests_count": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 21, "title": "Reception", "location": { "id": 12, "name": "Abay Ave" }, "team_id": 9, "kind": null, "active": true, "requests_count": 17, "url": "https://app.jecheck.io/r/aB3dE5fG7hJ9kL1mN3pQ5rS7" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "teamsRequestPointsCreate", "summary": "Create a QR request point", "description": "Requests go to `team_id` or, if not set, to the team of direction `kind` serving the location.", "tags": [ "Teams" ], "x-mcp-tool": "teams_request_points_create", "x-permissions": [ "org.manage" ], "x-plan-feature": "teams_pro", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Where the code hangs, e.g. \"Reception\"", "maxLength": 120 }, "location_id": { "type": "integer" }, "team_id": { "type": [ "integer", "null" ] }, "kind": { "type": [ "string", "null" ], "description": "Direction (when no team)", "maxLength": 80 }, "active": { "type": "boolean", "default": true } }, "required": [ "title", "location_id" ] }, "example": { "title": "Replace the broken fridge seal", "location_id": 12, "team_id": 42, "kind": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": "integer" }, "kind": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "requests_count": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 21, "title": "Reception", "location": { "id": 12, "name": "Abay Ave" }, "team_id": 9, "kind": null, "active": true, "requests_count": 17, "url": "https://app.jecheck.io/r/aB3dE5fG7hJ9kL1mN3pQ5rS7" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/request-points/{id}": { "patch": { "operationId": "teamsRequestPointsUpdate", "summary": "Update a QR request point", "tags": [ "Teams" ], "x-mcp-tool": "teams_request_points_update", "x-permissions": [ "org.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Request point id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 120 }, "location_id": { "type": "integer" }, "team_id": { "type": [ "integer", "null" ] }, "kind": { "type": [ "string", "null" ], "maxLength": 80 }, "active": { "type": "boolean" } } }, "example": { "title": "Replace the broken fridge seal", "location_id": 12, "team_id": 42, "kind": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": "integer" }, "kind": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "requests_count": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 21, "title": "Reception", "location": { "id": 12, "name": "Abay Ave" }, "team_id": 9, "kind": null, "active": true, "requests_count": 17, "url": "https://app.jecheck.io/r/aB3dE5fG7hJ9kL1mN3pQ5rS7" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "teamsRequestPointsDelete", "summary": "Delete a QR request point", "tags": [ "Teams" ], "x-mcp-tool": "teams_request_points_delete", "x-permissions": [ "org.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Request point id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/{id}": { "get": { "operationId": "teamsGet", "summary": "Retrieve a team", "description": "Team settings, members with workload, 30-day figures (with `org.view` or the paid feature `teams_pro`) and recent tasks. Available to team heads and with `org.view`.", "tags": [ "Teams" ], "x-mcp-tool": "teams_get", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "all_locations": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "routing": { "type": "string" }, "only_on_shift": { "type": "boolean" }, "notify": { "type": "string" }, "take_minutes": { "type": "integer" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_head": { "type": "boolean" } } } }, "members_count": { "type": "integer" }, "is_member": { "type": "boolean" }, "is_head": { "type": "boolean" }, "stats": { "type": "object", "properties": { "open": { "type": "integer" }, "queued": { "type": "integer" }, "overdue": { "type": "integer" }, "done_30d": { "type": "integer" }, "avg_take_minutes": { "type": "integer" }, "avg_close_minutes": { "type": "integer" }, "on_time_percent": { "type": "integer" } } }, "workload": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "open_tasks": { "type": "integer" }, "done_30d": { "type": "integer" } } } }, "recent_tasks": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "assignees": { "type": "array" }, "queued": { "type": "boolean" }, "location": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 9, "uuid": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "name": "Maintenance", "kind": "Repairs", "color": "#5249e6", "icon": "build", "description": "Equipment repairs in all coffee shops", "all_locations": false, "locations": [ { "id": 12, "name": "Abay Ave" } ], "routing": "load", "only_on_shift": true, "notify": "heads", "take_minutes": 30, "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "is_head": true } ], "members_count": 1, "is_member": true, "is_head": true, "stats": { "open": 7, "queued": 2, "overdue": 1, "done_30d": 41, "avg_take_minutes": 18, "avg_close_minutes": 640, "on_time_percent": 92 }, "workload": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "open_tasks": 3, "done_30d": 14 } ], "recent_tasks": [ { "uuid": "3f2b8c1e-7a4d-4e2f-9b1a-6c5d4e3f2a1b", "title": "Coffee machine leaks", "status": "new", "assignees": [], "queued": true, "location": "Abay Ave", "due_date": "2026-11-04", "source": "request", "created_at": "2026-11-03T09:10:00+05:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "teamsUpdate", "summary": "Update a team", "description": "Partial update. `members` replaces the whole member list; use the member operations for incremental changes.", "tags": [ "Teams" ], "x-mcp-tool": "teams_update", "x-permissions": [ "org.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Team name", "minLength": 2, "maxLength": 120 }, "kind": { "type": [ "string", "null" ], "description": "Direction (e.g. \"Repairs\", \"IT\") — used by automation scenarios and QR points to find the team", "maxLength": 80 }, "color": { "type": "string", "description": "Hex color", "maxLength": 9 }, "icon": { "type": "string", "description": "Material Symbols icon name", "maxLength": 40 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "all_locations": { "type": "boolean", "description": "Serves all locations (default `true`)" }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Served locations when `all_locations` is false" }, "routing": { "type": "string", "enum": [ "manual", "load", "round" ], "description": "Queue distribution: manual, by load, round robin (auto-distribution requires the paid feature `teams_pro`)" }, "only_on_shift": { "type": "boolean", "description": "Auto-assign only to members on shift" }, "notify": { "type": "string", "enum": [ "heads", "members" ], "description": "Who is notified about new queued tasks" }, "take_minutes": { "type": [ "integer", "null" ], "description": "Escalate to heads if nobody takes a task within N minutes", "minimum": 5, "maximum": 10080 }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer" }, "is_head": { "type": "boolean" } }, "required": [ "user_id" ] }, "description": "Full member list (replaces current members)", "maxItems": 500 } } }, "example": { "name": "Replace the broken fridge seal", "kind": "string", "color": "string", "icon": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "all_locations": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "routing": { "type": "string" }, "only_on_shift": { "type": "boolean" }, "notify": { "type": "string" }, "take_minutes": { "type": "integer" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_head": { "type": "boolean" } } } }, "members_count": { "type": "integer" }, "is_member": { "type": "boolean" }, "is_head": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 9, "uuid": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "name": "Maintenance", "kind": "Repairs", "color": "#5249e6", "icon": "build", "description": "Equipment repairs in all coffee shops", "all_locations": false, "locations": [ { "id": 12, "name": "Abay Ave" } ], "routing": "load", "only_on_shift": true, "notify": "heads", "take_minutes": 30, "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "is_head": true } ], "members_count": 1, "is_member": true, "is_head": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "teamsDelete", "summary": "Delete a team", "description": "Not allowed while the team queue has unassigned tasks. Its QR points are deactivated.", "tags": [ "Teams" ], "x-mcp-tool": "teams_delete", "x-permissions": [ "org.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/{id}/members": { "post": { "operationId": "teamsMembersAdd", "summary": "Add team members", "description": "Adds employees to the team; with `from_team_id` moves them from another team (a head is moved as a regular member).", "tags": [ "Teams" ], "x-mcp-tool": "teams_members_add", "x-permissions": [ "org.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 500 }, "from_team_id": { "type": "integer", "description": "Move from this team" } }, "required": [ "user_ids" ] }, "example": { "user_ids": [ 12, 14 ], "from_team_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "all_locations": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "routing": { "type": "string" }, "only_on_shift": { "type": "boolean" }, "notify": { "type": "string" }, "take_minutes": { "type": "integer" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_head": { "type": "boolean" } } } }, "members_count": { "type": "integer" }, "is_member": { "type": "boolean" }, "is_head": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 9, "uuid": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "name": "Maintenance", "kind": "Repairs", "color": "#5249e6", "icon": "build", "description": "Equipment repairs in all coffee shops", "all_locations": false, "locations": [ { "id": 12, "name": "Abay Ave" } ], "routing": "load", "only_on_shift": true, "notify": "heads", "take_minutes": 30, "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "is_head": true } ], "members_count": 1, "is_member": true, "is_head": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/{id}/members/{user_id}": { "delete": { "operationId": "teamsMembersRemove", "summary": "Remove a team member", "tags": [ "Teams" ], "x-mcp-tool": "teams_members_remove", "x-permissions": [ "org.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "integer" } }, { "name": "user_id", "in": "path", "required": true, "description": "User id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/{id}/members/{user_id}/head": { "put": { "operationId": "teamsMembersHead", "summary": "Make or unmake a team head", "description": "A head distributes the team queue and sees team figures. Making a non-member a head adds them to the team.", "tags": [ "Teams" ], "x-mcp-tool": "teams_members_head", "x-permissions": [ "org.manage" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "integer" } }, { "name": "user_id", "in": "path", "required": true, "description": "User id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_head": { "type": "boolean", "default": true } } }, "example": { "is_head": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "all_locations": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "routing": { "type": "string" }, "only_on_shift": { "type": "boolean" }, "notify": { "type": "string" }, "take_minutes": { "type": "integer" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "is_head": { "type": "boolean" } } } }, "members_count": { "type": "integer" }, "is_member": { "type": "boolean" }, "is_head": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 9, "uuid": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "name": "Maintenance", "kind": "Repairs", "color": "#5249e6", "icon": "build", "description": "Equipment repairs in all coffee shops", "all_locations": false, "locations": [ { "id": 12, "name": "Abay Ave" } ], "routing": "load", "only_on_shift": true, "notify": "heads", "take_minutes": 30, "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "is_head": true } ], "members_count": 1, "is_member": true, "is_head": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/teams/{id}/schedule": { "get": { "operationId": "teamsSchedule", "summary": "Get the team schedule for a week", "description": "Published shifts and approved absences of team members for the week containing `from`. Available to team heads and with `org.view`.", "tags": [ "Teams" ], "x-mcp-tool": "teams_schedule", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "description": "Any day of the week, default — current week", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "days": { "type": "array", "items": { "type": "string", "format": "date" } }, "members": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "on_shift_now": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "location": { "type": "string" }, "color": { "type": "string" } } } }, "absence": { "type": [ "string", "null" ] } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "from": "2026-11-02", "days": [ "2026-11-02", "2026-11-03" ], "members": [ { "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "on_shift_now": "Abay Ave", "days": [ { "date": "2026-11-02", "shifts": [ { "start": "09:00", "end": "18:00", "location": "Abay Ave", "color": "#5b54e8" } ], "absence": null } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/assignees/{id}": { "patch": { "operationId": "testingAssigneesUpdate", "summary": "Change the deadline of an employee", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignees_update", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignee id (one employee in an assignment)", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "due_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Personal deadline (null — none)" } }, "required": [ "due_at" ] }, "example": { "due_at": "2026-11-03T09:00:00+05:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "ok": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "testingAssigneesDelete", "summary": "Remove an employee from an assignment", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignees_delete", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignee id (one employee in an assignment)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/assignees/{id}/remind": { "post": { "operationId": "testingAssigneesRemind", "summary": "Remind an employee", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignees_remind", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignee id (one employee in an assignment)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "ok": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/assignees/{id}/restart": { "post": { "operationId": "testingAssigneesRestart", "summary": "Reset attempts of an employee", "description": "Starts a new cycle for one employee of an assignment (previous attempts stay in history) and notifies them.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignees_restart", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignee id (one employee in an assignment)", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "due_at": { "type": [ "string", "null" ], "format": "date-time", "description": "New personal deadline" } } }, "example": { "due_at": "2026-11-03T09:00:00+05:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "ok": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/assignments/{id}": { "get": { "operationId": "testingAssignmentsGet", "summary": "Retrieve an assignment", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignments_get", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignment id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "status": { "type": "string" }, "starts_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "recur_days": { "type": "integer" }, "recur_due_days": { "type": "integer" }, "close_after_due": { "type": "boolean" }, "auto_enroll": { "type": "boolean" }, "created_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer" } } } }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "in_progress": { "type": "integer" }, "review": { "type": "integer" }, "not_started": { "type": "integer" }, "overdue": { "type": "integer" }, "completion": { "type": "integer" } } }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position": { "type": "string" }, "status": { "type": "string" }, "overdue": { "type": "boolean" }, "attempts": { "type": "integer" }, "best_percent": { "type": "number" }, "best_attempt_uuid": { "type": "string", "format": "uuid" }, "due_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "cycle": { "type": "integer" }, "link": { "type": "string", "format": "uri" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 140, "title": "Onboarding — October", "message": "Please pass by Friday", "test": { "id": 58, "title": "Food safety basics" }, "status": "active", "starts_at": null, "due_at": "2026-11-07T18:00:00+05:00", "recur_days": 365, "recur_due_days": 14, "close_after_due": false, "auto_enroll": true, "created_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "created_at": "2026-10-31T09:00:00+05:00", "targets": [ { "kind": "position", "id": 7 } ], "progress": { "total": 12, "passed": 8, "failed": 1, "in_progress": 1, "review": 0, "not_started": 2, "overdue": 0, "completion": 67 }, "assignees": [ { "id": 5012, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position": "Cook", "status": "passed", "overdue": false, "attempts": 1, "best_percent": 86.7, "best_attempt_uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "due_at": "2026-11-07T18:00:00+05:00", "completed_at": "2026-11-02T16:20:00+05:00", "valid_until": "2027-11-02T16:20:00+05:00", "cycle": 1, "link": "https://app.jecheck.io/exam/Xy7…" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "testingAssignmentsUpdate", "summary": "Update an assignment", "description": "Close / reopen the assignment (`status`) or move the deadline for everyone who has not passed yet (`due_at`). Allowed to the author or with `testing.results` for all locations.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignments_update", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignment id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "closed" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time", "description": "New deadline" } } }, "example": { "status": "active", "due_at": "2026-11-03T09:00:00+05:00" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "status": { "type": "string" }, "starts_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "recur_days": { "type": "integer" }, "recur_due_days": { "type": "integer" }, "close_after_due": { "type": "boolean" }, "auto_enroll": { "type": "boolean" }, "created_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer" } } } }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "in_progress": { "type": "integer" }, "review": { "type": "integer" }, "not_started": { "type": "integer" }, "overdue": { "type": "integer" }, "completion": { "type": "integer" } } }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position": { "type": "string" }, "status": { "type": "string" }, "overdue": { "type": "boolean" }, "attempts": { "type": "integer" }, "best_percent": { "type": "number" }, "best_attempt_uuid": { "type": "string", "format": "uuid" }, "due_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "cycle": { "type": "integer" }, "link": { "type": "string", "format": "uri" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 140, "title": "Onboarding — October", "message": "Please pass by Friday", "test": { "id": 58, "title": "Food safety basics" }, "status": "active", "starts_at": null, "due_at": "2026-11-07T18:00:00+05:00", "recur_days": 365, "recur_due_days": 14, "close_after_due": false, "auto_enroll": true, "created_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "created_at": "2026-10-31T09:00:00+05:00", "targets": [ { "kind": "position", "id": 7 } ], "progress": { "total": 12, "passed": 8, "failed": 1, "in_progress": 1, "review": 0, "not_started": 2, "overdue": 0, "completion": 67 }, "assignees": [ { "id": 5012, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position": "Cook", "status": "passed", "overdue": false, "attempts": 1, "best_percent": 86.7, "best_attempt_uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "due_at": "2026-11-07T18:00:00+05:00", "completed_at": "2026-11-02T16:20:00+05:00", "valid_until": "2027-11-02T16:20:00+05:00", "cycle": 1, "link": "https://app.jecheck.io/exam/Xy7…" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "testingAssignmentsDelete", "summary": "Delete an assignment", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignments_delete", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignment id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/assignments/{id}/remind": { "post": { "operationId": "testingAssignmentsRemind", "summary": "Remind assignees", "description": "Sends a reminder to everyone who has not passed yet.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignments_remind", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignment id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reminded": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "reminded": 4 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/assignments/{id}/sync": { "post": { "operationId": "testingAssignmentsSync", "summary": "Add new matching employees", "description": "Adds employees who now match the targets (new hires in the position or location) and notifies them.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignments_sync", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Assignment id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "added": 2 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/attempts": { "get": { "operationId": "testingAttemptsList", "summary": "List attempts", "description": "Attempts of employees of the locations of `testing.results` (guests of open links — only with the permission for all locations), newest first.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_attempts_list", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "test_id", "in": "query", "description": "Only this test", "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "description": "Only this employee", "schema": { "type": "integer" } }, { "name": "location_ids[]", "in": "query", "description": "Only employees of these locations", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "status", "in": "query", "description": "`flagged` — strict-mode attempts with a low trust score", "schema": { "type": "string", "enum": [ "passed", "failed", "review", "annulled", "in_progress", "flagged" ] } }, { "name": "search", "in": "query", "description": "Search by employee or guest name / email", "schema": { "type": "string", "maxLength": 100 } }, { "name": "date_from", "in": "query", "description": "Started from", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Started to", "schema": { "type": "string", "format": "date" } }, { "name": "updated_since", "in": "query", "description": "Only attempts changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "strict": { "type": "boolean" }, "status": { "type": "string" }, "percent": { "type": "number" }, "score": { "type": "integer" }, "max_score": { "type": "integer" }, "passed": { "type": "boolean" }, "critical_failed": { "type": "boolean" }, "finish_reason": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "violations": { "type": "integer" }, "trust_score": { "type": [ "string", "null" ] }, "trust_level": { "type": [ "string", "null" ] }, "reviewed": { "type": "boolean" }, "certificate_number": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "test": { "id": 58, "title": "Food safety basics" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest": null, "channel": "app", "strict": false, "status": "completed", "percent": 86.7, "score": 13, "max_score": 15, "passed": true, "critical_failed": false, "finish_reason": "manual", "started_at": "2026-11-02T16:02:00+05:00", "submitted_at": "2026-11-02T16:20:00+05:00", "duration_sec": 1080, "violations": 0, "trust_score": null, "trust_level": null, "reviewed": false, "certificate_number": "JC-2026-000412", "url": "https://app.jecheck.io/ui/testing/attempts/8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/attempts/{uuid}": { "get": { "operationId": "testingAttemptsGet", "summary": "Retrieve an attempt", "description": "Attempt with every question: the employee's answer, the correct answer, points and manual-review state. `can_review` tells whether the token may grade it.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_attempts_get", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "strict": { "type": "boolean" }, "status": { "type": "string" }, "percent": { "type": "number" }, "score": { "type": "integer" }, "max_score": { "type": "integer" }, "passed": { "type": "boolean" }, "critical_failed": { "type": "boolean" }, "finish_reason": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "violations": { "type": "integer" }, "trust_score": { "type": [ "string", "null" ] }, "trust_level": { "type": [ "string", "null" ] }, "reviewed": { "type": "boolean" }, "certificate_number": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "review_note": { "type": [ "string", "null" ] }, "can_review": { "type": "boolean" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "n": { "type": "integer" }, "section": { "type": "string" }, "type": { "type": "string" }, "body": { "type": "string" }, "your_answer": { "type": "string" }, "correct_answer": { "type": "string" }, "is_correct": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "points": { "type": "integer" }, "max_points": { "type": "integer" }, "is_critical": { "type": "boolean" }, "feedback": { "type": [ "string", "null" ] }, "rubric": { "type": [ "string", "null" ] }, "time_spent_sec": { "type": "integer" }, "graded_manually": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "test": { "id": 58, "title": "Food safety basics" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest": null, "channel": "app", "strict": false, "status": "completed", "percent": 86.7, "score": 13, "max_score": 15, "passed": true, "critical_failed": false, "finish_reason": "manual", "started_at": "2026-11-02T16:02:00+05:00", "submitted_at": "2026-11-02T16:20:00+05:00", "duration_sec": 1080, "violations": 0, "trust_score": null, "trust_level": null, "reviewed": false, "certificate_number": "JC-2026-000412", "url": "https://app.jecheck.io/ui/testing/attempts/8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "review_note": null, "can_review": true, "answers": [ { "question_id": 901, "n": 1, "section": "Storage", "type": "single", "body": "At what temperature must chilled food be stored?", "your_answer": "0…+4 °C", "correct_answer": "0…+4 °C", "is_correct": true, "needs_review": false, "points": 1, "max_points": 1, "is_critical": true, "feedback": null, "rubric": null, "time_spent_sec": 41, "graded_manually": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/attempts/{uuid}/annul": { "post": { "operationId": "testingAttemptsAnnul", "summary": "Annul an attempt", "description": "Cancels the result (e.g. cheating in strict mode); the employee can take the test again.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_attempts_annul", "x-permissions": [ "testing.review" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "Reason", "minLength": 1, "maxLength": 1000 } }, "required": [ "note" ] }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "strict": { "type": "boolean" }, "status": { "type": "string" }, "percent": { "type": "number" }, "score": { "type": "integer" }, "max_score": { "type": "integer" }, "passed": { "type": "boolean" }, "critical_failed": { "type": "boolean" }, "finish_reason": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "violations": { "type": "integer" }, "trust_score": { "type": [ "string", "null" ] }, "trust_level": { "type": [ "string", "null" ] }, "reviewed": { "type": "boolean" }, "certificate_number": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "review_note": { "type": [ "string", "null" ] }, "can_review": { "type": "boolean" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "n": { "type": "integer" }, "section": { "type": "string" }, "type": { "type": "string" }, "body": { "type": "string" }, "your_answer": { "type": "string" }, "correct_answer": { "type": "string" }, "is_correct": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "points": { "type": "integer" }, "max_points": { "type": "integer" }, "is_critical": { "type": "boolean" }, "feedback": { "type": [ "string", "null" ] }, "rubric": { "type": [ "string", "null" ] }, "time_spent_sec": { "type": "integer" }, "graded_manually": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "test": { "id": 58, "title": "Food safety basics" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest": null, "channel": "app", "strict": false, "status": "completed", "percent": 86.7, "score": 13, "max_score": 15, "passed": true, "critical_failed": false, "finish_reason": "manual", "started_at": "2026-11-02T16:02:00+05:00", "submitted_at": "2026-11-02T16:20:00+05:00", "duration_sec": 1080, "violations": 0, "trust_score": null, "trust_level": null, "reviewed": false, "certificate_number": "JC-2026-000412", "url": "https://app.jecheck.io/ui/testing/attempts/8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "review_note": null, "can_review": true, "answers": [ { "question_id": 901, "n": 1, "section": "Storage", "type": "single", "body": "At what temperature must chilled food be stored?", "your_answer": "0…+4 °C", "correct_answer": "0…+4 °C", "is_correct": true, "needs_review": false, "points": 1, "max_points": 1, "is_critical": true, "feedback": null, "rubric": null, "time_spent_sec": 41, "graded_manually": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/attempts/{uuid}/confirm": { "post": { "operationId": "testingAttemptsConfirm", "summary": "Confirm an attempt result", "description": "Marks the attempt as reviewed (e.g. after checking a strict-mode recording).", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_attempts_confirm", "x-permissions": [ "testing.review" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "example": { "note": "Seal on fridge #2 is torn, temperature rises to +9 °C." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "strict": { "type": "boolean" }, "status": { "type": "string" }, "percent": { "type": "number" }, "score": { "type": "integer" }, "max_score": { "type": "integer" }, "passed": { "type": "boolean" }, "critical_failed": { "type": "boolean" }, "finish_reason": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "violations": { "type": "integer" }, "trust_score": { "type": [ "string", "null" ] }, "trust_level": { "type": [ "string", "null" ] }, "reviewed": { "type": "boolean" }, "certificate_number": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "review_note": { "type": [ "string", "null" ] }, "can_review": { "type": "boolean" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "n": { "type": "integer" }, "section": { "type": "string" }, "type": { "type": "string" }, "body": { "type": "string" }, "your_answer": { "type": "string" }, "correct_answer": { "type": "string" }, "is_correct": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "points": { "type": "integer" }, "max_points": { "type": "integer" }, "is_critical": { "type": "boolean" }, "feedback": { "type": [ "string", "null" ] }, "rubric": { "type": [ "string", "null" ] }, "time_spent_sec": { "type": "integer" }, "graded_manually": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "test": { "id": 58, "title": "Food safety basics" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest": null, "channel": "app", "strict": false, "status": "completed", "percent": 86.7, "score": 13, "max_score": 15, "passed": true, "critical_failed": false, "finish_reason": "manual", "started_at": "2026-11-02T16:02:00+05:00", "submitted_at": "2026-11-02T16:20:00+05:00", "duration_sec": 1080, "violations": 0, "trust_score": null, "trust_level": null, "reviewed": false, "certificate_number": "JC-2026-000412", "url": "https://app.jecheck.io/ui/testing/attempts/8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "review_note": null, "can_review": true, "answers": [ { "question_id": 901, "n": 1, "section": "Storage", "type": "single", "body": "At what temperature must chilled food be stored?", "your_answer": "0…+4 °C", "correct_answer": "0…+4 °C", "is_correct": true, "needs_review": false, "points": 1, "max_points": 1, "is_critical": true, "feedback": null, "rubric": null, "time_spent_sec": 41, "graded_manually": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/attempts/{uuid}/grade": { "post": { "operationId": "testingAttemptsGrade", "summary": "Grade an open answer", "description": "Sets points (and optional feedback) for a question, usually an essay waiting for manual review. When all answers are graded the attempt gets its final result and the employee is notified.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_attempts_grade", "x-permissions": [ "testing.review" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question_id": { "type": "integer" }, "points": { "type": "number", "minimum": 0 }, "feedback": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "question_id", "points" ] }, "example": { "question_id": 42, "points": 4.5, "feedback": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "guest": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "strict": { "type": "boolean" }, "status": { "type": "string" }, "percent": { "type": "number" }, "score": { "type": "integer" }, "max_score": { "type": "integer" }, "passed": { "type": "boolean" }, "critical_failed": { "type": "boolean" }, "finish_reason": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "violations": { "type": "integer" }, "trust_score": { "type": [ "string", "null" ] }, "trust_level": { "type": [ "string", "null" ] }, "reviewed": { "type": "boolean" }, "certificate_number": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "review_note": { "type": [ "string", "null" ] }, "can_review": { "type": "boolean" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "integer" }, "n": { "type": "integer" }, "section": { "type": "string" }, "type": { "type": "string" }, "body": { "type": "string" }, "your_answer": { "type": "string" }, "correct_answer": { "type": "string" }, "is_correct": { "type": "boolean" }, "needs_review": { "type": "boolean" }, "points": { "type": "integer" }, "max_points": { "type": "integer" }, "is_critical": { "type": "boolean" }, "feedback": { "type": [ "string", "null" ] }, "rubric": { "type": [ "string", "null" ] }, "time_spent_sec": { "type": "integer" }, "graded_manually": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "test": { "id": 58, "title": "Food safety basics" }, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "guest": null, "channel": "app", "strict": false, "status": "completed", "percent": 86.7, "score": 13, "max_score": 15, "passed": true, "critical_failed": false, "finish_reason": "manual", "started_at": "2026-11-02T16:02:00+05:00", "submitted_at": "2026-11-02T16:20:00+05:00", "duration_sec": 1080, "violations": 0, "trust_score": null, "trust_level": null, "reviewed": false, "certificate_number": "JC-2026-000412", "url": "https://app.jecheck.io/ui/testing/attempts/8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "review_note": null, "can_review": true, "answers": [ { "question_id": 901, "n": 1, "section": "Storage", "type": "single", "body": "At what temperature must chilled food be stored?", "your_answer": "0…+4 °C", "correct_answer": "0…+4 °C", "is_correct": true, "needs_review": false, "points": 1, "max_points": 1, "is_critical": true, "feedback": null, "rubric": null, "time_spent_sec": 41, "graded_manually": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/my": { "get": { "operationId": "testingMyList", "summary": "List my assigned tests", "description": "Tests assigned to the acting user with availability: `can_start`, `reason`, `open_attempt`, `web_only` (strict-mode tests are taken on the website by `url`).", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_my_list", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "assignee_id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "overdue": { "type": "boolean" }, "due_at": { "type": "string", "format": "date-time" }, "starts_at": { "type": [ "string", "null" ] }, "valid_until": { "type": [ "string", "null" ] }, "best_percent": { "type": [ "string", "null" ] }, "pass_score": { "type": "integer" }, "questions_count": { "type": "integer" }, "time_limit_minutes": { "type": "integer" }, "strict": { "type": "boolean" }, "web_only": { "type": "boolean" }, "can_start": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "open_attempt": { "type": [ "string", "null" ] }, "attempts_left": { "type": "integer" }, "last_attempt": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "assignee_id": 5012, "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "message": "Please pass by Friday", "status": "assigned", "overdue": false, "due_at": "2026-11-07T18:00:00+05:00", "starts_at": null, "valid_until": null, "best_percent": null, "pass_score": 80, "questions_count": 15, "time_limit_minutes": 20, "strict": false, "web_only": false, "can_start": true, "reason": null, "open_attempt": null, "attempts_left": 3, "last_attempt": null, "url": "https://app.jecheck.io/exam/Xy7…" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/my/attempts/{uuid}": { "get": { "operationId": "testingMyAttemptsGet", "summary": "Get my attempt state", "description": "Questions, saved answers and the remaining time of an attempt of the acting user.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_my_attempts_get", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attempt": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "channel": { "type": "string" }, "strict": { "type": "boolean" }, "started_at": { "type": "string", "format": "date-time" }, "deadline_at": { "type": "string", "format": "date-time" }, "remaining_sec": { "type": "integer" }, "current_index": { "type": "integer" }, "violations": { "type": "integer" }, "identity_photo": { "type": "boolean" } } }, "test": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "navigation": { "type": "string" }, "pass_score": { "type": "integer" }, "time_limit_minutes": { "type": "integer" }, "questions_count": { "type": "integer" }, "max_score": { "type": "integer" }, "proctoring": { "type": [ "string", "null" ] } } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "points": { "type": "integer" }, "section": { "type": "string" }, "multiple_hint": { "type": [ "string", "null" ] }, "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" } } } }, "response": { "type": [ "string", "null" ] }, "flagged": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "attempt": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "status": "in_progress", "channel": "app", "strict": false, "started_at": "2026-11-02T16:02:00+05:00", "deadline_at": "2026-11-02T16:22:00+05:00", "remaining_sec": 1150, "current_index": 0, "violations": 0, "identity_photo": false }, "test": { "title": "Food safety basics", "description": "For new kitchen staff", "navigation": "free", "pass_score": 80, "time_limit_minutes": 20, "questions_count": 15, "max_score": 15, "proctoring": null }, "questions": [ { "id": 901, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "points": 1, "section": "Storage", "multiple_hint": null, "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C" }, { "id": "e5f6g7h8", "text": "+8…+12 °C" } ], "response": null, "flagged": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/my/attempts/{uuid}/answer": { "post": { "operationId": "testingMyAttemptsAnswer", "summary": "Save an answer", "description": "Saves the answer to one question. `response` by type: single {\"choice\": \"\"}, multiple {\"choices\": [\"\"]}, true_false {\"value\": true}, text/essay {\"text\": \"…\"}, number {\"value\": 4}, ordering {\"order\": [\"\", …]}, matching {\"pairs\": {\"\": \"\"}}. Pass `flagged` alone to mark the question for later.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_my_attempts_answer", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question_id": { "type": "integer" }, "response": { "type": [ "object", "null" ], "properties": {}, "additionalProperties": true, "description": "Answer, see the description" }, "time_spent_sec": { "type": "integer", "minimum": 0 }, "flagged": { "type": "boolean" } }, "required": [ "question_id" ] }, "example": { "question_id": 42, "response": [], "time_spent_sec": 42, "flagged": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "saved": { "type": "boolean" }, "answered": { "type": "boolean" }, "remaining_sec": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "saved": true, "answered": true, "remaining_sec": 1120 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/my/attempts/{uuid}/finish": { "post": { "operationId": "testingMyAttemptsFinish", "summary": "Finish my attempt", "description": "Submits the attempt and returns the result in the scope allowed by the test (`show`).", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_my_attempts_finish", "x-scope": "write", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "show": { "type": "string" }, "finish_reason": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "pass_score": { "type": "integer" }, "questions_count": { "type": "integer" }, "certificate_number": { "type": "string" }, "pdf_url": { "type": "string", "format": "uri" }, "retry": { "type": [ "string", "null" ] }, "percent": { "type": "number" }, "score": { "type": "integer" }, "max_score": { "type": "integer" }, "passed": { "type": "boolean" }, "critical_failed": { "type": "boolean" }, "correct_count": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "title": "Food safety basics", "status": "completed", "show": "score", "finish_reason": "manual", "submitted_at": "2026-11-02T16:20:00+05:00", "duration_sec": 1080, "pass_score": 80, "questions_count": 15, "certificate_number": "JC-2026-000412", "pdf_url": "https://app.jecheck.io/exam/a/8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a/pdf", "retry": null, "percent": 86.7, "score": 13, "max_score": 15, "passed": true, "critical_failed": false, "correct_count": 13 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/my/attempts/{uuid}/result": { "get": { "operationId": "testingMyAttemptsResult", "summary": "Get my attempt result", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_my_attempts_result", "x-scope": "read", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Attempt UUID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "show": { "type": "string" }, "finish_reason": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "duration_sec": { "type": "integer" }, "pass_score": { "type": "integer" }, "questions_count": { "type": "integer" }, "certificate_number": { "type": "string" }, "pdf_url": { "type": "string", "format": "uri" }, "retry": { "type": [ "string", "null" ] }, "percent": { "type": "number" }, "score": { "type": "integer" }, "max_score": { "type": "integer" }, "passed": { "type": "boolean" }, "critical_failed": { "type": "boolean" }, "correct_count": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "title": "Food safety basics", "status": "completed", "show": "score", "finish_reason": "manual", "submitted_at": "2026-11-02T16:20:00+05:00", "duration_sec": 1080, "pass_score": 80, "questions_count": 15, "certificate_number": "JC-2026-000412", "pdf_url": "https://app.jecheck.io/exam/a/8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a/pdf", "retry": null, "percent": 86.7, "score": 13, "max_score": 15, "passed": true, "critical_failed": false, "correct_count": 13 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/my/history": { "get": { "operationId": "testingMyHistory", "summary": "List my finished attempts", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_my_history", "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "percent": { "type": "number" }, "passed": { "type": "boolean" }, "certificate_number": { "type": "string" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "title": "Food safety basics", "status": "completed", "submitted_at": "2026-11-02T16:20:00+05:00", "percent": 86.7, "passed": true, "certificate_number": "JC-2026-000412" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/my/start": { "post": { "operationId": "testingMyStart", "summary": "Start or continue my test", "description": "Starts an attempt of an assigned test as the acting user (or returns the open one) and returns questions without correct answers. Strict-mode and website-only tests return `409 web_only` with `web_url` to open in a browser.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_my_start", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignee_id": { "type": "integer", "description": "`assignee_id` from `testing.my.list`" } }, "required": [ "assignee_id" ] }, "example": { "assignee_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attempt": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "channel": { "type": "string" }, "strict": { "type": "boolean" }, "started_at": { "type": "string", "format": "date-time" }, "deadline_at": { "type": "string", "format": "date-time" }, "remaining_sec": { "type": "integer" }, "current_index": { "type": "integer" }, "violations": { "type": "integer" }, "identity_photo": { "type": "boolean" } } }, "test": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "navigation": { "type": "string" }, "pass_score": { "type": "integer" }, "time_limit_minutes": { "type": "integer" }, "questions_count": { "type": "integer" }, "max_score": { "type": "integer" }, "proctoring": { "type": [ "string", "null" ] } } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "points": { "type": "integer" }, "section": { "type": "string" }, "multiple_hint": { "type": [ "string", "null" ] }, "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" } } } }, "response": { "type": [ "string", "null" ] }, "flagged": { "type": "boolean" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "attempt": { "uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "status": "in_progress", "channel": "app", "strict": false, "started_at": "2026-11-02T16:02:00+05:00", "deadline_at": "2026-11-02T16:22:00+05:00", "remaining_sec": 1150, "current_index": 0, "violations": 0, "identity_photo": false }, "test": { "title": "Food safety basics", "description": "For new kitchen staff", "navigation": "free", "pass_score": 80, "time_limit_minutes": 20, "questions_count": 15, "max_score": 15, "proctoring": null }, "questions": [ { "id": 901, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "points": 1, "section": "Storage", "multiple_hint": null, "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C" }, { "id": "e5f6g7h8", "text": "+8…+12 °C" } ], "response": null, "flagged": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests": { "get": { "operationId": "testingTestsList", "summary": "List tests", "description": "All tests of the company with statistics limited to the locations of the `testing.results` permission.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_list", "x-permissions": [ "testing.manage", "testing.results" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "status[]", "in": "query", "description": "Filter by status: draft, published, archived", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "search", "in": "query", "description": "Search in title and category", "schema": { "type": "string", "maxLength": 200 } }, { "name": "updated_since", "in": "query", "description": "Only tests changed after this moment", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "strict": { "type": "boolean" }, "public_enabled": { "type": "boolean" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "questions_count": { "type": "integer" }, "attempts": { "type": "integer" }, "avg_percent": { "type": "number" }, "pass_rate": { "type": "integer" }, "assigned": { "type": "integer" }, "assigned_passed": { "type": "integer" }, "overdue": { "type": "integer" }, "pending_review": { "type": "integer" }, "last_attempt_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "status": "published", "strict": false, "public_enabled": false, "time_limit_minutes": 20, "pass_score": 80, "questions_count": 15, "attempts": 42, "avg_percent": 84.5, "pass_rate": 76, "assigned": 30, "assigned_passed": 22, "overdue": 3, "pending_review": 1, "last_attempt_at": "2026-11-02T16:20:00+05:00", "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/results" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "testingTestsCreate", "summary": "Create a test", "description": "Creates a draft test with one section. Optionally pass `questions` to fill it in one call, then `publish` it. ", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_create", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Test title", "minLength": 2, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "category": { "type": [ "string", "null" ], "maxLength": 120 }, "cover_color": { "type": [ "string", "null" ], "description": "Card colour, e.g. `#2563eb`", "maxLength": 20 }, "time_limit_minutes": { "type": [ "integer", "null" ], "description": "Time limit (null — unlimited)", "minimum": 1, "maximum": 600 }, "pass_score": { "type": "integer", "description": "Pass threshold, percent", "minimum": 0, "maximum": 100 }, "attempts_limit": { "type": [ "integer", "null" ], "description": "Attempts per assignment cycle (null — unlimited)", "minimum": 1, "maximum": 100 }, "retry_cooldown_hours": { "type": [ "integer", "null" ], "description": "Pause between attempts, hours", "minimum": 0, "maximum": 8760 }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string", "enum": [ "free", "linear" ], "description": "`linear` — no going back to previous questions" }, "show_result": { "type": "string", "enum": [ "none", "score", "answers", "full" ], "description": "What the employee sees after finishing" }, "allow_app": { "type": "boolean", "description": "Can be taken in the mobile app" }, "allow_web": { "type": "boolean", "description": "Can be taken on the website" }, "certificate_enabled": { "type": "boolean", "description": "Issue a certificate on passing" }, "certificate_valid_days": { "type": [ "integer", "null" ], "description": "Certificate validity; employees are re-assigned when it expires", "minimum": 1, "maximum": 3650 }, "public_enabled": { "type": "boolean", "description": "Open link for people without an account" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Strict mode with camera (website only)" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer", "minimum": 10, "maximum": 600 }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 50 } }, "description": "Strict mode settings (partial update)" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "single", "multiple", "true_false", "text", "number", "ordering", "matching", "essay" ], "description": "Question type" }, "section_id": { "type": "integer", "description": "Section (block) id; default — the first section" }, "body": { "type": "string", "description": "Question text", "maxLength": 5000 }, "options": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Answer options by type: `single`/`multiple` — {\"choices\": [{\"text\": \"…\", \"correct\": true}]}; `true_false` — {\"correct\": true}; `text` — {\"answers\": [\"…\"], \"case_sensitive\": false}; `number` — {\"value\": 4, \"tolerance\": 0}; `ordering` — {\"items\": [{\"text\": \"…\"}]} in the correct order; `matching` — {\"pairs\": [{\"left\": \"…\", \"right\": \"…\"}]}; `essay` — {\"min_words\": 50, \"rubric\": \"…\"} (graded manually)." }, "points": { "type": "number", "description": "Points, default 1", "minimum": 0, "maximum": 100 }, "partial_credit": { "type": "boolean", "description": "Partial points for multiple / ordering / matching" }, "is_critical": { "type": "boolean", "description": "A wrong answer fails the whole test" }, "explanation": { "type": [ "string", "null" ], "description": "Shown to the employee after the test when `show_result` = `full`", "maxLength": 5000 }, "media_url": { "type": [ "string", "null" ], "description": "Image URL (upload with `testing.tests.images.upload`)", "maxLength": 1024 } }, "required": [ "type", "body" ] }, "description": "Questions to add to the first section", "maxItems": 100 } }, "required": [ "title" ] }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "category": "string", "cover_color": "string" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "cover_color": { "type": "string" }, "status": { "type": "string" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "attempts_limit": { "type": "integer" }, "retry_cooldown_hours": { "type": "integer" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string" }, "show_result": { "type": "string" }, "allow_app": { "type": "boolean" }, "allow_web": { "type": "boolean" }, "certificate_enabled": { "type": "boolean" }, "certificate_valid_days": { "type": "integer" }, "public_enabled": { "type": "boolean" }, "public_url": { "type": [ "string", "null" ] }, "strict": { "type": "boolean" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer" }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "string", "null" ] } } }, "questions_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "problems": { "type": "array" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "cover_color": "#2563eb", "status": "published", "time_limit_minutes": 20, "pass_score": 80, "attempts_limit": 3, "retry_cooldown_hours": 24, "shuffle_questions": true, "shuffle_options": true, "navigation": "free", "show_result": "answers", "allow_app": true, "allow_web": true, "certificate_enabled": true, "certificate_valid_days": 365, "public_enabled": false, "public_url": null, "strict": false, "proctoring": { "enabled": false, "camera": true, "identity_photo": true, "snapshot_interval": 60, "fullscreen": true, "block_copy": true, "face_detection": true, "max_violations": null }, "questions_count": 15, "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/edit", "problems": [], "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}": { "get": { "operationId": "testingTestsGet", "summary": "Retrieve a test", "description": "Test settings. Sections with questions and correct answers (`sections`, `problems`) are returned only with `testing.manage`; otherwise they are `null`.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_get", "x-permissions": [ "testing.manage", "testing.results" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "cover_color": { "type": "string" }, "status": { "type": "string" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "attempts_limit": { "type": "integer" }, "retry_cooldown_hours": { "type": "integer" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string" }, "show_result": { "type": "string" }, "allow_app": { "type": "boolean" }, "allow_web": { "type": "boolean" }, "certificate_enabled": { "type": "boolean" }, "certificate_valid_days": { "type": "integer" }, "public_enabled": { "type": "boolean" }, "public_url": { "type": [ "string", "null" ] }, "strict": { "type": "boolean" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer" }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "string", "null" ] } } }, "questions_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "problems": { "type": "array" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "cover_color": "#2563eb", "status": "published", "time_limit_minutes": 20, "pass_score": 80, "attempts_limit": 3, "retry_cooldown_hours": 24, "shuffle_questions": true, "shuffle_options": true, "navigation": "free", "show_result": "answers", "allow_app": true, "allow_web": true, "certificate_enabled": true, "certificate_valid_days": 365, "public_enabled": false, "public_url": null, "strict": false, "proctoring": { "enabled": false, "camera": true, "identity_photo": true, "snapshot_interval": 60, "fullscreen": true, "block_copy": true, "face_detection": true, "max_violations": null }, "questions_count": 15, "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/edit", "problems": [], "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "testingTestsUpdate", "summary": "Update test settings", "description": "Partial update of the test settings. Enabling strict mode (`proctoring.enabled`) also enables taking the test on the website.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_update", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Test title", "minLength": 2, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "category": { "type": [ "string", "null" ], "maxLength": 120 }, "cover_color": { "type": [ "string", "null" ], "description": "Card colour, e.g. `#2563eb`", "maxLength": 20 }, "time_limit_minutes": { "type": [ "integer", "null" ], "description": "Time limit (null — unlimited)", "minimum": 1, "maximum": 600 }, "pass_score": { "type": "integer", "description": "Pass threshold, percent", "minimum": 0, "maximum": 100 }, "attempts_limit": { "type": [ "integer", "null" ], "description": "Attempts per assignment cycle (null — unlimited)", "minimum": 1, "maximum": 100 }, "retry_cooldown_hours": { "type": [ "integer", "null" ], "description": "Pause between attempts, hours", "minimum": 0, "maximum": 8760 }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string", "enum": [ "free", "linear" ], "description": "`linear` — no going back to previous questions" }, "show_result": { "type": "string", "enum": [ "none", "score", "answers", "full" ], "description": "What the employee sees after finishing" }, "allow_app": { "type": "boolean", "description": "Can be taken in the mobile app" }, "allow_web": { "type": "boolean", "description": "Can be taken on the website" }, "certificate_enabled": { "type": "boolean", "description": "Issue a certificate on passing" }, "certificate_valid_days": { "type": [ "integer", "null" ], "description": "Certificate validity; employees are re-assigned when it expires", "minimum": 1, "maximum": 3650 }, "public_enabled": { "type": "boolean", "description": "Open link for people without an account" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Strict mode with camera (website only)" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer", "minimum": 10, "maximum": 600 }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 50 } }, "description": "Strict mode settings (partial update)" } } }, "example": { "title": "Replace the broken fridge seal", "description": "Seal on fridge #2 is torn, temperature rises to +9 °C.", "category": "string", "cover_color": "string" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "cover_color": { "type": "string" }, "status": { "type": "string" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "attempts_limit": { "type": "integer" }, "retry_cooldown_hours": { "type": "integer" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string" }, "show_result": { "type": "string" }, "allow_app": { "type": "boolean" }, "allow_web": { "type": "boolean" }, "certificate_enabled": { "type": "boolean" }, "certificate_valid_days": { "type": "integer" }, "public_enabled": { "type": "boolean" }, "public_url": { "type": [ "string", "null" ] }, "strict": { "type": "boolean" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer" }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "string", "null" ] } } }, "questions_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "problems": { "type": "array" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "cover_color": "#2563eb", "status": "published", "time_limit_minutes": 20, "pass_score": 80, "attempts_limit": 3, "retry_cooldown_hours": 24, "shuffle_questions": true, "shuffle_options": true, "navigation": "free", "show_result": "answers", "allow_app": true, "allow_web": true, "certificate_enabled": true, "certificate_valid_days": 365, "public_enabled": false, "public_url": null, "strict": false, "proctoring": { "enabled": false, "camera": true, "identity_photo": true, "snapshot_interval": 60, "fullscreen": true, "block_copy": true, "face_detection": true, "max_violations": null }, "questions_count": 15, "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/edit", "problems": [], "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "testingTestsDelete", "summary": "Delete a test", "description": "Deletes the test and closes its assignments. Results of past attempts are kept.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_delete", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/analytics": { "get": { "operationId": "testingTestsAnalytics", "summary": "Get test analytics", "description": "Summary of finished attempts (pass rate, average, score distribution), per-question difficulty, results by section and by location — for employees of the locations of `testing.results`.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_analytics", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "description": "Attempts submitted from", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Attempts submitted to", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "attempts": { "type": "integer" }, "participants": { "type": "integer" }, "pass_rate": { "type": "integer" }, "avg_percent": { "type": "number" }, "median_duration": { "type": "integer" }, "pending_review": { "type": "integer" }, "low_trust": { "type": "integer" }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "count": { "type": "integer" } } } }, "pass_score": { "type": "integer" } } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "exists": { "type": "boolean" }, "position": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "section": { "type": "string" }, "answers": { "type": "integer" }, "correct_rate": { "type": "integer" }, "avg_time": { "type": "integer" }, "discrimination": { "type": "number" }, "flag": { "type": [ "string", "null" ] }, "choices": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "correct": { "type": "boolean" }, "share": { "type": "integer" } } } }, "top_wrong": { "type": [ "string", "null" ] } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "percent": { "type": "integer" } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "total": { "type": "integer" }, "passed": { "type": "integer" }, "completion": { "type": "integer" }, "avg_percent": { "type": "number" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "summary": { "attempts": 42, "participants": 30, "pass_rate": 76, "avg_percent": 84.5, "median_duration": 960, "pending_review": 1, "low_trust": 0, "distribution": [ { "from": 90, "to": 100, "count": 12 } ], "pass_score": 80 }, "questions": [ { "id": 901, "exists": true, "position": 1, "type": "single", "body": "At what temperature must chilled food be stored?", "section": "Storage", "answers": 42, "correct_rate": 64, "avg_time": 38, "discrimination": 0.31, "flag": null, "choices": [ { "text": "0…+4 °C", "correct": true, "share": 64 } ], "top_wrong": null } ], "sections": [ { "name": "Storage", "percent": 71 } ], "locations": [ { "id": 12, "name": "Abay Ave", "total": 10, "passed": 8, "completion": 80, "avg_percent": 85.2 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/assignments": { "get": { "operationId": "testingAssignmentsList", "summary": "List assignments of a test", "description": "Assignments with progress and per-employee status. Only employees of the locations of `testing.results` are included.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignments_list", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "status": { "type": "string" }, "starts_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "recur_days": { "type": "integer" }, "recur_due_days": { "type": "integer" }, "close_after_due": { "type": "boolean" }, "auto_enroll": { "type": "boolean" }, "created_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer" } } } }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "in_progress": { "type": "integer" }, "review": { "type": "integer" }, "not_started": { "type": "integer" }, "overdue": { "type": "integer" }, "completion": { "type": "integer" } } }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position": { "type": "string" }, "status": { "type": "string" }, "overdue": { "type": "boolean" }, "attempts": { "type": "integer" }, "best_percent": { "type": "number" }, "best_attempt_uuid": { "type": "string", "format": "uuid" }, "due_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "cycle": { "type": "integer" }, "link": { "type": "string", "format": "uri" } } } } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 140, "title": "Onboarding — October", "message": "Please pass by Friday", "test": { "id": 58, "title": "Food safety basics" }, "status": "active", "starts_at": null, "due_at": "2026-11-07T18:00:00+05:00", "recur_days": 365, "recur_due_days": 14, "close_after_due": false, "auto_enroll": true, "created_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "created_at": "2026-10-31T09:00:00+05:00", "targets": [ { "kind": "position", "id": 7 } ], "progress": { "total": 12, "passed": 8, "failed": 1, "in_progress": 1, "review": 0, "not_started": 2, "overdue": 0, "completion": 67 }, "assignees": [ { "id": 5012, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position": "Cook", "status": "passed", "overdue": false, "attempts": 1, "best_percent": 86.7, "best_attempt_uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "due_at": "2026-11-07T18:00:00+05:00", "completed_at": "2026-11-02T16:20:00+05:00", "valid_until": "2027-11-02T16:20:00+05:00", "cycle": 1, "link": "https://app.jecheck.io/exam/Xy7…" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "testingAssignmentsCreate", "summary": "Assign a test", "description": "Assigns a published test to employees, positions, locations or the whole company. Employees get a notification with a personal link; with `auto_enroll` new employees matching the targets are added automatically, with `recur_days` the test is re-assigned periodically. With a location-scoped permission only `user` and `department` targets within those locations are allowed.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_assignments_create", "x-permissions": [ "testing.results" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user", "position", "department", "all" ], "description": "`department` — a location" }, "id": { "type": [ "integer", "null" ], "description": "User, position or location id (omit for `all`)" } }, "required": [ "kind" ] }, "minItems": 1 }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "message": { "type": [ "string", "null" ], "description": "Message to employees", "maxLength": 1000 }, "starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Open from (notifications are sent then)" }, "due_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Deadline (future)" }, "recur_days": { "type": [ "integer", "null" ], "description": "Repeat every N days", "minimum": 1, "maximum": 3650 }, "recur_due_days": { "type": [ "integer", "null" ], "description": "Days to pass each repetition, default 14", "minimum": 1, "maximum": 365 }, "close_after_due": { "type": "boolean", "description": "Close the test for an employee after the deadline" }, "auto_enroll": { "type": "boolean", "description": "Add new matching employees automatically, default true" }, "remind": { "type": "boolean", "description": "Send deadline reminders, default true" } }, "required": [ "targets" ] }, "example": { "targets": [ { "kind": "user", "id": 42 } ], "title": "Replace the broken fridge seal", "message": "string", "starts_at": "2026-11-03T09:00:00+05:00" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "test": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" } } }, "status": { "type": "string" }, "starts_at": { "type": [ "string", "null" ] }, "due_at": { "type": "string", "format": "date-time" }, "recur_days": { "type": "integer" }, "recur_due_days": { "type": "integer" }, "close_after_due": { "type": "boolean" }, "auto_enroll": { "type": "boolean" }, "created_by": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer" } } } }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "in_progress": { "type": "integer" }, "review": { "type": "integer" }, "not_started": { "type": "integer" }, "overdue": { "type": "integer" }, "completion": { "type": "integer" } } }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "position": { "type": "string" }, "status": { "type": "string" }, "overdue": { "type": "boolean" }, "attempts": { "type": "integer" }, "best_percent": { "type": "number" }, "best_attempt_uuid": { "type": "string", "format": "uuid" }, "due_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "cycle": { "type": "integer" }, "link": { "type": "string", "format": "uri" } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 140, "title": "Onboarding — October", "message": "Please pass by Friday", "test": { "id": 58, "title": "Food safety basics" }, "status": "active", "starts_at": null, "due_at": "2026-11-07T18:00:00+05:00", "recur_days": 365, "recur_due_days": 14, "close_after_due": false, "auto_enroll": true, "created_by": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "created_at": "2026-10-31T09:00:00+05:00", "targets": [ { "kind": "position", "id": 7 } ], "progress": { "total": 12, "passed": 8, "failed": 1, "in_progress": 1, "review": 0, "not_started": 2, "overdue": 0, "completion": 67 }, "assignees": [ { "id": 5012, "user": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "name": "Aigerim Sadykova" }, "position": "Cook", "status": "passed", "overdue": false, "attempts": 1, "best_percent": 86.7, "best_attempt_uuid": "8c7b6a59-4e3d-4c2b-9a19-0f8e7d6c5b4a", "due_at": "2026-11-07T18:00:00+05:00", "completed_at": "2026-11-02T16:20:00+05:00", "valid_until": "2027-11-02T16:20:00+05:00", "cycle": 1, "link": "https://app.jecheck.io/exam/Xy7…" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/duplicate": { "post": { "operationId": "testingTestsDuplicate", "summary": "Duplicate a test", "description": "Creates a draft copy with all sections and questions.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_duplicate", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "cover_color": { "type": "string" }, "status": { "type": "string" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "attempts_limit": { "type": "integer" }, "retry_cooldown_hours": { "type": "integer" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string" }, "show_result": { "type": "string" }, "allow_app": { "type": "boolean" }, "allow_web": { "type": "boolean" }, "certificate_enabled": { "type": "boolean" }, "certificate_valid_days": { "type": "integer" }, "public_enabled": { "type": "boolean" }, "public_url": { "type": [ "string", "null" ] }, "strict": { "type": "boolean" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer" }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "string", "null" ] } } }, "questions_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "problems": { "type": "array" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "cover_color": "#2563eb", "status": "published", "time_limit_minutes": 20, "pass_score": 80, "attempts_limit": 3, "retry_cooldown_hours": 24, "shuffle_questions": true, "shuffle_options": true, "navigation": "free", "show_result": "answers", "allow_app": true, "allow_web": true, "certificate_enabled": true, "certificate_valid_days": 365, "public_enabled": false, "public_url": null, "strict": false, "proctoring": { "enabled": false, "camera": true, "identity_photo": true, "snapshot_interval": 60, "fullscreen": true, "block_copy": true, "face_detection": true, "max_violations": null }, "questions_count": 15, "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/edit", "problems": [], "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/images": { "post": { "operationId": "testingTestsImagesUpload", "summary": "Upload a question image", "description": "Uploads an image (up to 10 MB, converted to JPEG) and returns its URL for `media_url` of a question.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_images_upload", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" } }, "required": [ "image" ] } }, "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "object", "required": [ "name", "content_base64" ], "properties": { "name": { "type": "string", "description": "File name with extension" }, "content_base64": { "type": "string", "description": "File content, base64-encoded" } } } }, "required": [ "image" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } }, "required": [ "data" ] }, "example": { "data": { "url": "https://files.jecheck.io/exams/761/questions/a8Kd02.jpg" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/public-link": { "post": { "operationId": "testingTestsPublicLink", "summary": "Regenerate the public link", "description": "Issues a new open link for the test; the old one stops working.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_public_link", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "cover_color": { "type": "string" }, "status": { "type": "string" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "attempts_limit": { "type": "integer" }, "retry_cooldown_hours": { "type": "integer" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string" }, "show_result": { "type": "string" }, "allow_app": { "type": "boolean" }, "allow_web": { "type": "boolean" }, "certificate_enabled": { "type": "boolean" }, "certificate_valid_days": { "type": "integer" }, "public_enabled": { "type": "boolean" }, "public_url": { "type": [ "string", "null" ] }, "strict": { "type": "boolean" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer" }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "string", "null" ] } } }, "questions_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "problems": { "type": "array" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "cover_color": "#2563eb", "status": "published", "time_limit_minutes": 20, "pass_score": 80, "attempts_limit": 3, "retry_cooldown_hours": 24, "shuffle_questions": true, "shuffle_options": true, "navigation": "free", "show_result": "answers", "allow_app": true, "allow_web": true, "certificate_enabled": true, "certificate_valid_days": 365, "public_enabled": false, "public_url": null, "strict": false, "proctoring": { "enabled": false, "camera": true, "identity_photo": true, "snapshot_interval": 60, "fullscreen": true, "block_copy": true, "face_detection": true, "max_violations": null }, "questions_count": 15, "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/edit", "problems": [], "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/publish": { "post": { "operationId": "testingTestsPublish", "summary": "Publish a test", "description": "Publishes the test so it can be assigned. Fails with `validation_failed` listing the problems (no questions, missing correct answers…).", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_publish", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "cover_color": { "type": "string" }, "status": { "type": "string" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "attempts_limit": { "type": "integer" }, "retry_cooldown_hours": { "type": "integer" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string" }, "show_result": { "type": "string" }, "allow_app": { "type": "boolean" }, "allow_web": { "type": "boolean" }, "certificate_enabled": { "type": "boolean" }, "certificate_valid_days": { "type": "integer" }, "public_enabled": { "type": "boolean" }, "public_url": { "type": [ "string", "null" ] }, "strict": { "type": "boolean" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer" }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "string", "null" ] } } }, "questions_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "problems": { "type": "array" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "cover_color": "#2563eb", "status": "published", "time_limit_minutes": 20, "pass_score": 80, "attempts_limit": 3, "retry_cooldown_hours": 24, "shuffle_questions": true, "shuffle_options": true, "navigation": "free", "show_result": "answers", "allow_app": true, "allow_web": true, "certificate_enabled": true, "certificate_valid_days": 365, "public_enabled": false, "public_url": null, "strict": false, "proctoring": { "enabled": false, "camera": true, "identity_photo": true, "snapshot_interval": 60, "fullscreen": true, "block_copy": true, "face_detection": true, "max_violations": null }, "questions_count": 15, "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/edit", "problems": [], "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/questions": { "post": { "operationId": "testingQuestionsCreate", "summary": "Add a question", "description": "Adds a question to a section. Answer options by type: `single`/`multiple` — {\"choices\": [{\"text\": \"…\", \"correct\": true}]}; `true_false` — {\"correct\": true}; `text` — {\"answers\": [\"…\"], \"case_sensitive\": false}; `number` — {\"value\": 4, \"tolerance\": 0}; `ordering` — {\"items\": [{\"text\": \"…\"}]} in the correct order; `matching` — {\"pairs\": [{\"left\": \"…\", \"right\": \"…\"}]}; `essay` — {\"min_words\": 50, \"rubric\": \"…\"} (graded manually).", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_questions_create", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "single", "multiple", "true_false", "text", "number", "ordering", "matching", "essay" ], "description": "Question type" }, "section_id": { "type": "integer", "description": "Section (block) id; default — the first section" }, "body": { "type": "string", "description": "Question text", "maxLength": 5000 }, "options": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Answer options by type: `single`/`multiple` — {\"choices\": [{\"text\": \"…\", \"correct\": true}]}; `true_false` — {\"correct\": true}; `text` — {\"answers\": [\"…\"], \"case_sensitive\": false}; `number` — {\"value\": 4, \"tolerance\": 0}; `ordering` — {\"items\": [{\"text\": \"…\"}]} in the correct order; `matching` — {\"pairs\": [{\"left\": \"…\", \"right\": \"…\"}]}; `essay` — {\"min_words\": 50, \"rubric\": \"…\"} (graded manually)." }, "points": { "type": "number", "description": "Points, default 1", "minimum": 0, "maximum": 100 }, "partial_credit": { "type": "boolean", "description": "Partial points for multiple / ordering / matching" }, "is_critical": { "type": "boolean", "description": "A wrong answer fails the whole test" }, "explanation": { "type": [ "string", "null" ], "description": "Shown to the employee after the test when `show_result` = `full`", "maxLength": 5000 }, "media_url": { "type": [ "string", "null" ], "description": "Image URL (upload with `testing.tests.images.upload`)", "maxLength": 1024 } }, "required": [ "type", "body" ] }, "example": { "type": "single", "section_id": 42, "body": "string", "options": [] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/questions/batch": { "post": { "operationId": "testingQuestionsBatch", "summary": "Add questions in bulk", "description": "Adds up to 100 questions to a section in one call; items without a known type or text are skipped.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_questions_batch", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "section_id": { "type": [ "integer", "null" ], "description": "Target section, default — the first one" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "single", "multiple", "true_false", "text", "number", "ordering", "matching", "essay" ], "description": "Question type" }, "section_id": { "type": "integer", "description": "Section (block) id; default — the first section" }, "body": { "type": "string", "description": "Question text", "maxLength": 5000 }, "options": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Answer options by type: `single`/`multiple` — {\"choices\": [{\"text\": \"…\", \"correct\": true}]}; `true_false` — {\"correct\": true}; `text` — {\"answers\": [\"…\"], \"case_sensitive\": false}; `number` — {\"value\": 4, \"tolerance\": 0}; `ordering` — {\"items\": [{\"text\": \"…\"}]} in the correct order; `matching` — {\"pairs\": [{\"left\": \"…\", \"right\": \"…\"}]}; `essay` — {\"min_words\": 50, \"rubric\": \"…\"} (graded manually)." }, "points": { "type": "number", "description": "Points, default 1", "minimum": 0, "maximum": 100 }, "partial_credit": { "type": "boolean", "description": "Partial points for multiple / ordering / matching" }, "is_critical": { "type": "boolean", "description": "A wrong answer fails the whole test" }, "explanation": { "type": [ "string", "null" ], "description": "Shown to the employee after the test when `show_result` = `full`", "maxLength": 5000 }, "media_url": { "type": [ "string", "null" ], "description": "Image URL (upload with `testing.tests.images.upload`)", "maxLength": 1024 } }, "required": [ "type", "body" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "questions" ] }, "example": { "section_id": 42, "questions": [ { "type": "single", "section_id": 42, "body": "string" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "added": 10, "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/questions/{question_id}": { "patch": { "operationId": "testingQuestionsUpdate", "summary": "Update a question", "description": "Partial update. Changing `type` converts the options where possible.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_questions_update", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } }, { "name": "question_id", "in": "path", "required": true, "description": "Question id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "single", "multiple", "true_false", "text", "number", "ordering", "matching", "essay" ], "description": "Question type" }, "section_id": { "type": "integer", "description": "Section (block) id; default — the first section" }, "body": { "type": "string", "description": "Question text", "maxLength": 5000 }, "options": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Answer options by type: `single`/`multiple` — {\"choices\": [{\"text\": \"…\", \"correct\": true}]}; `true_false` — {\"correct\": true}; `text` — {\"answers\": [\"…\"], \"case_sensitive\": false}; `number` — {\"value\": 4, \"tolerance\": 0}; `ordering` — {\"items\": [{\"text\": \"…\"}]} in the correct order; `matching` — {\"pairs\": [{\"left\": \"…\", \"right\": \"…\"}]}; `essay` — {\"min_words\": 50, \"rubric\": \"…\"} (graded manually)." }, "points": { "type": "number", "description": "Points, default 1", "minimum": 0, "maximum": 100 }, "partial_credit": { "type": "boolean", "description": "Partial points for multiple / ordering / matching" }, "is_critical": { "type": "boolean", "description": "A wrong answer fails the whole test" }, "explanation": { "type": [ "string", "null" ], "description": "Shown to the employee after the test when `show_result` = `full`", "maxLength": 5000 }, "media_url": { "type": [ "string", "null" ], "description": "Image URL (upload with `testing.tests.images.upload`)", "maxLength": 1024 } } }, "example": { "type": "single", "section_id": 42, "body": "string", "options": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "testingQuestionsDelete", "summary": "Delete a question", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_questions_delete", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } }, { "name": "question_id", "in": "path", "required": true, "description": "Question id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/questions/{question_id}/duplicate": { "post": { "operationId": "testingQuestionsDuplicate", "summary": "Duplicate a question", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_questions_duplicate", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } }, { "name": "question_id", "in": "path", "required": true, "description": "Question id", "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/sections": { "post": { "operationId": "testingSectionsCreate", "summary": "Add a section", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_sections_create", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 } } }, "example": { "title": "Replace the broken fridge seal" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] } } } }, "required": [ "data" ] }, "example": { "data": { "id": 78, "title": "Hygiene", "pick_count": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/sections/{section_id}": { "patch": { "operationId": "testingSectionsUpdate", "summary": "Update a section", "description": "Rename a section or set `pick_count` — how many random questions of the section each attempt gets (null — all).", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_sections_update", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } }, { "name": "section_id", "in": "path", "required": true, "description": "Section id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "pick_count": { "type": [ "integer", "null" ], "minimum": 1 } } }, "example": { "title": "Replace the broken fridge seal", "pick_count": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 78, "title": "Hygiene", "pick_count": 5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "testingSectionsDelete", "summary": "Delete a section", "description": "Questions of the deleted section move to another section.", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_sections_delete", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } }, { "name": "section_id", "in": "path", "required": true, "description": "Section id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/testing/tests/{id}/status": { "post": { "operationId": "testingTestsStatus", "summary": "Change test status", "description": "Move a test to `draft`, `archived` or `published` (same checks as publish).", "tags": [ "Employee testing" ], "x-mcp-tool": "testing_tests_status", "x-permissions": [ "testing.manage" ], "x-plan-feature": "testing", "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "published", "archived" ] } }, "required": [ "status" ] }, "example": { "status": "draft" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "cover_color": { "type": "string" }, "status": { "type": "string" }, "time_limit_minutes": { "type": "integer" }, "pass_score": { "type": "integer" }, "attempts_limit": { "type": "integer" }, "retry_cooldown_hours": { "type": "integer" }, "shuffle_questions": { "type": "boolean" }, "shuffle_options": { "type": "boolean" }, "navigation": { "type": "string" }, "show_result": { "type": "string" }, "allow_app": { "type": "boolean" }, "allow_web": { "type": "boolean" }, "certificate_enabled": { "type": "boolean" }, "certificate_valid_days": { "type": "integer" }, "public_enabled": { "type": "boolean" }, "public_url": { "type": [ "string", "null" ] }, "strict": { "type": "boolean" }, "proctoring": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "camera": { "type": "boolean" }, "identity_photo": { "type": "boolean" }, "snapshot_interval": { "type": "integer" }, "fullscreen": { "type": "boolean" }, "block_copy": { "type": "boolean" }, "face_detection": { "type": "boolean" }, "max_violations": { "type": [ "string", "null" ] } } }, "questions_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "problems": { "type": "array" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "pick_count": { "type": [ "string", "null" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "section_id": { "type": "integer" }, "type": { "type": "string" }, "body": { "type": "string" }, "media_url": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "correct": { "type": "boolean" } } } } } }, "points": { "type": "integer" }, "partial_credit": { "type": "boolean" }, "is_critical": { "type": "boolean" }, "explanation": { "type": "string" }, "problems": { "type": "array" } } } } } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 58, "uuid": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "title": "Food safety basics", "description": "For new kitchen staff", "category": "Kitchen", "cover_color": "#2563eb", "status": "published", "time_limit_minutes": 20, "pass_score": 80, "attempts_limit": 3, "retry_cooldown_hours": 24, "shuffle_questions": true, "shuffle_options": true, "navigation": "free", "show_result": "answers", "allow_app": true, "allow_web": true, "certificate_enabled": true, "certificate_valid_days": 365, "public_enabled": false, "public_url": null, "strict": false, "proctoring": { "enabled": false, "camera": true, "identity_photo": true, "snapshot_interval": 60, "fullscreen": true, "block_copy": true, "face_detection": true, "max_violations": null }, "questions_count": 15, "updated_at": "2026-10-20T10:00:00+05:00", "url": "https://app.jecheck.io/ui/testing/58/edit", "problems": [], "sections": [ { "id": 77, "title": "Storage", "pick_count": null, "questions": [ { "id": 901, "section_id": 77, "type": "single", "body": "At what temperature must chilled food be stored?", "media_url": null, "options": { "choices": [ { "id": "a1b2c3d4", "text": "0…+4 °C", "correct": true }, { "id": "e5f6g7h8", "text": "+8…+12 °C", "correct": false } ] }, "points": 1, "partial_credit": false, "is_critical": true, "explanation": "SanPiN 2.3.6", "problems": [] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users": { "get": { "operationId": "usersList", "summary": "List employees", "description": "Employees visible to the token (`users.view`: employees of the locations where the permission applies; employees without a location are visible only with the permission for all locations). Active employees by default; use `status` for deleted ones. `email` and `phone` are `null` without `users.contacts` for that employee.", "tags": [ "Employees" ], "x-mcp-tool": "users_list", "x-permissions": [ "users.view" ], "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting from 1", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "description": "Employment status", "schema": { "type": "string", "enum": [ "active", "deleted", "all" ], "default": "active" } }, { "name": "location_ids[]", "in": "query", "description": "Only employees attached to these locations (primary or additional)", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "position_id", "in": "query", "description": "Only employees with this position", "schema": { "type": "integer" } }, { "name": "team_id", "in": "query", "description": "Only members of this team", "schema": { "type": "integer" } }, { "name": "is_admin", "in": "query", "description": "Only administrators (`true`) or only non-administrators (`false`)", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search in first name, last name and email", "schema": { "type": "string", "maxLength": 200 } }, { "name": "updated_since", "in": "query", "description": "Only employees changed after this moment — use for incremental sync", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "name", "created_desc", "updated_desc" ], "default": "name" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "locale": { "type": "string" }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "example": { "data": [ { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "first_name": "Aigerim", "last_name": "Sadykova", "name": "Aigerim Sadykova", "email": "aigerim@coffeelab.kz", "phone": "+77011234567", "position": { "id": 5, "name": "Barista" }, "status": "active", "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home", "is_manager": false } ], "teams": [ { "id": 4, "name": "Kitchen", "is_head": false } ], "locale": "ru", "last_activity_at": "2026-11-03T09:40:00+05:00", "created_at": "2025-02-11T10:00:00+05:00", "updated_at": "2026-10-28T16:12:00+05:00", "deleted_at": null, "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "usersCreate", "summary": "Create an employee", "description": "Adds an employee with access to the mobile app and the web cabinet. An invitation with a generated password is emailed to the employee. Email is the login and must be unique across jeCheck. Attach the employee to locations with `locations_staff_set`; administrator rights and app-only access are set with `access_users_account_update`.", "tags": [ "Employees" ], "x-mcp-tool": "users_create", "x-permissions": [ "users.create" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name", "minLength": 2, "maxLength": 255 }, "last_name": { "type": "string", "description": "Last name", "minLength": 2, "maxLength": 255 }, "email": { "type": "string", "description": "Email — the login", "maxLength": 255 }, "position_id": { "type": [ "integer", "null" ], "description": "Position id (see `GET /users/positions`)" } }, "required": [ "first_name", "last_name", "email" ] }, "example": { "first_name": "string", "last_name": "string", "email": "anna@example.com", "position_id": 42 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "locale": { "type": "string" }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "can": { "type": "object", "properties": { "edit": { "type": "boolean" }, "see_contacts": { "type": "boolean" }, "manage_login": { "type": "boolean" }, "deactivate": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "first_name": "Aigerim", "last_name": "Sadykova", "name": "Aigerim Sadykova", "email": "aigerim@coffeelab.kz", "phone": "+77011234567", "position": { "id": 5, "name": "Barista" }, "status": "active", "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home", "is_manager": false } ], "teams": [ { "id": 4, "name": "Kitchen", "is_head": false } ], "locale": "ru", "last_activity_at": "2026-11-03T09:40:00+05:00", "created_at": "2025-02-11T10:00:00+05:00", "updated_at": "2026-10-28T16:12:00+05:00", "deleted_at": null, "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "can": { "edit": true, "see_contacts": true, "manage_login": true, "deactivate": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/positions": { "get": { "operationId": "usersPositionsList", "summary": "List positions", "description": "The positions directory with the number of active employees in each. Positions are used to route corrective tasks, assign tests, instructions and HACCP logs.", "tags": [ "Employees" ], "x-mcp-tool": "users_positions_list", "x-permissions": [ "users.view", "users.positions" ], "x-scope": "read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "employees_count": { "type": "integer" } } } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 5, "name": "Barista", "employees_count": 23 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "usersPositionsCreate", "summary": "Create a position", "tags": [ "Employees" ], "x-mcp-tool": "users_positions_create", "x-permissions": [ "users.positions" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Position name", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "employees_count": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 6, "name": "Shift lead", "employees_count": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/positions/{id}": { "patch": { "operationId": "usersPositionsUpdate", "summary": "Rename a position", "tags": [ "Employees" ], "x-mcp-tool": "users_positions_update", "x-permissions": [ "users.positions" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Position id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name", "minLength": 1, "maxLength": 120 } }, "required": [ "name" ] }, "example": { "name": "Replace the broken fridge seal" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "employees_count": { "type": "integer" } } } }, "required": [ "data" ] }, "example": { "data": { "id": 6, "name": "Shift supervisor", "employees_count": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "usersPositionsDelete", "summary": "Delete a position", "description": "Employees with this position are left without a position.", "tags": [ "Employees" ], "x-mcp-tool": "users_positions_delete", "x-permissions": [ "users.positions" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Position id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/{id}": { "get": { "operationId": "usersGet", "summary": "Retrieve an employee", "description": "Employee card: position, locations (primary/additional, manager flag), teams, administrator and web-cabinet flags, last activity, and what the token may do with this employee (`can`).", "tags": [ "Employees" ], "x-mcp-tool": "users_get", "x-permissions": [ "users.view" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "locale": { "type": "string" }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "can": { "type": "object", "properties": { "edit": { "type": "boolean" }, "see_contacts": { "type": "boolean" }, "manage_login": { "type": "boolean" }, "deactivate": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "first_name": "Aigerim", "last_name": "Sadykova", "name": "Aigerim Sadykova", "email": "aigerim@coffeelab.kz", "phone": "+77011234567", "position": { "id": 5, "name": "Barista" }, "status": "active", "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home", "is_manager": false } ], "teams": [ { "id": 4, "name": "Kitchen", "is_head": false } ], "locale": "ru", "last_activity_at": "2026-11-03T09:40:00+05:00", "created_at": "2025-02-11T10:00:00+05:00", "updated_at": "2026-10-28T16:12:00+05:00", "deleted_at": null, "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "can": { "edit": true, "see_contacts": true, "manage_login": true, "deactivate": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "usersUpdate", "summary": "Update an employee", "description": "Partial update of name, position and email. Changing the email (login) additionally requires `users.access` and `users.contacts` for the employee; the employee is notified at the new address. Only an administrator can change the login of an administrator.", "tags": [ "Employees" ], "x-mcp-tool": "users_update", "x-permissions": [ "users.edit" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name", "minLength": 2, "maxLength": 255 }, "last_name": { "type": "string", "description": "Last name", "minLength": 2, "maxLength": 255 }, "email": { "type": "string", "description": "New email (login)", "maxLength": 255 }, "position_id": { "type": [ "integer", "null" ], "description": "Position id; `null` clears the position" } } }, "example": { "first_name": "string", "last_name": "string", "email": "anna@example.com", "position_id": 42 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "locale": { "type": "string" }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "can": { "type": "object", "properties": { "edit": { "type": "boolean" }, "see_contacts": { "type": "boolean" }, "manage_login": { "type": "boolean" }, "deactivate": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "first_name": "Aigerim", "last_name": "Sadykova", "name": "Aigerim Sadykova", "email": "aigerim@coffeelab.kz", "phone": "+77011234567", "position": { "id": 5, "name": "Barista" }, "status": "active", "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home", "is_manager": false } ], "teams": [ { "id": 4, "name": "Kitchen", "is_head": false } ], "locale": "ru", "last_activity_at": "2026-11-03T09:40:00+05:00", "created_at": "2025-02-11T10:00:00+05:00", "updated_at": "2026-10-28T16:12:00+05:00", "deleted_at": null, "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "can": { "edit": true, "see_contacts": true, "manage_login": true, "deactivate": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/{id}/deactivate": { "post": { "operationId": "usersDeactivate", "summary": "Deactivate an employee", "description": "Deletes the employee the same way as the web app: sign-in to the app and the cabinet is blocked immediately, mobile tokens are revoked, history stays. You cannot deactivate yourself or the company owner; only an administrator can deactivate an administrator.", "tags": [ "Employees" ], "x-mcp-tool": "users_deactivate", "x-permissions": [ "users.delete" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "locale": { "type": "string" }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "can": { "type": "object", "properties": { "edit": { "type": "boolean" }, "see_contacts": { "type": "boolean" }, "manage_login": { "type": "boolean" }, "deactivate": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "first_name": "Aigerim", "last_name": "Sadykova", "name": "Aigerim Sadykova", "email": "aigerim@coffeelab.kz", "phone": "+77011234567", "position": { "id": 5, "name": "Barista" }, "status": "deleted", "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home", "is_manager": false } ], "teams": [ { "id": 4, "name": "Kitchen", "is_head": false } ], "locale": "ru", "last_activity_at": "2026-11-03T09:40:00+05:00", "created_at": "2025-02-11T10:00:00+05:00", "updated_at": "2026-10-28T16:12:00+05:00", "deleted_at": "2026-11-03T12:00:00+05:00", "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "can": { "edit": true, "see_contacts": true, "manage_login": true, "deactivate": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/{id}/invite": { "post": { "operationId": "usersInvite", "summary": "Resend the invitation", "description": "Emails the invitation again with a sign-in link and a new password (the old password stops working).", "tags": [ "Employees" ], "x-mcp-tool": "users_invite", "x-permissions": [ "users.access" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent_to": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "sent_to": "aigerim@coffeelab.kz" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/{id}/reset-password": { "post": { "operationId": "usersResetPassword", "summary": "Reset password by email", "description": "Generates a new password and emails it to the employee. Existing mobile sessions are signed out.", "tags": [ "Employees" ], "x-mcp-tool": "users_reset_password", "x-permissions": [ "users.access" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent_to": { "type": "string" } } } }, "required": [ "data" ] }, "example": { "data": { "sent_to": "aigerim@coffeelab.kz" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/{id}/restore": { "post": { "operationId": "usersRestore", "summary": "Restore a deactivated employee", "tags": [ "Employees" ], "x-mcp-tool": "users_restore", "x-permissions": [ "users.delete" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "position": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "status": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "web_access": { "type": "boolean" }, "works_anywhere": { "type": "boolean" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "is_manager": { "type": "boolean" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_head": { "type": "boolean" } } } }, "locale": { "type": "string" }, "last_activity_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "can": { "type": "object", "properties": { "edit": { "type": "boolean" }, "see_contacts": { "type": "boolean" }, "manage_login": { "type": "boolean" }, "deactivate": { "type": "boolean" } } } } } }, "required": [ "data" ] }, "example": { "data": { "id": 311, "uuid": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "first_name": "Aigerim", "last_name": "Sadykova", "name": "Aigerim Sadykova", "email": "aigerim@coffeelab.kz", "phone": "+77011234567", "position": { "id": 5, "name": "Barista" }, "status": "active", "is_admin": false, "is_owner": false, "web_access": true, "works_anywhere": false, "locations": [ { "id": 12, "name": "Abay Ave", "kind": "home", "is_manager": false } ], "teams": [ { "id": 4, "name": "Kitchen", "is_head": false } ], "locale": "ru", "last_activity_at": "2026-11-03T09:40:00+05:00", "created_at": "2025-02-11T10:00:00+05:00", "updated_at": "2026-10-28T16:12:00+05:00", "deleted_at": null, "url": "https://app.jecheck.io/ui/users/1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b", "can": { "edit": true, "see_contacts": true, "manage_login": true, "deactivate": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/users/{id}/temporary-password": { "post": { "operationId": "usersTemporaryPassword", "summary": "Issue a temporary password", "description": "For an employee without access to email: returns a one-time password to hand over in person. It is not emailed or stored in clear text; the employee must set their own password at the first sign-in. Written to the access log.", "tags": [ "Employees" ], "x-mcp-tool": "users_temporary_password", "x-permissions": [ "users.access" ], "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "password": { "type": "string" }, "must_change": { "type": "boolean" } } } }, "required": [ "data" ] }, "example": { "data": { "password": "Kq7m-Xr4t", "must_change": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Company key `jck_live_…`, personal token `jck_pat_…` or OAuth token `jck_oat_…`" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code" }, "message": { "type": "string", "description": "Human-readable message (English)" }, "fields": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Validation errors by field (422 only)" } } } } }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } } }, "responses": { "Unauthorized": { "description": "Missing, invalid, revoked or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or revoked token" } } } } }, "Forbidden": { "description": "No permission, read-only token or the plan does not include the feature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Missing permission: tasks.view_all" } } } } }, "NotFound": { "description": "The resource does not exist or is not visible to the token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "ValidationFailed": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "The given data was invalid", "fields": { "title": [ "The title field is required." ] } } } } } }, "RateLimited": { "description": "Too many requests; retry after `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests" } } } } } } } }