openapi: 3.1.1
info:
  title: EMBArk API
  description: API of the firmware security scanning environment
  version: "0.3.0"
  license:
    name: "MIT License"
    identifier: "MIT"
  contact:
    name: EMBA - The security analyzer for firmware of embedded devices
    url: https://github.com/e-m-b-a

tags:
  - name: Uploader
    description: Uploader API
  - name: Status report
    description: Status report API
  - name: API Test
    description: Test API Authentication
  - name: API SBOM
    description: SBOM retrieval API

paths:
  /api/uploader:
    post:
      tags:
        - Uploader
      summary: Firmware upload and analysis
      description: Stores the provided firmware, queues a firmware analysis process with provided firmware and parameters
      operationId: uploadFirmware
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploaderResult"
            application/xml:
              schema:
                $ref: "#/components/schemas/UploaderResult"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
            application/xml:
              schema:
                $ref: "#/components/schemas/Error"
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The firmware to be analyzed
                  type: string
                  format: binary
                version:
                  type: string
                device:
                  type: array
                  items:
                    type: string
                notes:
                  type: string
                firmware_Architecture:
                  type: string
                user_emulation_test:
                  type: boolean
                system_emulation_test:
                  type: boolean
                sbom_only_test:
                  type: boolean
                scan_modules:
                  type: array
                  items:
                    type: string
              required:
                - file
  /user/api_test:
    get:
      tags:
        - API Test
      summary: Greet the API user
      description: >
        Returns a JSON greeting message to the authenticated API user.
        API key must be passed in either the `Authorization` header or the `api_key` query parameter.
      operationId: apiTest
      parameters:
        - in: query
          name: api_key
          schema:
            type: string
          required: false
          description: API key passed as a query parameter (alternative to Authorization header).
      security:
        - ApiKeyAuth: []
        - ApiKeyAuthQuery: []
      responses:
        '200':
          description: A successful response with a greeting message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Hello, johndoe!
        '401':
          description: Unauthorized - API key is missing or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing API key
  /api/sbom/{analysis_id}:
    get:
      tags:
        - API SBOM
      summary: Get SBOM as raw json
      description: Returns the SBOM of a firmware analysis in raw JSON format.
      operationId: apiSBOM
      parameters: 
        - name: analysis_id
          in: path
          required: true
          description: UUID of the analysis
          schema:
            type: string
            format: uuid
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: 
                  sbom: 
                    type: object
  /status_report/{analysis_id}:
    get:
      tags:
        - Status report
      summary: Get analysis status report
      description: >
        Retrieves the report of a firmware analysis.

        - If the analysis is still **running**, returns its progress

        - If the analysis has **failed**, returns failure message, queues zip file generation. Returns the download link on subsequent request

        - If analysis is **finished**, queues zip file generation. Returns the download link on subsequent request

      operationId: getStatusReport
      parameters:
        - name: analysis_id
          in: path
          required: true
          description: UUID of the analysis
          schema:
            type: string
            format: uuid
      security:
        - ApiKeyAuth: []
      responses:
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
                    example: Internal server error.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: Forbidden
                  error:
                    type: string
                    example: You're not allowed to access this resource.
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: Analysis failed. The logs are being zipped and will soon be ready for download.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
                    example: The analysis with the provided UUID doesn't exist.
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: running
                  message:
                    type: string
                    example: Analysis has been running since 2025-05-11 19:42:28.986026+00:00
                  completion:
                    type: string
                    example: 32.8125% finished
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: finished
                  message:
                    type: string
                    example: Analysis finished successfully in 0:23:45.
                  download_url:
                    type: string
                    example: http://embark.local/download_zipped/<analysis_id>

components:
  schemas:
    UploaderResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - success
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
    ApiKeyAuthQuery:
      type: apiKey
      in: query
      name: api_key