openapi: 3.0.0
info:
  title: VAARHAFT API
  description: >
    API for image and document verification.

     Send us your files in a ZIP archive through a request like below, and we verify them for you.
    You can give us images (like JPEG, PNG, ...) or PDF documents - we extract
    relevant items like embedded images or document scans automatically.

     You will get back a response where we detail exactly what the results of our different analyses are - and if your file is suspicious. 

     The results are packaged in a clean, structured JSON response like below, that is easy to understand, read and integrate. Additionally, depending on the results, we
    may send you one or multiple ZIP attachments containing additional results
    or indicators, like heatmaps that show you where your files have been
    edited.

     We can even generate an evaluation report for you, which shows you everything we found in an intuitive way that everyone, even without
    technical knowledge, can understand.
  version: 2.0.0
  contact:
    email: team@vaarhaft.com
    url: https://vaarhaft.com
  x-upload-info:
    maxUploadSize: 10MB
    supportedFormats:
      - jpg
      - jpeg
      - png
      - tiff
      - heic
      - pdf
    note: We extract embedded images in PDF files.
  x-response-info:
    note: >
      The JSON response (BaseResponse) contains the analysis results.
      Attachments (ZIP files) are provided as separate parts in a
      multipart/mixed response.
servers:
  - url: https://api.vaarhaft.com
