openapi: 3.0.3
info:
  title: Trust Matrix API
  description: |
    REST API for Trust Matrix - AI-powered trust administration platform.
    
    ## Authentication
    All API requests require authentication using Bearer tokens.
    Include the header: `Authorization: Bearer <your_api_key>`
    
    ## Rate Limits
    - Standard: 100 requests per minute
    - Enterprise: 1000 requests per minute
    
    ## Pagination
    List endpoints support pagination with `page` and `limit` parameters.
    Default limit is 20, maximum is 100.
  version: 1.0.0
  contact:
    name: API Support
    email: api@trustmatrix.io

servers:
  - url: https://api.trustos.io/v1
    description: Production
  - url: https://api.staging.trustos.io/v1
    description: Staging

tags:
  - name: Trusts
    description: Trust management endpoints
  - name: Persons
    description: Person/entity management
  - name: Assets
    description: Asset management
  - name: Transactions
    description: Transaction management
  - name: Documents
    description: Document management
  - name: Tasks
    description: Task management
  - name: Compliance
    description: KYC/AML compliance
  - name: AI Agents
    description: AI-powered document generation and extraction

paths:
  # ============================================
  # TRUSTS
  # ============================================
  /trusts:
    get:
      tags:
        - Trusts
      summary: List all trusts
      description: Retrieve a paginated list of trusts
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, active, suspended, terminated]
        - name: trust_type
          in: query
          schema:
            type: string
            enum: [discretionary, bare, interest_in_possession, discounted_gift, loan]
        - name: search
          in: query
          description: Search by name or reference
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Trust'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
    
    post:
      tags:
        - Trusts
      summary: Create a new trust
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrustCreate'
      responses:
        '201':
          description: Trust created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trust'
        '400':
          $ref: '#/components/responses/BadRequest'

  /trusts/{id}:
    get:
      tags:
        - Trusts
      summary: Get trust by ID
      parameters:
        - $ref: '#/components/parameters/TrustId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustDetail'
        '404':
          $ref: '#/components/responses/NotFound'
    
    patch:
      tags:
        - Trusts
      summary: Update trust
      parameters:
        - $ref: '#/components/parameters/TrustId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrustUpdate'
      responses:
        '200':
          description: Trust updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trust'
    
    delete:
      tags:
        - Trusts
      summary: Delete trust
      description: Soft delete - sets status to terminated
      parameters:
        - $ref: '#/components/parameters/TrustId'
      responses:
        '204':
          description: Trust deleted

  /trusts/{id}/parties:
    get:
      tags:
        - Trusts
      summary: Get trust parties
      parameters:
        - $ref: '#/components/parameters/TrustId'
        - name: role
          in: query
          schema:
            type: string
            enum: [settlor, trustee, beneficiary, protector]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrustParty'
    
    post:
      tags:
        - Trusts
      summary: Add party to trust
      parameters:
        - $ref: '#/components/parameters/TrustId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrustPartyCreate'
      responses:
        '201':
          description: Party added

  # ============================================
  # PERSONS
  # ============================================
  /persons:
    get:
      tags:
        - Persons
      summary: List all persons
      parameters:
        - name: kyc_status
          in: query
          schema:
            type: string
            enum: [not_started, in_progress, pending_review, verified, expired, failed]
        - name: risk_rating
          in: query
          schema:
            type: string
            enum: [low, medium, high]
        - name: search
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Person'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
    
    post:
      tags:
        - Persons
      summary: Create a new person
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonCreate'
      responses:
        '201':
          description: Person created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'

  /persons/{id}:
    get:
      tags:
        - Persons
      summary: Get person by ID
      parameters:
        - $ref: '#/components/parameters/PersonId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonDetail'
    
    patch:
      tags:
        - Persons
      summary: Update person
      parameters:
        - $ref: '#/components/parameters/PersonId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonUpdate'
      responses:
        '200':
          description: Person updated

  # ============================================
  # ASSETS
  # ============================================
  /trusts/{id}/assets:
    get:
      tags:
        - Assets
      summary: Get trust assets
      parameters:
        - $ref: '#/components/parameters/TrustId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
    
    post:
      tags:
        - Assets
      summary: Add asset to trust
      parameters:
        - $ref: '#/components/parameters/TrustId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetCreate'
      responses:
        '201':
          description: Asset created

  /assets/{id}/valuations:
    post:
      tags:
        - Assets
      summary: Add valuation to asset
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValuationCreate'
      responses:
        '201':
          description: Valuation added

  # ============================================
  # TRANSACTIONS
  # ============================================
  /trusts/{id}/transactions:
    get:
      tags:
        - Transactions
      summary: Get trust transactions
      parameters:
        - $ref: '#/components/parameters/TrustId'
        - name: type
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: from_date
          in: query
          schema:
            type: string
            format: date
        - name: to_date
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
    
    post:
      tags:
        - Transactions
      summary: Create transaction
      parameters:
        - $ref: '#/components/parameters/TrustId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionCreate'
      responses:
        '201':
          description: Transaction created

  /transactions/{id}/approve:
    post:
      tags:
        - Transactions
      summary: Approve transaction
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                notes:
                  type: string
      responses:
        '200':
          description: Transaction approved

  # ============================================
  # DOCUMENTS
  # ============================================
  /documents:
    get:
      tags:
        - Documents
      summary: List documents
      parameters:
        - name: trust_id
          in: query
          schema:
            type: string
            format: uuid
        - name: person_id
          in: query
          schema:
            type: string
            format: uuid
        - name: document_type
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
    
    post:
      tags:
        - Documents
      summary: Upload document
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                trust_id:
                  type: string
                  format: uuid
                person_id:
                  type: string
                  format: uuid
                document_type:
                  type: string
                title:
                  type: string
      responses:
        '201':
          description: Document uploaded

  /documents/{id}/download:
    get:
      tags:
        - Documents
      summary: Download document
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Document file
          content:
            application/pdf:
              schema:
                type: string
                format: binary

  # ============================================
  # TASKS
  # ============================================
  /tasks:
    get:
      tags:
        - Tasks
      summary: List tasks
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, in_progress, completed, overdue]
        - name: priority
          in: query
          schema:
            type: string
            enum: [low, medium, high, critical]
        - name: assigned_to
          in: query
          schema:
            type: string
            format: uuid
        - name: trust_id
          in: query
          schema:
            type: string
            format: uuid
        - name: due_before
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    
    post:
      tags:
        - Tasks
      summary: Create task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreate'
      responses:
        '201':
          description: Task created

  /tasks/{id}/complete:
    post:
      tags:
        - Tasks
      summary: Mark task as complete
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Task completed

  # ============================================
  # COMPLIANCE
  # ============================================
  /persons/{id}/kyc/check:
    post:
      tags:
        - Compliance
      summary: Run KYC check
      description: Trigger eIDV and screening checks
      parameters:
        - $ref: '#/components/parameters/PersonId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                check_types:
                  type: array
                  items:
                    type: string
                    enum: [eidv, pep, sanctions, adverse_media]
      responses:
        '202':
          description: Check initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  check_id:
                    type: string
                    format: uuid
                  status:
                    type: string

  /persons/{id}/kyc/status:
    get:
      tags:
        - Compliance
      summary: Get KYC status
      parameters:
        - $ref: '#/components/parameters/PersonId'
      responses:
        '200':
          description: KYC status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KYCStatus'

  /compliance/alerts:
    get:
      tags:
        - Compliance
      summary: List compliance alerts
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [open, reviewing, cleared, confirmed]
        - name: alert_type
          in: query
          schema:
            type: string
            enum: [pep_match, sanctions_match, adverse_media]
      responses:
        '200':
          description: Successful response

  # ============================================
  # AI AGENTS
  # ============================================
  /ai/documents/generate:
    post:
      tags:
        - AI Agents
      summary: Generate document using AI
      description: Generate trust documents using AI (trust deeds, minutes, etc.)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - template_type
                - input_data
              properties:
                template_type:
                  type: string
                  enum: [trust_deed, trustee_minutes, distribution_resolution, letter_of_wishes, trustee_appointment, trustee_retirement]
                trust_id:
                  type: string
                  format: uuid
                input_data:
                  type: object
                  description: Template-specific input data
      responses:
        '202':
          description: Generation started
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                    format: uuid
                  status:
                    type: string

  /ai/documents/jobs/{id}:
    get:
      tags:
        - AI Agents
      summary: Get document generation job status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum: [pending, processing, completed, failed]
                  document_id:
                    type: string
                    format: uuid
                  error:
                    type: string

  /ai/kyc/extract:
    post:
      tags:
        - AI Agents
      summary: Extract data from ID document
      description: Use AI vision to extract data from passport, driving licence, etc.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - document_type
              properties:
                file:
                  type: string
                  format: binary
                document_type:
                  type: string
                  enum: [passport, driving_licence, national_id, utility_bill]
                person_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Extracted data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KYCExtraction'

