FOSSology Admin API

openapi: 3.1.0
info:
  title: FOSSology Admin API
  description: Automate your fossology instance using REST API
  version: 1.6.2
  contact:
    email: fossology@fossology.org
  license:
    name: GPL-2.0-only
    url: https://github.com/fossology/fossology/blob/master/LICENSE
servers:
- url: http://localhost/repo/api/v1
  description: Localhost instance
- url: http://localhost/repo/api/v2
  description: Localhost instance (Version 2)
security:
- bearerAuth: []
- oauth: []
tags:
- name: Admin
  description: Administrator tasks
paths:
  /obligations/list:
    get:
      operationId: getObligationsList
      tags:
      - Admin
      summary: Get the list of obligations
      description: 'Get the list of obligations in the server.

        '
      responses:
        '200':
          description: The API information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationsList'
        default:
          $ref: '#/components/responses/defaultResponse'
  /obligations/{id}:
    parameters:
    - name: id
      required: true
      description: Id of the obligation
      in: path
      schema:
        type: integer
    get:
      operationId: getObligationsData
      tags:
      - Admin
      summary: Get details of a particular obligation
      description: 'Get the details of a particular obligation from the server.

        '
      responses:
        '200':
          description: The API information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationExtended'
        default:
          $ref: '#/components/responses/defaultResponse'
    delete:
      operationId: deleteObligationsData
      tags:
      - Admin
      summary: Delete a particular obligation
      description: 'Delete a particular obligation from the server.

        '
      responses:
        '200':
          description: Obligation deleted.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /obligations:
    get:
      operationId: getAllObligationsData
      tags:
      - Admin
      summary: Get details of a all obligations
      description: 'Get the details of all obligations from the server.

        '
      responses:
        '200':
          description: The API information
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ObligationExtended'
        default:
          $ref: '#/components/responses/defaultResponse'
  /users:
    post:
      operationId: createUser
      tags:
      - Admin
      summary: Create a new user
      description: 'Create a new user

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/User'
              - type: object
                properties:
                  user_pass:
                    type: string
                  defaultVisibility:
                    type: string
                    enum:
                    - public
                    - protected
                    - private
                required:
                - name
          application/x-www-form-urlencoded:
            schema:
              allOf:
              - $ref: '#/components/schemas/User'
              - type: object
                properties:
                  user_pass:
                    type: string
                  defaultVisibility:
                    type: string
                    enum:
                    - public
                    - protected
                    - private
                required:
                - name
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '409':
          description: User with the same email or username already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    get:
      operationId: getUsers
      tags:
      - Admin
      description: Get the registered users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        default:
          $ref: '#/components/responses/defaultResponse'
  /users/{id}:
    parameters:
    - name: id
      required: true
      in: path
      schema:
        type: integer
    get:
      operationId: getUserById
      tags:
      - Admin
      summary: Get user by id
      description: 'Get one single user by id

        '
      responses:
        '200':
          description: User with the given id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          $ref: '#/components/responses/defaultResponse'
    put:
      operationId: modifyUserById
      tags:
      - Admin
      summary: Edit user details by id
      description: 'Edit user details by id

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/User'
              - type: object
                properties:
                  user_pass:
                    type: string
                  defaultFolderId:
                    type: integer
                  defaultVisibility:
                    type: string
                    enum:
                    - public
                    - protected
                    - private
          application/x-www-form-urlencoded:
            schema:
              allOf:
              - $ref: '#/components/schemas/User'
              - type: object
                properties:
                  user_pass:
                    type: string
                  defaultFolderId:
                    type: integer
                  defaultVisibility:
                    type: string
                    enum:
                    - public
                    - protected
                    - private
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Missing or wrong parameters in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '403':
          description: The session owner is not an admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: UserId doesn't exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    delete:
      operationId: deleteUserById
      tags:
      - Admin
      summary: Delete user by id
      description: 'Delete a single user by id

        '
      responses:
        '202':
          description: User will be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /users/tokens:
    post:
      operationId: createRestApiToken
      tags:
      - Admin
      summary: Create a new REST API Token
      description: 'Create a new REST API Token

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '201':
          description: Token created successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Info'
                - type: object
                  properties:
                    token:
                      type: string
                      example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2NTgwODI1OTksIm5iZiI6MTY1NzkwOTgwMCwianRpIjoiTXk0eiIsInNjb3BlIjoid3JpdGUifQ.Sl1acvN0GlCe7VUZJQX00u_vpfWrtfJlVYQ63FBkzP4
        '400':
          description: Following parameters are required in the request body -- token_name,token_scope,token_expire
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /users/tokens/{type}:
    parameters:
    - name: type
      required: true
      in: path
      schema:
        type: string
        enum:
        - active
        - expired
    get:
      operationId: getTokensByType
      tags:
      - Admin
      summary: Get all the REST API tokens (active | expired)
      description: 'Get all the REST API tokens (active | expired)

        '
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Info'
                - type: object
                  properties:
                    active_tokens:
                      $ref: '#/components/schemas/Token'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/scheduler/operation/{operationName}:
    parameters:
    - name: operationName
      required: true
      description: Name of the operation
      in: path
      schema:
        type: string
        enum:
        - status
        - database
        - reload
        - agents
        - verbose
        - stop
        - restart
        - pause
        - priority
    get:
      operationId: getSchedulerOptionsByOperation
      tags:
      - Admin
      summary: get scheduler options by operation
      description: Returns the scheduler options for a specific operation
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSchedulerOption'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/scheduler/operation/run:
    parameters:
    - name: job
      required: false
      description: Name of the selected job
      in: query
      schema:
        type: string
    - name: level
      required: false
      description: Level of the selected verbose
      in: query
      schema:
        type: string
    - name: priority
      required: false
      description: Priority option selected
      in: query
      schema:
        type: string
    post:
      operationId: handleSchedulerRun
      tags:
      - Admin
      summary: Run the scheduler
      description: Run the scheduler with the selected options from a specific operation
      requestBody:
        description: Scheduler operation
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operation:
                  type: string
                  description: Operation to be run by the scheduler
                  enum:
                  - status
                  - database
                  - reload
                  - agents
                  - verbose
                  - stop
                  - restart
                  - pause
                  - priority
      responses:
        '200':
          description: Scheduler run successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /folders:
    parameters:
    - name: groupName
      description: The group name to chose while accessing folders
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    post:
      operationId: createFolder
      tags:
      - Admin
      summary: Create a new folder
      description: 'Create a new child folder with optional description

        '
      parameters:
      - name: parentFolder
        in: header
        required: true
        description: Parent folder for the new folder
        schema:
          type: integer
      - name: folderName
        in: header
        required: true
        description: Name of the new folder
        schema:
          type: string
      - name: folderDescription
        in: header
        required: false
        description: Description of the new folder
        schema:
          type: string
      responses:
        '200':
          description: Folder with the same name already exists under the same parent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '201':
          description: Folder is created with new folder id in message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /folders/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: ID of the folder
      schema:
        type: integer
    - name: groupName
      description: The group name to chose while accessing the folder
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    delete:
      operationId: deleteFolderById
      tags:
      - Admin
      summary: Delete a folder
      description: 'Schedule a folder deletion

        '
      responses:
        '202':
          description: Folder scheduled to be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /customise:
    get:
      operationId: getCustomiseData
      tags:
      - Admin
      summary: Get the Admin configuration data
      description: 'Returns the admin configuration data from the server

        '
      responses:
        '200':
          description: Config data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customise'
        '403':
          description: The session owner is not an admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    put:
      operationId: updateCustomiseData
      tags:
      - Admin
      summary: Update the Admin configuration data
      description: 'Updates the admin configuration data.

        '
      requestBody:
        description: Key and value to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCustomiseInfo'
      responses:
        '200':
          description: Config data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '403':
          description: The session owner is not an admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /groups:
    post:
      operationId: createGroup
      tags:
      - Admin
      summary: Create a new group
      description: 'Create a new user group

        '
      parameters:
      - name: name
        in: header
        required: true
        description: Name of the new group
        schema:
          type: string
      responses:
        '200':
          description: Group has been added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Group already exists, failed to create group or no group name provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /groups/{id}/user/{userId}:
    parameters:
    - name: id
      required: true
      description: Id of the group
      in: path
      schema:
        type: integer
    - name: userId
      required: true
      description: user id of the member
      in: path
      schema:
        type: integer
    post:
      operationId: addMember
      tags:
      - Admin
      summary: Add user to a group
      description: 'add a new user to group

        '
      requestBody:
        description: Request options
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddMember'
      responses:
        '200':
          description: User has been added to group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/admincandidates/{id}:
    parameters:
    - name: id
      required: true
      description: Id of the license-candidate
      in: path
      schema:
        type: integer
    delete:
      operationId: deleteByLicenseCandidateId
      tags:
      - Admin
      summary: Delete license candidate by id.
      description: 'Delete a single admin-license-candidate by the given id.

        '
      responses:
        '202':
          description: License candidate will be deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '403':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/verify/{shortname}:
    parameters:
    - name: shortname
      in: path
      required: true
      description: Shortname of the license to be verified
      schema:
        type: string
    put:
      operationId: verifyLicense
      tags:
      - Admin
      summary: Verify a license as new or variant
      description: 'Verify a license as new or variant of another license

        '
      requestBody:
        description: The shortname of the parent license | Same name if it's to be verified as a new license
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentShortname:
                  description: Shortname of the parent license
                  type: string
                  example: MIT
      responses:
        '200':
          description: License verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Given License not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/merge/{shortname}:
    parameters:
    - name: shortname
      in: path
      required: true
      description: Shortname of the license to be merged
      schema:
        type: string
    put:
      operationId: mergeLicense
      tags:
      - Admin
      summary: Merge a license with another
      description: 'Merge a license to another existing license

        '
      requestBody:
        description: The shortname of the parent license to be merged into
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentShortname:
                  description: Shortname of the parent license
                  type: string
                  example: MIT
      responses:
        '200':
          description: License merged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Given License not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /overview/database/contents:
    get:
      operationId: getDatabaseContents
      tags:
      - Admin
      summary: Get database contents
      description: 'Get database contents for the dashboard display.

        '
      responses:
        '200':
          description: List of the database contents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetDatabaseContent'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /overview/info/php:
    get:
      operationId: getPhpInfo
      tags:
      - Admin
      summary: Get PHP info
      description: 'Get PHP info

        '
      responses:
        '200':
          description: PHP info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPHPInfo'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /overview/disk/usage:
    get:
      operationId: getDiskUsage
      tags:
      - Admin
      summary: Get disk usage
      description: 'Get disk usage

        '
      responses:
        '200':
          description: Disk usage response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DiskUsage'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/suggest:
    post:
      operationId: getSuggestedLicense
      tags:
      - Admin
      summary: Get suggested license by reference text.
      description: 'Get a single suggested license by the given reference text.

        '
      requestBody:
        description: Reference text to get suggested license
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                referenceText:
                  description: Reference text to get suggested license
                  type: string
                  example: According to MIT license, add some modifications
      responses:
        '200':
          description: Request is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSuggestedLicense'
        '403':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /overview/database/metrics:
    get:
      operationId: getDatabaseMetrics
      tags:
      - Admin
      summary: Get database metrics
      description: 'Get database metrics for the dashboard display.

        '
      responses:
        '200':
          description: List of the database metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetDatabaseMetric'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /overview/queries/active:
    get:
      operationId: getActiveQueries
      tags:
      - Admin
      summary: Get active queries
      description: 'Get a list of active queries from the database.

        '
      responses:
        '200':
          description: List of active queries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetActiveQuery'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
