openapi: 3.0.0
info:
  title: OrgUnit
  version: 2.0.0
  description: >
    An **OrgUnit** represents a unit in the company organization chart.

    Organization units have a tree structure: each unit can have a parent unit

    (`parent_org_unit_id`) and multiple child units.


    Examples: "General Management", "Production Department", "Quality Office".


    Belongs to a project (not to an office). People are assigned to organization
    units

    via OrgPerson, optionally with a role (OrgRole).


    Use this API to:

    - Define the company organization chart structure

    - Create child units (by passing `parent_org_unit_id`)

    - Browse the organization chart for a project (filter by `project_id`)


    Supports historicization.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/org-unit/index:
    post:
      summary: index
      operationId: indexOrgUnit
      tags:
        - OrgUnits
      description: |
        Returns a paginated list of organization units.

        Most useful filters:
        - `project_id`: all units in a company
        - `parent_org_unit_id`: child units of a specific unit
        - `name`: search by name
      requestBody:
        description: Parameters for searching
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgUnitIndexParams"
            example:
              filter:
                project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
              per-page: 20
              page: 1
              sort: name
      responses:
        "200":
          description: List of organization units
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewOrgUnit"
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/org-unit/create:
    post:
      summary: create
      operationId: createOrgUnit
      tags:
        - OrgUnits
      description: >
        Creates a new organization unit.


        Requires `name` and `project_id`.

        The `org_unit_id` is auto-generated if not provided.


        To create a child unit, pass the `parent_org_unit_id` of the parent
        unit.

        Omit `parent_org_unit_id` for top-level units.
      requestBody:
        description: Organization unit to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgUnit"
      responses:
        "201":
          description: Organization unit created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrgUnit"
  /v2/org-unit/view/{id}:
    get:
      summary: view
      operationId: viewOrgUnit
      tags:
        - OrgUnits
      description: Retrieves a single organization unit by its ID.
      parameters:
        - name: id
          in: path
          description: The org_unit_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Organization unit found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewOrgUnit"
        "404":
          description: Not found
  /v2/org-unit/update/{id}:
    put:
      summary: update
      operationId: updateOrgUnit
      tags:
        - OrgUnits
      description: Updates an existing organization unit.
      parameters:
        - name: id
          in: path
          description: The org_unit_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgUnit"
      responses:
        "200":
          description: Updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrgUnit"
        "404":
          description: Not found
  /v2/org-unit/delete/{id}:
    delete:
      summary: delete
      operationId: deleteOrgUnit
      tags:
        - OrgUnits
      description: >
        Deletes an organization unit.


        If `force=false` (default), the response lists child entities (child
        units, person assignments).

        If `force=true`, the unit and all child entities are deleted.
      parameters:
        - name: id
          in: path
          description: The org_unit_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the unit and all child entities.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Deleted successfully
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
components:
  schemas:
    OrgUnit:
      type: object
      required:
        - name
        - project_id
      properties:
        org_unit_id:
          type: string
          format: uuid
          description: Unique identifier. Auto-generated if not provided.
        code:
          type: string
          maxLength: 50
          description: Identifier code.
        name:
          type: string
          maxLength: 255
          description: Name of the organization unit.
        description:
          type: string
          nullable: true
          description: Optional description.
        parent_org_unit_id:
          type: string
          format: uuid
          nullable: true
          description: Parent unit in the tree hierarchy. Null for top-level units. Pass
            the `org_unit_id` of the parent.
        project_id:
          type: string
          format: uuid
          description: The project (company). Pass the `project_id`.
    ViewOrgUnit:
      type: object
      properties:
        org_unit_id:
          type: string
          format: uuid
        code:
          type: string
        name:
          type: string
        description:
          type: string
        parent_org_unit_id:
          type: string
          format: uuid
          nullable: true
        project_id:
          type: string
          format: uuid
        owned_active:
          type: boolean
          nullable: true
          description: Whether this unit is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent entities are currently active.
    OrgUnitIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewOrgUnit"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - code
            - name
        history:
          type: boolean
          description: If true, includes historicized entries.
      example:
        filter:
          project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
        per-page: 100
        page: 1
        sort: name
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
