{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenHR REST API",
    "version": "1.0.0",
    "description": "Read-only integration API. Authenticate with `Authorization: Bearer hrk_...` API keys created by HR admins. Outbound webhooks are signed with `X-HR-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"t.body\">`. Events: employee.invited, employee.updated, leave.requested, leave.approved, leave.rejected, leave.cancelled, onboarding.task_completed, review.submitted, review.acknowledged."
  },
  "servers": [
    {
      "url": "/api/public/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/employees": {
      "get": {
        "summary": "List employees (scope employees:read)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "active",
                "onboarding",
                "offboarding",
                "inactive"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Missing scope"
          }
        }
      }
    },
    "/employees/{id}": {
      "get": {
        "summary": "Get an employee (scope employees:read)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/departments": {
      "get": {
        "summary": "List departments (scope employees:read)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/leave-requests": {
      "get": {
        "summary": "List leave requests (scope leave:read)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "pending",
                "approved",
                "rejected",
                "cancelled"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/payroll": {
      "get": {
        "summary": "Payroll CSV export (scope payroll:read)",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": {
              "enum": [
                "generic",
                "fortnox",
                "gusto"
              ]
            }
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {}
            }
          }
        }
      }
    }
  }
}