components:
  parameters:
    TrustId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    
    PersonId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
    
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        maximum: 100

  schemas:
    Trust:
      type: object
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: string
        name:
          type: string
        trust_type:
          type: string
        status:
          type: string
        date_established:
          type: string
          format: date
        current_value:
          type: number
        created_at:
          type: string
          format: date-time
    
    TrustDetail:
      allOf:
        - $ref: '#/components/schemas/Trust'
        - type: object
          properties:
            vesting_date:
              type: string
              format: date
            hmrc_trs_reference:
              type: string
            governing_law:
              type: string
            initial_settlement:
              type: number
            parties:
              type: array
              items:
                $ref: '#/components/schemas/TrustParty'
            assets:
              type: array
              items:
                $ref: '#/components/schemas/Asset'
    
    TrustCreate:
      type: object
      required:
        - name
        - trust_type
      properties:
        name:
          type: string
        trust_type:
          type: string
          enum: [discretionary, bare, interest_in_possession, discounted_gift, loan]
        date_established:
          type: string
          format: date
        initial_settlement:
          type: number
        governing_law:
          type: string
    
    TrustUpdate:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
        current_value:
          type: number
        hmrc_trs_reference:
          type: string
    
    TrustParty:
      type: object
      properties:
        id:
          type: string
          format: uuid
        person:
          $ref: '#/components/schemas/Person'
        role:
          type: string
        appointment_date:
          type: string
          format: date
        is_active:
          type: boolean
    
    TrustPartyCreate:
      type: object
      required:
        - person_id
        - role
      properties:
        person_id:
          type: string
          format: uuid
        role:
          type: string
          enum: [settlor, trustee, beneficiary, protector]
        appointment_date:
          type: string
          format: date
    
    Person:
      type: object
      properties:
        id:
          type: string
          format: uuid
        person_type:
          type: string
        title:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        kyc_status:
          type: string
        risk_rating:
          type: string
    
    PersonDetail:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
          properties:
            nationality:
              type: string
            email:
              type: string
            phone:
              type: string
            kyc_expiry_date:
              type: string
              format: date
            pep_status:
              type: boolean
            addresses:
              type: array
              items:
                $ref: '#/components/schemas/Address'
    
    PersonCreate:
      type: object
      required:
        - first_name
        - last_name
      properties:
        person_type:
          type: string
          default: individual
        title:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        nationality:
          type: string
        email:
          type: string
        phone:
          type: string
    
    PersonUpdate:
      type: object
      properties:
        title:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        phone:
          type: string
        kyc_status:
          type: string
        risk_rating:
          type: string
    
    Address:
      type: object
      properties:
        id:
          type: string
          format: uuid
        address_type:
          type: string
        address_line_1:
          type: string
        city:
          type: string
        postcode:
          type: string
        country:
          type: string
        is_primary:
          type: boolean
    
    Asset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        asset_type:
          type: string
        description:
          type: string
        current_value:
          type: number
        last_valuation_date:
          type: string
          format: date
        is_active:
          type: boolean
    
    AssetCreate:
      type: object
      required:
        - asset_type
        - description
      properties:
        asset_type:
          type: string
        description:
          type: string
        acquisition_value:
          type: number
        acquisition_date:
          type: string
          format: date
        custodian:
          type: string
    
    ValuationCreate:
      type: object
      required:
        - valuation_date
        - value
      properties:
        valuation_date:
          type: string
          format: date
        value:
          type: number
        source:
          type: string
    
    Transaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
        transaction_type:
          type: string
        status:
          type: string
        amount:
          type: number
        transaction_date:
          type: string
          format: date
        description:
          type: string
    
    TransactionCreate:
      type: object
      required:
        - transaction_type
        - amount
      properties:
        transaction_type:
          type: string
        amount:
          type: number
        beneficiary_id:
          type: string
          format: uuid
        description:
          type: string
        transaction_date:
          type: string
          format: date
    
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
        task_type:
          type: string
        title:
          type: string
        priority:
          type: string
        status:
          type: string
        due_date:
          type: string
          format: date
        assigned_to:
          type: string
          format: uuid
    
    TaskCreate:
      type: object
      required:
        - task_type
        - title
      properties:
        task_type:
          type: string
        title:
          type: string
        description:
          type: string
        priority:
          type: string
        due_date:
          type: string
          format: date
        assigned_to:
          type: string
          format: uuid
        trust_id:
          type: string
          format: uuid
        person_id:
          type: string
          format: uuid
    
    KYCStatus:
      type: object
      properties:
        person_id:
          type: string
          format: uuid
        status:
          type: string
        verified_date:
          type: string
          format: date
        expiry_date:
          type: string
          format: date
        checks:
          type: array
          items:
            type: object
            properties:
              check_type:
                type: string
              result:
                type: string
              completed_at:
                type: string
                format: date-time
    
    KYCExtraction:
      type: object
      properties:
        document_type:
          type: string
        confidence:
          type: number
        personal_info:
          type: object
          properties:
            full_name:
              type: object
              properties:
                value:
                  type: string
                confidence:
                  type: number
            date_of_birth:
              type: object
            nationality:
              type: object
        document_info:
          type: object
          properties:
            document_number:
              type: object
            issue_date:
              type: object
            expiry_date:
              type: object
    
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: array
                items:
                  type: object
    
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

security:
  - BearerAuth: []
