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.

      
      <br><br> One more thing:

       If you're using Python (v3.9 or higher), the easiest way to integrate our API is through our SDK - just run `pip install vaarhaft-fraudscanner` and you're good to go! [(more info here)](https://pypi.org/project/vaarhaft-fraudscanner/)
  version: v2.3.4
  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:
  /v2/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.

         *Note that due to our compute heavy analysis features, requests with many or large files can take longer than usual to complete. Thus, the request timeout is set to an extended period of 120s, although this is much longer than the average request will take.*
      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.
        - in: header
          name: language
          required: false
          schema:
            type: string
            enum:
              - de
              - en
              - pl
          description: >-
            The language setting for the request; currently only used for the
            language of the generated analysis report. Defaults to 'de'
            (German).
        - in: header
          name: Accept
          required: false
          schema:
            type: string
            enum:
              - application/json
              - multipart/mixed
              - '*/*'
          example: application/json
          description: >
            Optionally set the desired response media type. Use
            `application/json` for a JSON response with Base64-encoded
            attachments grouped by category (actual files: PDFs, PNGs, etc.; no
            ZIP bundles). If the header is not set, or if `multipart/mixed` or
            `*/*` is set, the server will respond with JSON plus one or more ZIP
            attachments (e.g., heatmaps, reports), combined in a multipart
            response. This is the standard way to consume the FraudScanner API.
      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/BaseResponseMultipart'
                  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, as well as a visual overview of the detected changes
                        - 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: binary
        '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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - the request was not formed correctly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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:
    Attachment:
      type: object
      properties:
        filename:
          type: string
          description: Original filename of the attachment
          example: '[HEATMAP]-3a35b619-4157-48cc-8e9a-443bd55f1edc.png'
        mime_type:
          type: string
          description: MIME type of the attachment
          example: image/png
          default: application/octet-stream
        data_b64:
          type: string
          format: base64
          description: Base64-encoded content of the attachment
          example: iVBORw0KGgoAAAANSUhEUgAA...
      required:
        - filename
        - mime_type
        - data_b64
    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)
        suspicion_level:
          type: string
          description: >-
            An indicator as to how suspicious the contents of the file are. Is
            calculated from the suspicion levels of the contained items.
          example: Yellow
          enum:
            - Green
            - Yellow
            - Red
        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_analyses:
              type: object
              nullable: true
              properties:
                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 be equal to 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.
                        Any extracted versions will be returned as attachment.
                    error:
                      type: boolean
                      description: Whether an error occured during PDF version analysis.
                      example: false
                structure:
                  type: object
                  nullable: true
                  description: >-
                    Information extracted about a PDF file's structure (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 created and
                        modified.
                      items:
                        type: string
                        format: date
                        example: '2025-02-24 19:39:03 +01:00'
                    inconsistent_metadata_dates:
                      type: boolean
                      example: false
                      description: >-
                        Whether the found dates of creation and modification in
                        the different PDF metadata formats of the file are
                        inconsistent or suspicious, potentially indicating
                        tampering. If nothing is out of the ordinary, this is
                        set to false.
                    editing_tools:
                      type: array
                      description: The detected tools used to modify the PDF file.
                      items:
                        type: string
                        example: Adobe Acrobat
                    annotation_layer_found:
                      type: boolean
                      example: true
                      description: >-
                        Indicates whether an annotation layer (a PDF feature)
                        was found in the file. This is a normal part of many PDF
                        documents, e.g. for interaction purposes, but may in
                        some cases indicate tampering.
                    error:
                      type: boolean
                      description: Whether an error occured during structural PDF analysis.
                      example: false
        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.
        item_type:
          type: string
          example: image
          enum:
            - image
            - document
          description: The type of the item; for image items typically "image".
        position:
          type: string
          nullable: true
          example: Page 1
          description: >-
            The position of the item within the file (e.g., "Page 1"). May be
            null if not applicable.
        suspicion_level:
          type: string
          description: >-
            An indicator as to how suspicious the contents of the item are. Is
            calculated from the suspicion levels of the individual analyses.
          example: Yellow
          enum:
            - Green
            - Yellow
            - Red
        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:
                inferences:
                  type: object
                  description: >-
                    Inferences across items regarding their metadata. Only
                    applicable if multiple items contain relevant metadata, such
                    as GPS-, timestamp- or model-data.
                  properties:
                    distance:
                      type: object
                      description: >-
                        Inferences regarding the distances calculated between
                        the places where the items/images were taken, according
                        to their GPS metadata.
                      properties:
                        highest_distance_in_km:
                          type: number
                          description: >-
                            The highest distance in kilometers between this and
                            another given item in the request, according to
                            their GPS metadata. High values may hint at
                            inconsistencies and will trigger flagging.
                          example: 153.9
                        highest_distance_item_uuid:
                          type: string
                          description: >-
                            The UUID of another item in the request, if any,
                            that has the highest distance to this item. Only
                            applies if this item has GPS metadata and at least
                            one more item in the request does too.
                          example: d25a844c-43f9-470e-8b55-0a55639072d9
                    gps_outlier:
                      type: object
                      description: >-
                        Inferences regarding clustered GPS data of all items
                        that possess the relevant metadata.
                      properties:
                        is_geographical_outlier:
                          type: boolean
                          description: >-
                            Whether the item's GPS metadata is an outlier,
                            compared to other items with GPS metadata in the
                            request.
                          example: true
                        distance_from_mean_in_km:
                          type: number
                          description: >-
                            The distance in kilometers from the cluster-mean
                            that was calculated from all items' metadata.
                          example: 402.12
                    model_consistency:
                      type: object
                      description: >-
                        Inferences regarding the used model of camera, phone, or
                        other device used to take the image, as noted in the
                        image's metadata.
                      properties:
                        is_consistent:
                          type: boolean
                          description: >-
                            Whether or not the model of the used
                            camera/phone/etc. is consistent across items that
                            possess the relevant metadata information.
                          example: true
                    time_consistency:
                      type: object
                      description: >-
                        Inferences regarding GPS metadata in combination with
                        timestamp metadata.
                      properties:
                        is_possible:
                          type: boolean
                          description: >-
                            Whether or not it is plausible that all images were
                            taken by one individual, taking into account all
                            available timestamps and corresponding GPS data. An
                            example would be; "According to their GPS metadata,
                            Image1 was taken in Berlin, Image2 was taken in
                            Munich. Their timestamps are only 20min apart,
                            however. Thus, it was likely someone else that took
                            one of the images."
                          example: true
                        implied_speed_kmh:
                          type: number
                          description: >-
                            The speed, according to GPS and timestamp metadata,
                            that the individual taking the images must have
                            traveled at, at least. High values may hint at
                            inconsistencies and will trigger flagging.
                          example: 26.4
                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.
                is_screenshot:
                  type: boolean
                  description: |
                    Indicates whether the image is likely a screenshot.
                  example: false
                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 not
                      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:
                matches:
                  type: array
                  description: List of matching images, if any were found.
                  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.
            phoneNumber:
              type: object
              description: >-
                Results for the detection of phone numbers within the image.
                (Note that this feature will NOT be part of the response if you
                do not have this feature enabled!)
              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.
            qrCode:
              type: object
              description: >-
                Results for the detection of QR codes within the image. (Note
                that this feature will NOT be part of the response if you do not
                have this feature enabled!)
              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: >-
                Results for the detection of URLs/links within the image. (Note
                that this feature will NOT be part of the response if you do not
                have this feature enabled!)
              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.
        item_type:
          type: string
          example: document
          enum:
            - image
            - document
          description: The type of the item; for document items typically "document".
        position:
          nullable: true
          type: string
          example: Page 1
          description: >-
            The position of the item within the file (e.g., "Page 1"). May be
            null if not applicable.
        suspicion_level:
          type: string
          description: >-
            An indicator as to how suspicious the contents of the item are. Is
            calculated from the suspicion levels of the individual analyses.
          example: Yellow
          enum:
            - Green
            - Yellow
            - Red
        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
    BaseResponseMultipart:
      type: object
      properties:
        suspicion_level:
          type: string
          description: >-
            An indicator as to how suspicious the contents of the request were.
            Is calculated from the suspicion levels of the contained files.
          enum:
            - Green
            - Yellow
            - Red
        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
        modelVersions:
          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.
        tokensConsumed:
          type: integer
          description: >-
            The amount of API tokens that were consumed by this request,
            depending for example on the number and types of processed files.
          example: 12
    BaseResponse:
      type: object
      properties:
        suspicion_level:
          type: string
          description: >-
            An indicator as to how suspicious the contents of the request were.
            Is calculated from the suspicion levels of the contained files.
          enum:
            - Green
            - Yellow
            - Red
        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
        modelVersions:
          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.
        tokensConsumed:
          type: integer
          description: >-
            The amount of API tokens that were consumed by this request,
            depending for example on the number and types of processed files.
          example: 12
        attachments:
          type: object
          description: >
            Map of 'categories-to-lists' for attachment objects (only relevant
            for pure JSON responses; see 'Accept'-header). Attachments are
            base64 encoded strings of the raw files. Categories:
              - analysis_report (PDF files)
              - heatmaps (PNG files)
              - thumbnails (PNG files)
              - reverse_search_downloads (different formats)
              - pdf_versions (PDF files)
          properties:
            heatmaps:
              type: array
              items:
                $ref: '#/components/schemas/Attachment'
              example:
                - filename: '[HEATMAP]-3a35b619-4157-48cc-8e9a-443bd55f1edc.png'
                  mime_type: image/png
                  data_b64: ...
                - filename: '[HEATMAP]-71bcd34e-025b-4efa-93f7-fac9f754c02c.png'
                  mime_type: image/png
                  data_b64: ...
            analysis_report:
              type: array
              items:
                $ref: '#/components/schemas/Attachment'
              example:
                - filename: '[ANALYSIS-REPORT]-90211b82-a602-48b5-9cdf-2f189abbe7e7.pdf'
                  mime_type: application/pdf
                  data_b64: ...
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          example: Some error details.
          description: Details about why the request was not successful.
