openapi: 3.0.0
info:
  title: Project
  version: 2.0.0
  description: >
    A **Project** represents a company in 4HSE.

    Every operation on the platform happens within the scope of a project:
    offices, people, actions,

    certificates, and compliance data all belong to a project.


    **Hierarchy:** Project (company) → Office (work location) → Person (worker).


    Other APIs reference the project via the `tenant_id` field — pass the
    `project_id`.


    Use this API to:

    - Find the company you want to operate on (e.g. search for "Acme
    Construction Ltd")

    - List all projects accessible by the authenticated user

    - Check project status — only projects with `status: active` are operational


    A customer with multiple companies has multiple projects. Each multi-company
    customer also has

    a project with `project_type: template`, which contains reference data,
    forms, and print templates

    reusable by operational projects and work locations.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/project/index:
    post:
      summary: index
      operationId: indexProject
      tags:
        - Projects
      description: >
        Returns a paginated list of projects accessible by the authenticated
        user.


        Most useful filters:

        - `name`: search a project by company name

        - `status: active`: exclude suspended or deleted projects

        - `project_type: safety`: exclude template projects
      requestBody:
        description: Parameters for searching projects
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectIndexParams"
            example:
              filter:
                name: Acme Construction
                project_type: safety
              per-page: 20
              page: 1
              sort: name
      responses:
        "200":
          description: List of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewProject"
              example:
                - project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                  name: Acme Construction Ltd
                  description: Safety management for Acme Construction sites
                  country: IT
                  status: active
                  project_type: safety
                  npeople: 47
                  customer_id: c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f
                  partner_id: d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a
                  created_at: 2023-06-15
                  updated_at: 2024-11-20
          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/project/create:
    post:
      summary: create
      operationId: createProject
      tags:
        - Projects
      description: >
        Creates a new project (company).


        Requires `name` and `country`. The `project_id` is auto-generated if not
        provided.

        By default the project is created with `status: active` and
        `project_type: safety`.


        After creation, the folder structure for file storage is prepared
        automatically.

        The typical next step is to create offices/work locations via the Office
        API.
      requestBody:
        description: Project object to be created
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Project"
            example:
              name: Acme Construction Ltd
              description: Safety management for Acme Construction sites
              country: IT
              project_type: safety
              customer_id: c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f
              partner_id: d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a
      responses:
        "201":
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
              example:
                project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                name: Acme Construction Ltd
                description: Safety management for Acme Construction sites
                country: IT
                status: active
                project_type: safety
                customer_id: c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f
                partner_id: d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a
                created_at: 2024-01-15
                updated_at: 2024-01-15
  /v2/project/view/{id}:
    get:
      summary: view
      operationId: viewProject
      tags:
        - Projects
      description: |
        Retrieves a single project by its ID.
      parameters:
        - name: id
          in: path
          description: The project_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Project found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewProject"
              example:
                project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                name: Acme Construction Ltd
                description: Safety management for Acme Construction sites
                country: IT
                status: active
                project_type: safety
                npeople: 47
                customer_id: c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f
                partner_id: d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a
                created_at: 2023-06-15
                updated_at: 2024-11-20
        "404":
          description: Project not found
  /v2/project/delete/{id}:
    delete:
      summary: delete
      operationId: deleteProject
      tags:
        - Projects
      description: >
        Deletes a project. The project is scheduled for deletion (`status:
        pending_delete`)

        and will be permanently removed at the date indicated in `deleted_at`.


        If `force=false` (default), the operation is interrupted and the
        response lists all

        child entities (offices, people, actions, certificates) that would be
        deleted.

        Use this to evaluate the impact.

        If `force=true`, the scheduled deletion is confirmed.
      parameters:
        - name: id
          in: path
          description: The project_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, confirms the scheduled deletion of the project and all
            child entities. If false, returns a preview of the entities that
            would be affected.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Project scheduled for deletion
        "400":
          description: Preview of entities that would be deleted (returned when force=false)
  /v2/project/update/{id}:
    put:
      summary: update
      operationId: updateProject
      tags:
        - Projects
      description: >
        Updates an existing project.


        Common use cases: changing the project name, suspending a project
        (`status: suspended`),

        updating the description. Setting `status` to `active` or `suspended`
        clears the deletion date.
      parameters:
        - name: id
          in: path
          description: The project_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Project fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Project"
            example:
              name: Acme Construction Ltd - Rome
              status: suspended
      responses:
        "200":
          description: Project updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
              example:
                project_id: b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01
                name: Acme Construction Ltd - Rome
                status: suspended
                country: IT
                project_type: safety
        "404":
          description: Project not found
components:
  schemas:
    Project:
      type: object
      properties:
        project_id:
          type: string
          format: uuid
          description: Unique identifier of the project. Auto-generated if not provided on
            creation. Other APIs reference the project via the `tenant_id` field
            — pass this value. If unknown, use the index endpoint filtering by
            `name` to find it.
        name:
          type: string
          maxLength: 50
          description: The company name.
        description:
          type: string
          nullable: true
          description: Optional free-text description.
        country:
          type: string
          maxLength: 2
          nullable: false
          description: ISO 3166-1 alpha-2 country code (e.g. "IT", "DE").
        status:
          type: string
          enum:
            - active
            - suspended
            - pending_delete
            - deleted
          description: >
            Project lifecycle status:

            - `active`: fully operational, all operations are allowed

            - `suspended`: temporarily disabled, data is preserved but
            operations may be restricted

            - `pending_delete`: scheduled for deletion, will be permanently
            removed at the date in `deleted_at`

            - `deleted`: permanently deleted
        project_type:
          type: string
          enum:
            - safety
            - template
          description: >
            - `safety`: an operational company project — the standard type

            - `template`: a container for reference data, forms, and print
            templates. Not an operational company. Each multi-company customer
            has one, and its contents are reusable by operational projects and
            work locations.
        data:
          type: object
          description: Additional structured data in JSON format.
        icon:
          type: string
          format: url
          maxLength: 255
          description: URL of the project icon image.
        npeople:
          type: integer
          description: Number of active workers in this project.
        subscription_id:
          type: string
          format: uuid
          description: The subscription governing access to this project. A project is
            only operational if its subscription is active.
        customer_id:
          type: string
          format: uuid
          description: The customer (billing entity) that owns this project.
        partner_id:
          type: string
          format: uuid
          description: The partner managing this project.
        created_at:
          type: string
          format: date
          description: Date when the project was created.
        updated_at:
          type: string
          format: date
          description: Date when the project was last modified.
        deleted_at:
          type: string
          format: date
          description: Scheduled deletion date. Cleared when status is set back to
            `active` or `suspended`.
      required:
        - name
        - country
    ViewProject:
      type: object
      properties:
        project_id:
          type: string
          format: uuid
          description: Unique identifier of the project. Other APIs reference the project
            via the `tenant_id` field — pass this value.
        name:
          type: string
          maxLength: 50
          description: The company name.
        description:
          type: string
          nullable: true
          description: Optional free-text description.
        country:
          type: string
          nullable: false
          description: ISO 3166-1 alpha-2 country code.
        status:
          type: string
          enum:
            - active
            - suspended
            - pending_delete
            - deleted
          description: |
            Project lifecycle status:
            - `active`: fully operational
            - `suspended`: temporarily disabled
            - `pending_delete`: scheduled for deletion
            - `deleted`: permanently deleted
        project_type:
          type: string
          enum:
            - safety
            - template
          description: >
            - `safety`: operational company project

            - `template`: container for reference data, forms, and print
            templates
        data:
          type: object
          description: Additional structured data in JSON format.
        icon:
          type: string
          format: url
          maxLength: 255
          description: URL of the project icon image.
        npeople:
          type: integer
          description: Number of active workers in this project.
        subscription_id:
          type: string
          format: uuid
          description: The subscription governing access to this project.
        customer_id:
          type: string
          format: uuid
          description: The customer (billing entity) that owns this project.
        partner_id:
          type: string
          format: uuid
          description: The partner managing this project.
        created_at:
          type: string
          format: date
          description: Date when the project was created.
        updated_at:
          type: string
          format: date
          description: Date when the project was last modified.
    ProjectIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewProject"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          description: Field to sort by. Prefix with minus for descending order (e.g.
            "-name").
          enum:
            - name
            - status
            - project_type
            - country
            - created_at
        history:
          type: boolean
          description: If true, includes historized (no longer active) entries in the
            results. By default only current entries are returned.
      example:
        filter:
          name: Acme Construction
          status: active
        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
