{ "openapi": "3.1.0", "info": { "title": "Personalrampe Skills API", "version": "1.0.0", "description": "REST API for integrating external HR systems with Personalrampe Skills. Manage employees, skills, ratings, positions, and webhooks." }, "servers": [ { "url": "https://skills.personalrampe.de/api/v1", "description": "Production" }, { "url": "http://localhost:3000/api/v1", "description": "Local development" } ], "security": [{ "ApiKeyAuth": [] }], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "API key authentication. Include your API key in the Authorization header as Bearer ." } }, "schemas": { "ApiError": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } } } } }, "PaginationMeta": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPrevPage": { "type": "boolean" } } }, "Employee": { "type": "object", "properties": { "id": { "type": "string" }, "personnelNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "businessEmail": { "type": "string", "format": "email" }, "title": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "hiredAt": { "type": "string", "format": "date-time", "nullable": true }, "leftAt": { "type": "string", "format": "date-time", "nullable": true }, "isHRTeamMember": { "type": "boolean" } } }, "EmployeeDetail": { "allOf": [ { "$ref": "#/components/schemas/Employee" }, { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object", "properties": { "personSkillId": { "type": "string" }, "skillId": { "type": "string" }, "skillName": { "type": "string" }, "latestRating": { "type": "object", "nullable": true, "properties": { "score": { "type": "integer" }, "ratingType": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } ] }, "Skill": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ratingScaleMin": { "type": "integer" }, "ratingScaleMax": { "type": "integer" }, "ratingScaleType": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "SkillDetail": { "allOf": [ { "$ref": "#/components/schemas/Skill" }, { "type": "object", "properties": { "employeeCount": { "type": "integer" } } } ] }, "Position": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "status": { "type": "string" }, "mustBeFilledBy": { "type": "string", "format": "date-time", "nullable": true }, "replacesPerson": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, "requiredSkills": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string" }, "skillName": { "type": "string" }, "minimumRating": { "type": "integer" } } } } } }, "PositionDetail": { "allOf": [ { "$ref": "#/components/schemas/Position" }, { "type": "object", "properties": { "possibleReplacements": { "type": "array", "items": { "type": "object", "properties": { "replacementId": { "type": "string" }, "candidate": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, "readyAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "skillsGap": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string" }, "skillName": { "type": "string" }, "minimumRating": { "type": "integer" }, "currentScore": { "type": "integer", "nullable": true }, "gap": { "type": "integer" } } } } } } } } } ] }, "Rating": { "type": "object", "properties": { "ratingId": { "type": "string" }, "personSkillId": { "type": "string" }, "skillId": { "type": "string" }, "skillName": { "type": "string" }, "score": { "type": "integer" }, "ratingType": { "type": "string" }, "comment": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "PersonSkill": { "type": "object", "properties": { "personSkillId": { "type": "string" }, "skillId": { "type": "string" }, "skillName": { "type": "string" }, "latestRating": { "type": "object", "nullable": true, "properties": { "ratingId": { "type": "string" }, "score": { "type": "integer" }, "ratingType": { "type": "string" }, "comment": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "paths": { "/employees": { "get": { "summary": "List employees", "description": "Returns paginated list of employees", "tags": ["Employees"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "departmentId", "in": "query", "schema": { "type": "string" } }, { "name": "isActive", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of employees", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create employee", "description": "Creates a new employee", "tags": ["Employees"], "security": [{ "ApiKeyAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "personnelNumber", "firstName", "lastName", "businessEmail" ], "properties": { "personnelNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "businessEmail": { "type": "string", "format": "email" }, "title": { "type": "string" }, "gender": { "type": "string" }, "hiredAt": { "type": "string", "format": "date-time" }, "isHRTeamMember": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created employee", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Employee" } } } } } } } } }, "/employees/{id}": { "get": { "summary": "Get employee", "description": "Returns full employee with skills summary", "tags": ["Employees"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EmployeeDetail" } } } } } } } }, "patch": { "summary": "Update employee", "description": "Partially updates an employee", "tags": ["Employees"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personnelNumber": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "businessEmail": { "type": "string", "format": "email" }, "title": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "hiredAt": { "type": "string", "format": "date-time", "nullable": true }, "leftAt": { "type": "string", "format": "date-time", "nullable": true }, "isHRTeamMember": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated employee", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Employee" } } } } } } } }, "delete": { "summary": "Deactivate employee (soft delete)", "description": "Sets leftAt to current time", "tags": ["Employees"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "leftAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/employees/{id}/skills": { "get": { "summary": "List employee skills", "description": "Returns all skills for an employee with latest ratings", "tags": ["Employee Skills"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Employee skills", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonSkill" } } } } } } } } }, "put": { "summary": "Upsert employee skill rating", "description": "Creates PersonSkill if not exists, then adds a new rating", "tags": ["Employee Skills"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["score", "ratingType"], "properties": { "score": { "type": "integer" }, "ratingType": { "type": "string", "enum": [ "MANAGER_EVALUATION", "SELF_ASSESMENT", "LLM_RATING" ] }, "comment": { "type": "string" } } } } } }, "responses": { "200": { "description": "Upserted skill rating", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PersonSkill" } } } } } } } }, "delete": { "summary": "Remove employee skill", "description": "Deletes PersonSkill and all its ratings", "tags": ["Employee Skills"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "schema": { "type": "string" }, "description": "Set to 'true' if more than 5 ratings exist" } ], "responses": { "200": { "description": "Skill removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } } } }, "/employees/{id}/ratings": { "get": { "summary": "List employee ratings", "description": "Returns all ratings for an employee with optional filters", "tags": ["Ratings"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "skillId", "in": "query", "schema": { "type": "string" } }, { "name": "ratingType", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated ratings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rating" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "post": { "summary": "Create rating", "description": "Creates PersonSkill if not exists, then creates a new Rating", "tags": ["Ratings"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["skillId", "score", "ratingType"], "properties": { "skillId": { "type": "string" }, "score": { "type": "integer" }, "ratingType": { "type": "string", "enum": [ "MANAGER_EVALUATION", "SELF_ASSESMENT", "LLM_RATING" ] }, "comment": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created rating", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Rating" } } } } } } } } }, "/skills": { "get": { "summary": "List skills", "description": "Returns paginated list of available skills", "tags": ["Skills"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated skills", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "post": { "summary": "Create skill", "description": "Creates a new available skill", "tags": ["Skills"], "security": [{ "ApiKeyAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "ratingScaleMin": { "type": "integer", "default": 0 }, "ratingScaleMax": { "type": "integer", "default": 5 }, "ratingScaleType": { "type": "string", "enum": ["NUMERIC", "STAR", "CUSTOM"] } } } } } }, "responses": { "201": { "description": "Created skill", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Skill" } } } } } } } } }, "/skills/{id}": { "get": { "summary": "Get skill", "description": "Returns skill with usage statistics", "tags": ["Skills"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SkillDetail" } } } } } } } }, "patch": { "summary": "Update skill", "description": "Partially updates a skill", "tags": ["Skills"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ratingScaleMin": { "type": "integer" }, "ratingScaleMax": { "type": "integer" }, "ratingScaleType": { "type": "string", "enum": ["NUMERIC", "STAR", "CUSTOM"] } } } } } }, "responses": { "200": { "description": "Updated skill", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Skill" } } } } } } } }, "delete": { "summary": "Delete skill", "description": "Deletes a skill if it has no employee ratings", "tags": ["Skills"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } }, "409": { "description": "Skill has employee ratings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/positions": { "get": { "summary": "List positions", "description": "Returns paginated list of positions", "tags": ["Positions"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated positions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/positions/{id}": { "get": { "summary": "Get position", "description": "Returns full position with replacements and skills gap", "tags": ["Positions"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Position detail with replacements", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PositionDetail" } } } } } } } } }, "/webhooks": { "get": { "summary": "List webhook endpoints", "description": "Returns registered webhook endpoints for the organisation", "tags": ["Webhooks"], "security": [{ "ApiKeyAuth": [] }], "responses": { "200": { "description": "Webhook endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } } } }, "post": { "summary": "Create webhook endpoint", "description": "Registers a new webhook endpoint", "tags": ["Webhooks"], "security": [{ "ApiKeyAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "events"], "properties": { "url": { "type": "string", "format": "uri", "description": "Must be HTTPS" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "employee.created", "employee.updated", "employee.deactivated", "skill.rated", "position.updated" ] } }, "secret": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created webhook endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } } } }, "/webhooks/{id}": { "delete": { "summary": "Delete webhook endpoint", "description": "Removes a webhook endpoint", "tags": ["Webhooks"], "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } } } } } } }