Aedifion Company API

openapi: 3.2.0
info:
  description: 'Welcome to the interactive user interface (UI) for the aedifion REST API.


    This UI allows you to


    - browse documentation of all endpoints

    - explore schemas and examples of request parameters and responses

    - call endpoints and view responses


    Further documentation as well as extensive guides and tutorials are available in the official documentation.'
  title: Docs Company API
  version: ''
servers:
- url: ''
tags:
- description: Creating, modifying, and accessing companies and related resources.
  name: Company
paths:
  /v2/company:
    get:
      description: Returns a list of projects and users defined for the queried company.
      operationId: get_company
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyWithContext'
          description: Successful operation. Returns the company's projects and users.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''get''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get all projects and users defined in the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    put:
      description: Updates the details for the company of the logged in user.
      operationId: put_company
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCompany'
        description: "The details of the updated user:\n  - **description** is optional, the new description of the updated company\n  - **address** is optional, the address of the updated company\n  - **phone** is optional, the phone of the updated company\n"
        required: true
        x-body-name: company
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Update the details for the company of the logged in user
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/avatar:
    delete:
      operationId: delete_company_avatar
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Successful operation.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Out of service.
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Deletes the current avatar image of the user's company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    post:
      operationId: post_company_avatar
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadAvatarRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: Successful operation.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: File is not an image file.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Out of service.
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Uploads and stores an image for the current user's company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/file:
    delete:
      description: Delete a file on the company's document database.
      operationId: delete_company_file
      parameters:
      - description: Path to file to be deleted.
        in: query
        name: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The details of deleted resource is returned in the ''resource'' field and the ''operation'' is set to ''delete''.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''delete''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Delete a file on the company's document database
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    get:
      description: Download a file from the company's document database.
      operationId: get_company_file
      parameters:
      - description: Path to the file to download.
        in: query
        name: path
        required: true
        schema:
          type: string
      - description: "The time period for which the generated link is valid.\nAcceptable format is a number followed by 's', 'm', 'h', 'd' for seconds, minutes, hours and days respectively.\n - Examples: 1h, 30m, 7d.\n - Minimum allowed value: 1s.\n - Maximum allowed value: 7d\n"
        in: query
        name: expiry
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
          description: Successful operation. The details of the file along with a downloadable link is returned.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''get''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Download a file from the company's document database
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    post:
      description: Upload a file to the company's document database.
      operationId: post_company_file
      parameters:
      - description: 'Path to a sub-folder, if required. If the folder doesn''t exist, it will be created.

          Paths are normalized: consecutive, leading, and trailing slashes are removed.

          The folder nesting depth must not exceed the configured maximum (see the ''max_folder_depth'' quota limit returned by the quota endpoint).

          '
        in: query
        name: folder
        required: false
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadFileRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The details of uploaded resource is returned in the ''resource'' field and the ''operation'' is set to ''create''.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.

            The file path is invalid or the folder nesting depth exceeds the configured maximum.

            Filenames and paths may only contain alphanumeric characters, ''/'', ''_'', ''-'', and spaces; the filename must have an extension separated by a dot.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''create''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Upload a file to the company's document database
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    put:
      description: Replace a file on the company's document database.
      operationId: put_company_file
      parameters:
      - description: 'Path to a sub-folder.

          Paths are normalized: consecutive, leading, and trailing slashes are removed.

          The folder nesting depth must not exceed the configured maximum (see the ''max_folder_depth'' quota limit returned by the quota endpoint).

          '
        in: query
        name: folder
        required: false
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadFileRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The details of uploaded resource is returned in the ''resource'' field and the ''operation'' is set to ''update''.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.

            The file path is invalid or the folder nesting depth exceeds the configured maximum.

            Filenames and paths may only contain alphanumeric characters, ''/'', ''_'', ''-'', and spaces; the filename must have an extension separated by a dot.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''update''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Replace a file on the company's document database
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/files:
    get:
      description: Get a list of files from the company's document database.
      operationId: get_company_files
      parameters:
      - description: Search file database. All files or folders matching the search string will be returned.
        in: query
        name: search
        schema:
          type: string
      - description: Page number.
        in: query
        name: page
        schema:
          format: int64
          type: integer
      - description: Items per page. Defaults to 20, maximum limit is 100.
        in: query
        name: per_page
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilesList'
          description: A list of files along with its details is returned.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''create''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get a list of files from the company's document database
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/quota:
    get:
      description: Returns quota for various services enabled for the company.
      operationId: get_company_quota
      parameters:
      - description: Optional parameter, filter quota for a specific service.
        in: query
        name: service
        schema:
          enum:
          - files
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quotas'
          description: Successful operation. Returns quota for services.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get quota for various services enabled for the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/role:
    post:
      description: Creates a new role for the company, user is logged in with.
      operationId: post_company_role
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCompanyRole'
        description: 'The details of the role to create\n

          - **name** is mandatory

          - **description** is optional (default = \"\")

          - **authed_endpoints** is mandatory, the list of numeric endpoint ids the specified role can access

          '
        required: true
        x-body-name: role_definition
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRole'
          description: Successful operation. Returns details of created role.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''post''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Create a new role for the logged user's company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/role/{role_id}:
    delete:
      description: Deletes an existing role for this company.
      operationId: delete_company_role
      parameters:
      - description: The id of the role that should be deleted.
        in: path
        name: role_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The deleted project is returned within the ''resource'' field and ''operation'' will indicate a ''delete'' operation

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''get''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Delete an existing role for the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    put:
      description: Updates an existing role for the company.
      operationId: put_company_role
      parameters:
      - description: The id of the role.
        in: path
        name: role_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCompanyRole'
        description: 'The details of the role to create\n

          - **name** that needs to be edited

          - **description** that needs to be edited

          - **endpoints** is the list of numeric endpoint ids the specified role can access

          '
        required: true
        x-body-name: role_definition
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyRole'
          description: Successful operation. Returns details of edited role.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''post''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Updates an existing role for the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/role/{role_id}/user/{user_id}:
    delete:
      description: Removes role with id 'role_id' from user with id 'id'.
      operationId: delete_user_company_role
      parameters:
      - description: The unique id of the user
        in: path
        name: user_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The unique id of the role
        in: path
        name: role_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The deleted relation between ''user'' and ''role'' is returned in the ''resource'' field of the response and ''operation'' is set to ''delete''.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''delete''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Removes a role from a user
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    post:
      description: Assigns role with its id 'role_id' to user with her/his id 'id'.
      operationId: post_user_company_role
      parameters:
      - description: The unique id of the user
        in: path
        name: user_id
        required: true
        schema:
          format: int64
          type: integer
      - description: The unique id of the role
        in: path
        name: role_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The newly created relation between ''user'' and ''role'' is returned in the ''resource'' field of the response and ''operation'' is set to ''create''.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''create''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Assign a role to a user
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/roles:
    get:
      description: Returns a list of roles defined for the queried company.
      operationId: get_company_roles
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfCompanyRoles'
          description: Successful operation. Returns a list of roles in the queried company.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''get''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get all roles defined in the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/user:
    post:
      description: Creates a new user with the specified details.
      operationId: post_user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
        description: 'The details of the user to create\n

          - **firstName** is mandatory, the first name of the new user

          - **lastName**  is mandatory, the last name of the new user

          - **email** is mandatory, must be unique among all users

          - **password** is mandatory, the initial password for the new user

          - **address** is optional, the address of the updated user

          - **phone** is optional, the phone number of the updated user

          - **units_system** is optional, the preferred system of units of the updated user

          - **currency_system** is optional, the preferred currency system of the updated user

          - **locale** is optional, the locale of the updated user

          '
        required: true
        x-body-name: user_body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation. The newly created user is returned in

            the ''resource'' field and the ''operation'' will indicate a CREATE operation.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unsuccessful request. The error is returned in the ''error''

            field.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Create a new user
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/user/{user_id}:
    delete:
      description: Deletes an existing user within the company.
      operationId: delete_user_company
      parameters:
      - description: id of the user that would be deleted.
        in: path
        name: user_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The deleted user is returned in the ''resource'' field and the ''operation'' will indicate a DELETE operation.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unsuccessful request. The error is returned in the 'error' field.
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Delete an existing user within the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    get:
      description: 'Get a user within the company.


        **Note**: Only company admins can fetch user details of users within the same company while non-admins can only fetch their own user details.'
      operationId: get_company_user
      parameters:
      - description: id of the user that will be updated.
        in: path
        name: user_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWithContext'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unsuccessful request.

            The error is returned in the ''error'' field.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get a user within the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
    put:
      description: 'Updates an existing user within the company.


        **Note**: Only company admins can update user details of users within the same company while non-admins can only update their own user details.'
      operationId: put_company_user
      parameters:
      - description: id of the user that will be updated.
        in: path
        name: user_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
        description: "The details of the updated user:\n  - **firstName** is optional, the new first name of the updated user\n  - **lastName** is optional, the new last name of the updated user\n  - **units_system** is optional, the preferred system of units of the updated user\n  - **currency_system** is optional, the preferred currency system of the updated user\n  - **locale** is optional, the locale of the updated user\n  - **address** is optional, the address of the updated user\n  - **phone** is optional, the phone number of the updated user\n"
        required: true
        x-body-name: user_details
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
          description: 'Successful operation.

            The updated user is returned in the ''resource'' field and the ''operation'' will indicate a PUT operation.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unsuccessful request.

            The error is returned in the ''error'' field.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Updates an existing user within the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/{company_id}:
    get:
      description: Returns a list of projects and users defined for the queried company.
      operationId: get_company_by_id
      parameters:
      - description: id of the company.
        in: path
        name: company_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyWithContext'
          description: Successful operation. Returns the company's projects and users.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            Details on the error are returned in the ''error'' field of the response and ''operation'' is set to ''get''.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get all projects and users defined in the company
      tags:
      - Company
      x-openapi-router-controller: app.controllers.company_controller
  /v2/company/{company_id}/project-groups:
    post:
      description: 'Creates a new project group for the company, optionally assigning projects to it.

        Projects that do not belong to the company are silently ignored.'
      operationId: post_company_project_group
      parameters:
      - description: The id of the company that the project group belongs to.
        in: path
        name: company_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewProjectGroup'
        description: The details of the project group to create.
        required: true
        x-body-name: project_group
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectGroup'
          description: 'Success.

            The project group has been created.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.

            Invalid input data.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized request.

            The error is returned in the ''error'' field.

            '
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Company not found.
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Create a project group
      tags:
      - Company
      x-openapi-router-contro

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aedifion/refs/heads/main/openapi/aedifion-company-api-openapi.yml