paths:
  /fraudScanner:
    post:
      operationId: AnalyseFile
      tags:
        - FraudScanner
      summary: Upload a ZIP file for fraud analysis
      description: >
        This endpoint allows you to upload a ZIP file to analyze contained image
        and document files in the context of a specific case.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Request'
      parameters:
        - in: header
          name: x-api-key
          required: true
          schema:
            type: string
          description: The API key for authentication.
        - in: header
          name: caseNumber
          required: true
          schema:
            type: string
          description: >-
            A case number to assign to the request. Typically matches the one
            that you use internally to track the files you're sending us.
        - in: header
          name: issueDate
          required: false
          schema:
            type: string
            format: date
          description: The issue date of the case, if available.
      responses:
        '200':
          description: Success. The file was successfully uploaded and processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
            multipart/mixed:
              schema:
                type: object
                properties:
                  jsonResponse:
                    $ref: '#/components/schemas/BaseResponse'
                  attachments:
                    type: array
                    description: >
                      The ZIP files containing attachments generated as part of
                      the analysis process.

                       Depending on the results and your personalised configuration, this may include:
                        - An analysis report generated by us (in PDF format), showing you what we found in detail and in an intuitive, human readable format
                        - Previous versions of PDF files we were able to restore
                        - Thumbnails for images and document scans extracted from PDF files
                        - Heatmap overlays, showing where editing was likely done in an image or document
                    items:
                      type: string
                      format: bytes
        '400':
          description: >-
            Input validation has failed (e.g. the provided issueDate is not in
            an allowed format or caseNumber is missing).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: >-
            The provided ZIP file exceeded the maximum size of 10MB. The request
            was automatically rejected.
        '429':
          description: Allocated API quota has been reached / out of credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: >-
            Internal server error. Something went wrong on the server while
            processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '501':
          description: Configuration issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    Request:
      required:
        - file
      type: object
      properties:
        file:
          type: string
          format: zip
          description: The ZIP file to be uploaded for analysis.
    File:
      type: object
      description: >
        The file for which the analysis was performed. Matches the naming of
        files in the ZIP archive from your request.
      properties:
        file_type:
          type: string
          description: The type of the file.
          example: PNG (image file)
        suspicious_contents:
          type: boolean
          example: true
          description: >-
            Indicates whether any of the analyses indicate that the file was
            generated or tampered with.
        file_level_analyses:
          type: object
          nullable: true
          description: >-
            A collection of analyses performed at the file level (e.g.
            structural PDF analysis). If no file-level analyses are applicable
            or conducted, this will be null.
          properties:
            pdf_metadata:
              type: object
              nullable: true
              description: >-
                Information extracted about the PDF metadata (only applicable
                for PDF files, else this will be null).
              properties:
                mod_dates:
                  type: array
                  description: The detected dates at which the PDF file was modified.
                  items:
                    type: string
                    format: date
                    example: 11-02-2025
                editing_tools:
                  type: array
                  description: The detected tools used to modify the PDF file.
                  items:
                    type: string
                    example: Adobe Acrobat
                xmlModDate_later_infoModDate:
                  type: boolean
                  example: false
                  description: >-
                    Whether a modification date found in extra, XML specified
                    metadata of the PDF is later than the modification date
                    found in the 'native' PDF metadata. If this is true, it
                    could indicate tampering.
            pdf_versions:
              type: object
              nullable: true
              description: >-
                Information about previous versions of the PDF (only applicable
                for PDF files, else this will be null). The number of found
                versions may not always equal the number of successfully
                extracted versions, as not all detectable methods of tampering
                allow for restoration of previous versions.
              properties:
                found:
                  type: integer
                  example: 2
                  description: The number of previous versions found.
                extracted:
                  type: integer
                  example: 1
                  description: The number of previous versions successfully extracted.
        items:
          type: array
          description: >
            Array of items that were analysed in the file (either images or
            documents).
          items:
            oneOf:
              - $ref: '#/components/schemas/ImageItem'
              - $ref: '#/components/schemas/DocumentItem'
    ImageItem:
      type: object
      description: Represents an image item extracted from the file.
      properties:
        id:
          type: string
          format: UUID
          example: f32dc630-47c1-4596-8cba-9d1584674c17
          description: Unique identifier for the image item.
        position:
          type: string
          nullable: true
          example: Page 1
          description: >-
            The position of the item within the file (e.g., "Page 1"). May be
            null.
        item_type:
          type: string
          example: image
          enum:
            - image
            - document
          description: The type of the item; for image items typically "image".
        analyses:
          type: object
          description: Analysis results for the image item.
          properties:
            imageQuality:
              type: object
              description: Results of the image quality check.
              properties:
                result:
                  type: boolean
                  example: true
                  description: Indicates if the image meets quality requirements.
                error:
                  type: boolean
                  example: false
                  description: >-
                    Indicates if an error occurred during the image quality
                    analysis.
            metadata:
              type: object
              description: Extracted metadata of the image.
              properties:
                analyzed:
                  type: object
                  description: Contains analyzed metadata.
                  properties:
                    creationDate:
                      type: object
                      description: Contains creation date information.
                      properties:
                        cDate:
                          type: string
                          description: >-
                            The creation date of the image (or "-" if not
                            found).
                        cTime:
                          type: string
                          description: >-
                            The creation time of the image (or "-" if not
                            found).
                        isSus:
                          type: boolean
                          description: Indicates if the creation date is suspicious.
                        diffInDays:
                          type: integer
                          description: >-
                            Difference in days between the creation date and a
                            reference date.
                        isTodayUsed:
                          type: boolean
                          description: Indicates if the current date was used.
                        refDate:
                          type: string
                          description: The reference date for checking the creation date.
                    imgRanking:
                      type: string
                      nullable: true
                      description: Ranking of the image based on its analysis. May be null.
                    fieldsMarkedSus:
                      type: object
                      additionalProperties: false
                      description: Suspicious fields marked in the metadata.
                GPSInfo:
                  type: object
                  additionalProperties: false
                  description: GPS information of the image, if available.
                raw:
                  type: object
                  description: Raw metadata containing detailed information.
                  properties:
                    Rating:
                      type: object
                      additionalProperties: false
                      description: Rating of the image metadata.
                    Dates:
                      type: object
                      description: Contains date entries from the metadata.
                    Other:
                      type: array
                      items:
                        type: object
                      description: Other metadata found during analysis.
                error:
                  type: boolean
                  example: false
                  description: Indicates if an error occurred during metadata analysis.
                enabled:
                  type: boolean
                  example: true
                  description: Indicates if metadata analysis was enabled.
            c2pa:
              type: object
              description: Results of the C2PA metadata / Content Credentials analysis.
              properties:
                c2pa_extracted:
                  type: boolean
                  example: true
                  description: Indicates if C2PA data was extracted.
                reason:
                  example: C2PA data found
                  type: string
                  description: Explanation for why C2PA data was extracted / not extracted.
                data:
                  type: object
                  nullable: true
                  description: >-
                    Detailed information regarding the extracted C2PA data. If
                    no data was extracted, this will be null.
                  properties:
                    is_valid:
                      type: boolean
                      example: true
                      description: >-
                        Indicates if the C2PA data is valid. This will check,
                        for example, if the signature matches the content.
                    suspicious_keywords:
                      type: array
                      items:
                        type: string
                      description: Keywords that may indicate tampering.
                    validation_status_base64:
                      type: string
                      format: base64
                      description: Base64 encoded validation status.
                    manifest_base64:
                      type: string
                      format: base64
                      description: Base64 encoded manifest of the C2PA data.
                error:
                  type: boolean
                  example: false
                  description: Indicates if an error occurred during C2PA analysis.
                enabled:
                  type: boolean
                  example: true
                  description: Indicates if C2PA analysis was enabled.
            generatedDetection:
              type: object
              description: Detects if the image was generated by an AI.
              properties:
                predictedClassName:
                  type: string
                  description: >-
                    Predicted class name ("gen" for generated or "real" for
                    non-generated).
                  example: real
                  enum:
                    - gen
                    - real
                  x-enumDescriptions:
                    gen: >-
                      The detection model decided that the item is likely
                      generated
                    real: >-
                      The detection model decided that the item is likely
                      non-generated
                confidence:
                  type: number
                  example: 0.99
                  description: Confidence level of the prediction.
                error:
                  type: boolean
                  example: false
                  description: Indicates if an error occurred during generated detection.
                enabled:
                  type: boolean
                  example: true
                  description: Indicates if generated detection was activated.
            tamperedDetection:
              type: object
              description: Detects if the image was tampered with.
              properties:
                predictedClassName:
                  type: string
                  description: >-
                    Predicted class name ("tp" for tampered/edited or "real" for
                    real).
                  example: tp
                  enum:
                    - tp
                    - real
                  x-enumDescriptions:
                    tp: The detection model decided that the item is likely edited
                    real: The detection model decided that the item is likely real
                confidence:
                  type: number
                  description: Confidence level of the prediction.
                  example: 0.99
                error:
                  type: boolean
                  description: Indicates if an error occurred during tampered detection.
                  example: false
                enabled:
                  type: boolean
                  description: Indicates if tampered detection was activated.
                  example: true
            doubletCheck:
              type: object
              description: Results of the duplicate comparison.
              properties:
                result:
                  type: boolean
                  description: Indicates if the image was already seen.
                  example: true
                caseNumber:
                  type: string
                  description: Case number of the identified duplicate.
                  example: Case 321B
                internal:
                  type: boolean
                  description: Indicates if the duplicate is internal.
                  example: true
                error:
                  type: boolean
                  description: Indicates if an error occurred during the duplicate check.
                  example: false
                enabled:
                  type: boolean
                  description: Indicates if duplicate check was activated.
                  example: true
            reverseSearch:
              type: object
              description: Results of the reverse image search.
              properties:
                result:
                  type: boolean
                  example: true
                  description: Indicates if a similar image was found online.
                matches:
                  type: array
                  description: List of matching images.
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                        example: https://example.com
                        description: URL of the found image.
                      score:
                        type: number
                        example: 98
                        description: Matching score (0-100).
                error:
                  type: boolean
                  example: false
                  description: Indicates if an error occurred during reverse search.
                enabled:
                  type: boolean
                  example: true
                  description: Indicates if reverse search was enabled.
            foreignObjects:
              type: object
              description: Groups detections of foreign objects.
              properties:
                phone_number:
                  type: object
                  description: Detection results for phone numbers.
                  properties:
                    text:
                      type: string
                      example: +49 123 456789
                      description: Detected phone number (if any).
                    result:
                      type: boolean
                      example: true
                      description: Indicates if a phone number was found.
                    error:
                      type: boolean
                      example: false
                      description: >-
                        Indicates if an error occurred during phone number
                        detection.
                    enabled:
                      type: boolean
                      example: true
                      description: Indicates if phone number detection was enabled.
                qr_code:
                  type: object
                  description: Detection results for QR codes.
                  properties:
                    result:
                      type: boolean
                      example: true
                      description: Indicates if a QR code was found.
                    error:
                      type: boolean
                      example: false
                      description: Indicates if an error occurred during QR code detection.
                    enabled:
                      type: boolean
                      example: true
                      description: Indicates if QR code detection was enabled.
                link:
                  type: object
                  description: Detection results for links.
                  properties:
                    text:
                      type: string
                      example: https://www.example.com
                      description: The detected URL (if any).
                    result:
                      type: boolean
                      example: true
                      description: Indicates if a URL was found.
                    error:
                      type: boolean
                      example: false
                      description: Indicates if an error occurred during link detection.
                    enabled:
                      type: boolean
                      example: true
                      description: Indicates if link detection was enabled.
    DocumentItem:
      type: object
      description: Represents a document item extracted from the file.
      properties:
        id:
          type: string
          format: UUID
          example: 6e48cce8-a7bd-4e4c-928c-f8fbcce8f10d
          description: Unique identifier for the document item.
        position:
          nullable: true
          type: string
          example: Page 1
          description: >-
            The position of the item within the file (e.g., "Page 1"). May be
            null.
        item_type:
          type: string
          example: document
          enum:
            - image
            - document
          description: The type of the item; for document items typically "document".
        analyses:
          type: object
          description: Analysis results for the document item.
          properties:
            tamperedDetection:
              type: object
              description: Detects if the document was tampered with.
              properties:
                predictedClassName:
                  type: string
                  example: real
                  enum:
                    - tp
                    - real
                  x-enumDescriptions:
                    tp: The detection model decided that the item is likely edited
                    real: The detection model decided that the item is likely real
                confidence:
                  type: number
                  example: 0.9742
                error:
                  type: boolean
                  example: false
                enabled:
                  type: boolean
                  example: true
    BaseResponse:
      type: object
      properties:
        Files:
          type: object
          description: A mapping of filename to file analysis results.
          additionalProperties:
            x-additionalPropertiesName: <FileID>
            $ref: '#/components/schemas/File'
        caseNumber:
          type: string
          description: The case number assigned to the request.
          example: Case 123A
        sessionId:
          type: string
          format: UUID
          description: A unique identifier generated for the request.
          example: 5a8d8fd2-3317-4964-8298-caa96cd5cfa3
        model_versions:
          type: object
          description: Overview of the internal VAARHAFT AI models used for classification.
          properties:
            generatedModelVersion:
              type: string
              example: vh-gen-uranus
              description: The VAARHAFT AI model used for detection of AI generated images.
            tamperedModelVersion:
              type: string
              example: vh-tp-venus
              description: The VAARHAFT AI model used for detection of edited images.
            semanticModelVersion:
              type: string
              example: vh-sem-mars
              description: The VAARHAFT AI model used for semantic analysis of images.
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          example: Your allocated API quota of 2000 credits has been reached.
          description: Details about why the request was not successful.