components:
  schemas:
    SetCustomiseInfo:
      type: object
      properties:
        key:
          type: string
          description: Key of the field to be updated
        value:
          type: string
          description: Value of the field to be updated
    AddMember:
      description: UserMember options
      type: object
      properties:
        perm:
          type: integer
          description: Default permission of the new member.
          nullable: false
          minimum: 0
          maximum: 2
          example: 0
    Analysis:
      type: object
      properties:
        bucket:
          type: boolean
          description: Should bucket analysis be run on this upload
        copyright_email_author:
          type: boolean
          description: Should Copyright/Email/URL/Author Analysis be run on this upload.
        ecc:
          type: boolean
          description: Should ECC Analysis be run on this upload.
        patent:
          type: boolean
          description: Should IPRA Analysis be run on this upload.
        keyword:
          type: boolean
          description: Should keyword Analysis be run on this upload.
        mime:
          type: boolean
          description: Should MIME Analysis be run on this upload.
        monk:
          type: boolean
          description: Should Monk Analysis be run on this upload.
        nomos:
          type: boolean
          description: Should Nomos Analysis be run on this upload.
        ojo:
          type: boolean
          description: Should OJO Analysis be run on this upload.
        package:
          type: boolean
          description: Should Package Analysis be run on this upload.
        reso:
          type: boolean
          description: Should REUSE.Software Analysis be run on this upload.
        heritage:
          type: boolean
          description: Should Software Heritage Analysis be run on this upload.
        compatibility:
          type: boolean
          description: Should Compatibility Analysis be run on this upload.
    User:
      type: object
      properties:
        id:
          type: integer
          description: ID of the user
        name:
          type: string
          description: Unique username
        description:
          type: string
          description: Description of the user
        email:
          type: string
          description: Email of the user, needs to be unique and is required
        accessLevel:
          type: string
          enum:
          - none
          - read_only
          - read_write
          - clearing_admin
          - admin
        rootFolderId:
          type: number
          format: int
          description: root folder id of the user
        emailNotification:
          type: boolean
          description: enable email notification when upload scan completes
        defaultGroup:
          type: integer
          description: Default group id of the user
        agents:
          $ref: '#/components/schemas/Analysis'
        defaultBucketpool:
          description: Default bucket pool id
          type: integer
          nullable: true
      required:
      - id
    Obligation:
      description: Obligation information
      type: object
     

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