openapi: 3.0.3
info:
  title: Kontomatik Data Analysis API
  version: 1.0.0
  description: |
    Analytical services running on top of imported AIS, PDF, or uploaded data.
    Includes transaction labeling, vendor recognition, ML-based credit scoring,
    behavioral profiling, owner features, data summaries, and income
    confirmation across configurable timespans.
  contact:
    name: Kontomatik Support
    email: support@kontomatik.com
    url: https://developer.kontomatik.com/
servers:
- url: https://api.kontomatik.com/v1
  description: Production
- url: https://test.api.kontomatik.com/v1
  description: Test
security:
- ApiKeyAuth: []
tags:
- name: Labeling
  description: Transaction categorization
- name: Vendors
  description: Vendor / counterparty recognition (beta)
- name: Score
  description: ML credit scoring
- name: Profile
  description: Behavioral profiling (beta)
- name: Features
  description: Owner-level financial metrics
- name: Summary
  description: Aggregated financial summaries
- name: Income
  description: Income confirmation
- name: Aggregation
  description: Cross-source aggregation
- name: Owner
  description: Owner data lifecycle
paths:
  /labeling:
    get:
      tags: [Labeling]
      summary: Get Transaction Labels
      description: Returns transaction labels (salary, rent, utilities, etc.) for an owner's imported data.
      operationId: getLabeling
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Labels returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelingResult'
  /external-data-labeling:
    post:
      tags: [Labeling]
      summary: Label External Transactions
      description: Labels transactions submitted from non-bank sources.
      operationId: labelExternalData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalLabelingRequest'
      responses:
        '200':
          description: External labels returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelingResult'
  /vendors:
    get:
      tags: [Vendors]
      summary: Get Vendor Recognition
      description: Identifies merchant / counterparty names in transactions (beta).
      operationId: getVendors
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Vendor mapping returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorResult'
  /score:
    get:
      tags: [Score]
      summary: Get Credit Score
      description: Returns ML-based creditworthiness scoring for an owner.
      operationId: getScore
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Score returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResult'
  /profile:
    get:
      tags: [Profile]
      summary: Get Behavioral Profile
      description: Returns descriptive behavioral profile segments based on transaction patterns (beta).
      operationId: getProfile
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Profile returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResult'
  /owner-features:
    get:
      tags: [Features]
      summary: Get Owner Features
      description: Returns owner-level financial metrics derived from imported data.
      operationId: getOwnerFeatures
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Features returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResult'
  /data-summary:
    get:
      tags: [Summary]
      summary: Get Data Summary
      description: Aggregated calculations per category or account.
      operationId: getDataSummary
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Summary returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSummaryResult'
  /data-summary-catalog:
    get:
      tags: [Summary]
      summary: List Data Summary Catalog
      description: Lists supported summary categories.
      operationId: getDataSummaryCatalog
      responses:
        '200':
          description: Catalog returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    items: {type: string}
  /income-confirmation:
    get:
      tags: [Income]
      summary: Get Income Confirmation
      description: Returns income-focused aggregates across four configurable timespans.
      operationId: getIncomeConfirmation
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Income confirmation returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomeResult'
  /data/aggregated:
    get:
      tags: [Aggregation]
      summary: Get Aggregated Data
      description: Aggregates data across multiple import sessions for a single owner.
      operationId: getAggregatedData
      parameters:
      - name: ownerExternalId
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: Aggregated data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatedData'
  /data/delete:
    post:
      tags: [Owner]
      summary: Delete Owner Data
      description: Permanently removes all data for the specified owner. Default retention is 24 hours.
      operationId: deleteOwnerData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ownerExternalId]
              properties:
                ownerExternalId: {type: string}
      responses:
        '200':
          description: Data deleted
  /owner-upload:
    post:
      tags: [Owner]
      summary: Upload Owner Data
      description: Uploads custom owner / account / transaction data in XML or JSON for analysis alongside bank-sourced data.
      operationId: uploadOwnerData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnerUpload'
      responses:
        '200':
          description: Upload accepted
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  schemas:
    LabelingResult:
      type: object
      properties:
        ownerExternalId: {type: string}
        labels:
          type: array
          items:
            type: object
            properties:
              transactionId: {type: string}
              category: {type: string}
              confidence: {type: number, format: float}
    ExternalLabelingRequest:
      type: object
      required: [transactions]
      properties:
        ownerExternalId: {type: string}
        transactions:
          type: array
          items:
            type: object
            properties:
              externalId: {type: string}
              date: {type: string, format: date}
              amount: {type: number}
              currency: {type: string}
              description: {type: string}
    VendorResult:
      type: object
      properties:
        ownerExternalId: {type: string}
        vendors:
          type: array
          items:
            type: object
            properties:
              transactionId: {type: string}
              vendorName: {type: string}
              confidence: {type: number}
    ScoreResult:
      type: object
      properties:
        ownerExternalId: {type: string}
        score: {type: number}
        scoreVersion: {type: string}
        repaymentProbability: {type: number}
        explanations:
          type: array
          items: {type: string}
    ProfileResult:
      type: object
      properties:
        ownerExternalId: {type: string}
        segments:
          type: array
          items: {type: string}
        descriptors:
          type: object
          additionalProperties: {type: string}
    FeatureResult:
      type: object
      properties:
        ownerExternalId: {type: string}
        features:
          type: object
          additionalProperties: {type: number}
    DataSummaryResult:
      type: object
      properties:
        ownerExternalId: {type: string}
        summary:
          type: object
          additionalProperties:
            type: object
            properties:
              total: {type: number}
              count: {type: integer}
              average: {type: number}
    IncomeResult:
      type: object
      properties:
        ownerExternalId: {type: string}
        timespans:
          type: array
          items:
            type: object
            properties:
              window: {type: string, example: 90d}
              confirmedIncome: {type: number}
              transactionCount: {type: integer}
    AggregatedData:
      type: object
      properties:
        ownerExternalId: {type: string}
        owners:
          type: array
          items: {type: object}
        accounts:
          type: array
          items: {type: object}
        sources:
          type: array
          items: {type: string, enum: [AIS, PDF, UPLOAD]}
    OwnerUpload:
      type: object
      required: [ownerExternalId]
      properties:
        ownerExternalId: {type: string}
        owners:
          type: array
          items: {type: object}
        accounts:
          type: array
          items: {type: object}
        transactions:
          type: array
          items: {type: object}