{ "schemes": [], "swagger": "2.0", "info": { "description": "API for collaborative shift planning and management. This API allows you to create shift plans, manage shift types, create and manage shifts, and handle participant sign-ups.", "title": "Shifts API", "contact": { "name": "API Support", "url": "https://github.com/72nd/shifts" }, "version": "1.0" }, "host": "localhost:8080", "basePath": "/api", "paths": { "/plans": { "post": { "description": "Creates a new shift plan with the provided details. Returns the plan token, URL, and admin password.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Plans" ], "summary": "Create a new shift plan", "parameters": [ { "description": "Shift plan details", "name": "plan", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateShiftPlanRequest" } } ], "responses": { "200": { "description": "Created plan with token, URL, and password", "schema": { "$ref": "#/definitions/CreateShiftPlanResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}": { "get": { "description": "Retrieves the details of a shift plan by its token", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Plans" ], "summary": "Get shift plan details", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "Shift plan details", "schema": { "$ref": "#/definitions/ShiftPlanResponse" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } }, "put": { "security": [ { "AdminToken": [] } ], "description": "Updates the details of an existing shift plan. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Plans" ], "summary": "Update shift plan", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Updated plan details", "name": "plan", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ShiftPlanUpdateRequest" } } ], "responses": { "200": { "description": "Updated shift plan", "schema": { "$ref": "#/definitions/ShiftPlanResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "AdminToken": [] } ], "description": "Deletes a shift plan and all its associated data (shifts, types, participants). Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Plans" ], "summary": "Delete shift plan", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true } ], "responses": { "204": { "description": "Plan deleted successfully" }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/export": { "get": { "security": [ { "AdminToken": [] } ], "description": "Exports a shift plan in various formats (JSON, PDF, etc.) with optional filtering. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json", "application/pdf", "image/png" ], "tags": [ "Plans" ], "summary": "Export shift plan", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "type": "string", "default": "json", "description": "Export format (json, pdf, timetable, report, poster)", "name": "format", "in": "query" }, { "type": "string", "description": "Filter by day (YYYY-MM-DD)", "name": "day", "in": "query" }, { "type": "string", "description": "Filter by status (past, current, future)", "name": "status", "in": "query" }, { "type": "string", "description": "Search query", "name": "search", "in": "query" }, { "type": "string", "description": "Comma-separated list of type IDs to filter", "name": "type_ids", "in": "query" } ], "responses": { "200": { "description": "Exported file", "schema": { "type": "file" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/shifts": { "post": { "security": [ { "AdminToken": [] } ], "description": "Creates a new shift for a shift type. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Create shift", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Shift details", "name": "shift", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ShiftCreateRequest" } } ], "responses": { "200": { "description": "Created shift", "schema": { "$ref": "#/definitions/ShiftResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan or type not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/shifts/batch": { "put": { "security": [ { "AdminToken": [] } ], "description": "Updates multiple shifts in a single transaction. All updates are validated first, then applied. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Batch update shifts", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Batch update request with array of shift updates", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BatchShiftUpdateRequest" } } ], "responses": { "200": { "description": "Batch update result with updated shift IDs and any failures", "schema": { "$ref": "#/definitions/BatchUpdateResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } }, "post": { "security": [ { "AdminToken": [] } ], "description": "Creates multiple shifts in a single transaction. All shifts are validated first, then created. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Batch create shifts", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Batch create request with array of shifts", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BatchShiftCreateRequest" } } ], "responses": { "200": { "description": "Batch create result with created shifts and any failures", "schema": { "$ref": "#/definitions/BatchCreateResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "AdminToken": [] } ], "description": "Deletes multiple shifts in a single transaction. All shift IDs are validated first, then deleted. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Batch delete shifts", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Batch delete request with array of shift IDs", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BatchShiftDeleteRequest" } } ], "responses": { "200": { "description": "Batch delete result with deleted shift IDs and any failures", "schema": { "$ref": "#/definitions/BatchDeleteResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/shifts/{shiftId}": { "put": { "security": [ { "AdminToken": [] } ], "description": "Updates an existing shift. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Update shift", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift ID", "name": "shiftId", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Updated shift details", "name": "shift", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ShiftUpdateRequest" } } ], "responses": { "204": { "description": "Shift updated successfully" }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan or shift not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "AdminToken": [] } ], "description": "Deletes a shift and all its participants. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Delete shift", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift ID", "name": "shiftId", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true } ], "responses": { "204": { "description": "Shift deleted successfully" }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan or shift not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/shifts/{shiftId}/lock": { "post": { "security": [ { "AdminToken": [] } ], "description": "Locks a shift, preventing non-admin users from joining or leaving. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Lock shift", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift ID", "name": "shiftId", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true } ], "responses": { "204": { "description": "Shift locked successfully" }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan or shift not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/shifts/{shiftId}/participants": { "post": { "description": "Adds a participant to a shift. Admin token required if shift is locked.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Participants" ], "summary": "Add participant to shift", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift ID", "name": "shiftId", "in": "path", "required": true }, { "type": "string", "description": "Admin token (required if shift is locked)", "name": "X-Admin-Token", "in": "header" }, { "description": "Participant name", "name": "data", "in": "body", "required": true, "schema": { "$ref": "#/definitions/AddParticipantRequest" } } ], "responses": { "200": { "description": "Added participant", "schema": { "$ref": "#/definitions/ParticipantResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "403": { "description": "Shift is locked - admin access required", "schema": { "type": "string" } }, "404": { "description": "Plan or shift not found", "schema": { "type": "string" } }, "409": { "description": "Shift full or duplicate name", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/shifts/{shiftId}/participants/{participantId}": { "delete": { "description": "Removes a participant from a shift. Admin token required if shift is locked.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Participants" ], "summary": "Remove participant from shift", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift ID", "name": "shiftId", "in": "path", "required": true }, { "type": "integer", "description": "Participant ID", "name": "participantId", "in": "path", "required": true }, { "type": "string", "description": "Admin token (required if shift is locked)", "name": "X-Admin-Token", "in": "header" } ], "responses": { "204": { "description": "Participant removed successfully" }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "403": { "description": "Shift is locked - admin access required", "schema": { "type": "string" } }, "404": { "description": "Plan, shift, or participant not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/shifts/{shiftId}/unlock": { "post": { "security": [ { "AdminToken": [] } ], "description": "Unlocks a shift, allowing all users to join or leave. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Shifts" ], "summary": "Unlock shift", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift ID", "name": "shiftId", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true } ], "responses": { "204": { "description": "Shift unlocked successfully" }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan or shift not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/stats": { "get": { "description": "Retrieves comprehensive statistics for a shift plan including overview, helper stats, type stats, and daily stats", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Plans" ], "summary": "Get shift plan statistics", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "Plan statistics", "schema": { "$ref": "#/definitions/StatsResponse" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/types": { "get": { "description": "Retrieves all shift types for a plan, including their associated shifts", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Types" ], "summary": "Get shift types", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "List of shift types", "schema": { "type": "array", "items": { "$ref": "#/definitions/ShiftTypeResponse" } } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } }, "post": { "security": [ { "AdminToken": [] } ], "description": "Creates a new shift type for a plan. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Types" ], "summary": "Create shift type", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Shift type details", "name": "shiftType", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateShiftTypeRequest" } } ], "responses": { "200": { "description": "Created shift type", "schema": { "$ref": "#/definitions/ShiftTypeResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/types/order": { "put": { "security": [ { "AdminToken": [] } ], "description": "Updates the display order of shift types for a plan", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Types" ], "summary": "Update shift type order", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Type IDs in desired order", "name": "data", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ShiftTypeOrderRequest" } } ], "responses": { "200": { "description": "Order updated successfully", "schema": { "type": "string" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/types/{typeId}": { "put": { "security": [ { "AdminToken": [] } ], "description": "Updates an existing shift type. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Types" ], "summary": "Update shift type", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift type ID", "name": "typeId", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true }, { "description": "Updated shift type details", "name": "shiftType", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ShiftTypeUpdateRequest" } } ], "responses": { "200": { "description": "Shift type updated successfully" }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan or type not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } }, "delete": { "security": [ { "AdminToken": [] } ], "description": "Deletes a shift type and all its associated shifts. Requires admin authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Types" ], "summary": "Delete shift type", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "type": "integer", "description": "Shift type ID", "name": "typeId", "in": "path", "required": true }, { "type": "string", "description": "Admin token", "name": "X-Admin-Token", "in": "header", "required": true } ], "responses": { "200": { "description": "Shift type deleted successfully" }, "401": { "description": "Unauthorized", "schema": { "type": "string" } }, "404": { "description": "Plan or type not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } }, "/plans/{token}/verify-admin": { "post": { "description": "Verifies the admin password for a shift plan and returns the token if valid", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Plans" ], "summary": "Verify admin password", "parameters": [ { "type": "string", "description": "Plan token", "name": "token", "in": "path", "required": true }, { "description": "Password to verify", "name": "data", "in": "body", "required": true, "schema": { "$ref": "#/definitions/VerifyAdminRequest" } } ], "responses": { "200": { "description": "Token if password is valid", "schema": { "$ref": "#/definitions/VerifyAdminResponse" } }, "400": { "description": "Invalid input", "schema": { "type": "string" } }, "401": { "description": "Invalid password", "schema": { "type": "string" } }, "404": { "description": "Plan not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "string" } } } } } }, "definitions": { "AddParticipantRequest": { "description": "Request body for adding a participant to a shift", "type": "object", "required": [ "name" ], "properties": { "name": { "description": "Name of the participant to add", "type": "string", "maxLength": 100, "minLength": 1, "example": "John Doe" } } }, "BatchCreateResponse": { "description": "Response body for batch shift creation", "type": "object", "properties": { "created": { "description": "Array of successfully created shifts", "type": "array", "items": { "$ref": "#/definitions/ShiftResponse" } }, "failed": { "description": "Array of items that failed to create (only present if there were failures)", "type": "array", "items": { "$ref": "#/definitions/github_com_72nd_shifts_internal_model.BatchItemError" } } } }, "BatchDeleteResponse": { "description": "Response body for batch shift deletion", "type": "object", "properties": { "deleted": { "description": "Array of IDs of successfully deleted shifts", "type": "array", "items": { "type": "integer" } }, "failed": { "description": "Array of items that failed to delete (only present if there were failures)", "type": "array", "items": { "$ref": "#/definitions/github_com_72nd_shifts_internal_model.BatchItemError" } } } }, "BatchShiftCreateRequest": { "description": "Request body for creating multiple shifts in a single operation", "type": "object", "required": [ "shifts" ], "properties": { "shifts": { "description": "Array of shifts to create (max 100 items)", "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/ShiftCreateRequest" } } } }, "BatchShiftDeleteRequest": { "description": "Request body for deleting multiple shifts in a single operation", "type": "object", "required": [ "shift_ids" ], "properties": { "shift_ids": { "description": "Array of shift IDs to delete (max 100 items)", "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "BatchShiftUpdateItem": { "description": "Single shift update item within a batch update request. Only include fields you want to update (partial updates supported).", "type": "object", "required": [ "id" ], "properties": { "comment_de": { "description": "Optional comment in German (supports Markdown). Use null to clear existing comment.", "type": "string", "example": "Bitte pünktlich erscheinen" }, "comment_en": { "description": "Optional comment in English (supports Markdown). Use null to clear existing comment.", "type": "string", "example": "Please arrive on time" }, "duration": { "description": "Duration of the shift in minutes (optional, only set if you want to change it)", "type": "integer", "example": 120 }, "id": { "description": "ID of the shift to update", "type": "integer", "minimum": 1, "example": 42 }, "required": { "description": "Number of required participants, -1 for unlimited (optional, only set if you want to change it)", "type": "integer", "example": 3 }, "start_time": { "description": "Start time of the shift in RFC3339 format (optional, only set if you want to change it)", "type": "string", "example": "2024-12-20T09:00:00Z" }, "type_id": { "description": "ID of the shift type this shift belongs to (optional, only set if you want to change it)", "type": "integer", "example": 1 } } }, "BatchShiftUpdateRequest": { "description": "Request body for updating multiple shifts in a single operation", "type": "object", "required": [ "shifts" ], "properties": { "shifts": { "description": "Array of shift updates (max 100 items)", "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/BatchShiftUpdateItem" } } } }, "BatchUpdateResponse": { "description": "Response body for batch shift update", "type": "object", "properties": { "failed": { "description": "Array of items that failed to update (only present if there were failures)", "type": "array", "items": { "$ref": "#/definitions/github_com_72nd_shifts_internal_model.BatchItemError" } }, "updated": { "description": "Array of IDs of successfully updated shifts", "type": "array", "items": { "type": "integer" } } } }, "CreateShiftPlanRequest": { "description": "Request body for creating a new shift plan", "type": "object", "required": [ "end_date", "start_date", "title_en" ], "properties": { "collaborative_mode": { "description": "Whether participants can see each other's names", "type": "boolean", "example": false }, "day_boundary_time": { "description": "Time when a new day starts (HH:MM format, e.g., \"06:00\" for 6 AM)", "type": "string", "example": "00:00" }, "description_de": { "description": "Description in German (supports Markdown)", "type": "string", "example": "Beschreibung des Events" }, "description_en": { "description": "Description in English (supports Markdown)", "type": "string", "example": "Event description" }, "end_date": { "description": "End date of the plan", "type": "string", "example": "2024-12-22T00:00:00Z" }, "is_multilingual": { "description": "Whether the plan supports multiple languages", "type": "boolean", "example": true }, "start_date": { "description": "Start date of the plan", "type": "string", "example": "2024-12-20T00:00:00Z" }, "title_de": { "description": "Title in German (required if multilingual)", "type": "string", "example": "Sommerfest 2024" }, "title_en": { "description": "Title in English", "type": "string", "maxLength": 150, "example": "Summer Festival 2024" } } }, "CreateShiftPlanResponse": { "description": "Response body for successful shift plan creation", "type": "object", "properties": { "password": { "description": "Admin password for managing the plan (only returned on creation)", "type": "string", "example": "secretpassword123" }, "token": { "description": "Public token for accessing the plan", "type": "string", "example": "abc123def456" }, "url": { "description": "URL path to access the plan", "type": "string", "example": "/plans/abc123def456" } } }, "CreateShiftTypeRequest": { "description": "Request body for creating a new shift type", "type": "object", "required": [ "title_de", "title_en" ], "properties": { "description_de": { "description": "Description in German (supports Markdown)", "type": "string", "example": "Hilfe in der Küche" }, "description_en": { "description": "Description in English (supports Markdown)", "type": "string", "example": "Help in the kitchen" }, "location_de": { "description": "Location in German", "type": "string", "example": "Hauptküche" }, "location_en": { "description": "Location in English", "type": "string", "example": "Main Kitchen" }, "password": { "description": "Optional password to restrict participation (if set, participants must provide this password)", "type": "string", "example": "secret123" }, "title_de": { "description": "Title in German", "type": "string", "maxLength": 150, "example": "Küchendienst" }, "title_en": { "description": "Title in English", "type": "string", "maxLength": 150, "example": "Kitchen Duty" } } }, "DailyStatsResponse": { "description": "Statistics for a single day", "type": "object", "properties": { "date": { "description": "Date", "type": "string", "example": "2024-12-20T00:00:00Z" }, "filled_hours": { "description": "Filled hours for this day", "type": "number", "example": 56 }, "open_positions": { "description": "Number of open positions", "type": "integer", "example": 2 }, "percent_filled": { "description": "Percentage filled", "type": "integer", "example": 93 }, "total_filled": { "description": "Total filled positions for this day", "type": "integer", "example": 28 }, "total_hours": { "description": "Total hours for this day", "type": "number", "example": 60 }, "total_required": { "description": "Total required participants for this day", "type": "integer", "example": 30 }, "total_shifts": { "description": "Total number of shifts on this day", "type": "integer", "example": 10 } } }, "HelperStatsResponse": { "description": "Statistics for a single helper/participant", "type": "object", "properties": { "future_hours": { "description": "Hours in future shifts", "type": "number", "example": 14.5 }, "name": { "description": "Name of the helper", "type": "string", "example": "John Doe" }, "past_hours": { "description": "Hours in past shifts", "type": "number", "example": 10 }, "shift_details": { "description": "Detailed breakdown of shifts for this helper", "type": "array", "items": { "$ref": "#/definitions/ShiftDetailResponse" } }, "total_hours": { "description": "Total hours for this helper", "type": "number", "example": 24.5 }, "total_shifts": { "description": "Total number of shifts this helper is assigned to", "type": "integer", "example": 12 } } }, "ParticipantResponse": { "description": "Participant data returned in API responses", "type": "object", "properties": { "id": { "description": "Unique identifier of the participant", "type": "integer", "example": 123 }, "name": { "description": "Name of the participant", "type": "string", "example": "John Doe" } } }, "ShiftCreateRequest": { "description": "Request body for creating a single shift", "type": "object", "required": [ "duration", "required", "start_time", "type_id" ], "properties": { "comment_de": { "description": "Optional comment in German (supports Markdown)", "type": "string", "example": "Bitte pünktlich erscheinen" }, "comment_en": { "description": "Optional comment in English (supports Markdown)", "type": "string", "example": "Please arrive on time" }, "duration": { "description": "Duration of the shift in minutes", "type": "integer", "minimum": 1, "example": 120 }, "required": { "description": "Number of required participants (-1 for unlimited)", "type": "integer", "minimum": -1, "example": 3 }, "start_time": { "description": "Start time of the shift in RFC3339 format", "type": "string", "example": "2024-12-20T09:00:00Z" }, "type_id": { "description": "ID of the shift type this shift belongs to", "type": "integer", "minimum": 1, "example": 1 } } }, "ShiftDetailResponse": { "description": "Detailed information about a single shift for statistics", "type": "object", "properties": { "date": { "description": "Date of the shift", "type": "string", "example": "2024-12-20T00:00:00Z" }, "duration": { "description": "Duration in hours", "type": "number", "example": 2 }, "status": { "description": "Status of the shift (past, current, future)", "type": "string", "example": "future" }, "type_id": { "description": "ID of the shift type", "type": "integer", "example": 1 }, "type_name": { "description": "Name of the shift type", "type": "string", "example": "Kitchen Duty" } } }, "ShiftPlanResponse": { "description": "Shift plan data returned in API responses", "type": "object", "properties": { "collaborative_mode": { "description": "Whether participants can see each other's names", "type": "boolean", "example": false }, "created_at": { "description": "Timestamp when the plan was created", "type": "string", "example": "2024-12-01T10:00:00Z" }, "day_boundary_time": { "description": "Time when a new day starts (HH:MM format)", "type": "string", "example": "00:00" }, "description_de": { "description": "Description in German (raw Markdown)", "type": "string", "example": "Beschreibung des Events" }, "description_de_html": { "description": "Rendered HTML of German description (only present if description_de is set)", "type": "string" }, "description_en": { "description": "Description in English (raw Markdown)", "type": "string", "example": "Event description" }, "description_en_html": { "description": "Rendered HTML of English description (only present if description_en is set)", "type": "string" }, "end_date": { "description": "End date of the plan", "type": "string", "example": "2024-12-22T00:00:00Z" }, "id": { "description": "Unique identifier of the shift plan", "type": "integer", "example": 42 }, "is_multilingual": { "description": "Whether the plan supports multiple languages", "type": "boolean", "example": true }, "start_date": { "description": "Start date of the plan", "type": "string", "example": "2024-12-20T00:00:00Z" }, "title_de": { "description": "Title in German", "type": "string", "example": "Sommerfest 2024" }, "title_en": { "description": "Title in English", "type": "string", "example": "Summer Festival 2024" }, "token": { "description": "Public token for accessing the plan", "type": "string", "example": "abc123def456" } } }, "ShiftPlanUpdateRequest": { "description": "Request body for updating a shift plan", "type": "object", "required": [ "end_date", "start_date", "title_en" ], "properties": { "collaborative_mode": { "description": "Whether participants can see each other's names", "type": "boolean", "example": false }, "day_boundary_time": { "description": "Time when a new day starts (HH:MM format, e.g., \"06:00\" for 6 AM)", "type": "string", "example": "00:00" }, "description_de": { "description": "Description in German (supports Markdown)", "type": "string", "example": "Beschreibung des Events" }, "description_en": { "description": "Description in English (supports Markdown)", "type": "string", "example": "Event description" }, "end_date": { "description": "End date of the plan", "type": "string", "example": "2024-12-22T00:00:00Z" }, "is_multilingual": { "description": "Whether the plan supports multiple languages", "type": "boolean", "example": true }, "start_date": { "description": "Start date of the plan", "type": "string", "example": "2024-12-20T00:00:00Z" }, "title_de": { "description": "Title in German (required if multilingual)", "type": "string", "example": "Sommerfest 2024" }, "title_en": { "description": "Title in English", "type": "string", "maxLength": 150, "example": "Summer Festival 2024" } } }, "ShiftResponse": { "description": "Shift data returned in API responses", "type": "object", "properties": { "comment_de": { "description": "Comment in German (raw Markdown)", "type": "string", "example": "Bitte pünktlich erscheinen" }, "comment_de_html": { "description": "Rendered HTML of German comment (only present if comment_de is set)", "type": "string" }, "comment_en": { "description": "Comment in English (raw Markdown)", "type": "string", "example": "Please arrive on time" }, "comment_en_html": { "description": "Rendered HTML of English comment (only present if comment_en is set)", "type": "string" }, "duration": { "description": "Duration of the shift in minutes", "type": "integer", "example": 120 }, "id": { "description": "Unique identifier of the shift", "type": "integer", "example": 42 }, "is_locked": { "description": "Whether the shift is locked for participant changes", "type": "boolean", "example": false }, "participants": { "description": "List of participants (only present when requested)", "type": "array", "items": { "$ref": "#/definitions/ParticipantResponse" } }, "required": { "description": "Number of required participants (-1 for unlimited)", "type": "integer", "example": 3 }, "start_time": { "description": "Start time of the shift", "type": "string", "example": "2024-12-20T09:00:00Z" }, "type_id": { "description": "ID of the shift type this shift belongs to", "type": "integer", "example": 1 } } }, "ShiftTypeOrderRequest": { "description": "Request body for updating the display order of shift types", "type": "object", "required": [ "type_ids" ], "properties": { "type_ids": { "description": "Array of type IDs in the desired display order", "type": "array", "items": { "type": "integer" } } } }, "ShiftTypeResponse": { "description": "Shift type data returned in API responses", "type": "object", "properties": { "description_de": { "description": "Description in German (raw Markdown)", "type": "string", "example": "Hilfe in der Küche" }, "description_de_html": { "description": "Rendered HTML of German description (only present if description_de is set)", "type": "string" }, "description_en": { "description": "Description in English (raw Markdown)", "type": "string", "example": "Help in the kitchen" }, "description_en_html": { "description": "Rendered HTML of English description (only present if description_en is set)", "type": "string" }, "id": { "description": "Unique identifier of the shift type", "type": "integer", "example": 1 }, "location_de": { "description": "Location in German", "type": "string", "example": "Hauptküche" }, "location_en": { "description": "Location in English", "type": "string", "example": "Main Kitchen" }, "plan_id": { "description": "ID of the shift plan this type belongs to", "type": "integer", "example": 42 }, "shifts": { "description": "Array of shifts belonging to this type (only present when requested)", "type": "array", "items": { "$ref": "#/definitions/ShiftResponse" } }, "sort_order": { "description": "Display order of this type", "type": "integer", "example": 1 }, "title_de": { "description": "Title in German", "type": "string", "example": "Küchendienst" }, "title_en": { "description": "Title in English", "type": "string", "example": "Kitchen Duty" } } }, "ShiftTypeUpdateRequest": { "description": "Request body for updating a shift type", "type": "object", "required": [ "title_en" ], "properties": { "description_de": { "description": "Description in German (supports Markdown)", "type": "string", "example": "Hilfe in der Küche" }, "description_en": { "description": "Description in English (supports Markdown)", "type": "string", "example": "Help in the kitchen" }, "location_de": { "description": "Location in German", "type": "string", "example": "Hauptküche" }, "location_en": { "description": "Location in English", "type": "string", "example": "Main Kitchen" }, "title_de": { "description": "Title in German", "type": "string", "maxLength": 150, "example": "Küchendienst" }, "title_en": { "description": "Title in English", "type": "string", "maxLength": 150, "example": "Kitchen Duty" } } }, "ShiftUpdateRequest": { "description": "Request body for updating a single shift", "type": "object", "required": [ "duration", "required", "start_time", "type_id" ], "properties": { "comment_de": { "description": "Optional comment in German (supports Markdown)", "type": "string", "example": "Bitte pünktlich erscheinen" }, "comment_en": { "description": "Optional comment in English (supports Markdown)", "type": "string", "example": "Please arrive on time" }, "duration": { "description": "Duration of the shift in minutes", "type": "integer", "minimum": 1, "example": 120 }, "required": { "description": "Number of required participants (-1 for unlimited)", "type": "integer", "minimum": -1, "example": 3 }, "start_time": { "description": "Start time of the shift in RFC3339 format", "type": "string", "example": "2024-12-20T09:00:00Z" }, "type_id": { "description": "ID of the shift type this shift belongs to", "type": "integer", "minimum": 1, "example": 1 } } }, "StatsOverviewResponse": { "description": "Overview statistics for a shift plan", "type": "object", "properties": { "avg_hours_per_helper": { "description": "Average hours per helper", "type": "number", "example": 22.82 }, "filled_hours": { "description": "Total filled hours (filled positions * duration)", "type": "number", "example": 570.5 }, "future_hours": { "description": "Hours in future shifts", "type": "number", "example": 370.5 }, "open_shifts": { "description": "Number of shifts that still have open positions", "type": "integer", "example": 15 }, "past_hours": { "description": "Hours in past shifts", "type": "number", "example": 200 }, "total_filled": { "description": "Total number of filled positions", "type": "integer", "example": 285 }, "total_hours": { "description": "Total hours of all shifts (required positions * duration)", "type": "number", "example": 600.5 }, "total_required": { "description": "Total number of required participants across all shifts", "type": "integer", "example": 300 }, "total_shifts": { "description": "Total number of shifts in the plan", "type": "integer", "example": 100 }, "unique_helpers": { "description": "Number of unique helpers/participants", "type": "integer", "example": 25 } } }, "StatsResponse": { "description": "Complete statistics data for a shift plan", "type": "object", "properties": { "daily_stats": { "description": "Statistics per day", "type": "array", "items": { "$ref": "#/definitions/DailyStatsResponse" } }, "helper_stats": { "description": "Statistics per helper/participant", "type": "array", "items": { "$ref": "#/definitions/HelperStatsResponse" } }, "overview": { "description": "Overview statistics for the entire plan", "allOf": [ { "$ref": "#/definitions/StatsOverviewResponse" } ] }, "type_stats": { "description": "Statistics per shift type", "type": "array", "items": { "$ref": "#/definitions/TypeStatsResponse" } } } }, "TypeStatsResponse": { "description": "Statistics for a single shift type", "type": "object", "properties": { "filled_hours": { "description": "Filled hours for this type", "type": "number", "example": 110 }, "id": { "description": "Unique identifier of the shift type", "type": "integer", "example": 1 }, "open_positions": { "description": "Number of open positions", "type": "integer", "example": 5 }, "percent_filled": { "description": "Percentage filled", "type": "integer", "example": 92 }, "title_de": { "description": "Title in German", "type": "string", "example": "Küchendienst" }, "title_en": { "description": "Title in English", "type": "string", "example": "Kitchen Duty" }, "total_filled": { "description": "Total filled positions for this type", "type": "integer", "example": 55 }, "total_hours": { "description": "Total hours for this type (required * duration)", "type": "number", "example": 120 }, "total_required": { "description": "Total required participants for this type", "type": "integer", "example": 60 }, "total_shifts": { "description": "Total number of shifts of this type", "type": "integer", "example": 20 } } }, "VerifyAdminRequest": { "description": "Request body for verifying admin password", "type": "object", "required": [ "password" ], "properties": { "password": { "description": "Admin password to verify", "type": "string", "example": "secretpassword123" } } }, "VerifyAdminResponse": { "description": "Response body for successful admin verification", "type": "object", "properties": { "token": { "description": "Token to use for admin operations", "type": "string", "example": "secretpassword123" } } }, "github_com_72nd_shifts_internal_model.BatchItemError": { "type": "object", "properties": { "code": { "description": "Machine-readable error code", "type": "string" }, "error": { "description": "Human-readable error message", "type": "string" }, "index": { "description": "Index of the failed item in the original request array", "type": "integer" } } } }, "securityDefinitions": { "AdminToken": { "description": "Admin authentication token. Required for admin-only endpoints. The token is the admin password set when creating a shift plan.", "type": "apiKey", "name": "X-Admin-Token", "in": "header" } } }