openapi: 3.1.0
info:
  title: Light Horse Account API
  version: 1.0.0
  description: API for managing account properties, documents, and analytics.
  contact:
    name: Light Horse Support
    url: https://www.lighthorse.io
    email: support@lighthorse.io
  license:
    name: Proprietary
tags:
  - name: Documents
    description: Account documents and statements
servers:
  - url: https://interface.lighthorse.io/open-api/account-center/v1
    description: Production with cryptographic signatures authentication
  - url: https://interface.lighthorse.io/api/account-center/v1
    description: Production with access tokens authentication
security:
  - SignatureAuth: []

components:
  securitySchemes:
    SignatureAuth:
      type: apiKey
      in: header
      name: X-Signature
      description: Cryptographic signature authentication

paths:
  /document/{accountId}/documents:
    get:
      operationId: getDocuments
      tags: [Documents]
      summary: List Documents
      description: Returns a paginated list of account documents filtered by date range and document type.
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
          description: Account identifier
          example: "lh000000000001"
        - name: startDate
          in: query
          required: false
          schema:
            type: integer
          description: Start of date range as Unix timestamp in milliseconds
          example: 955695962000
        - name: endDate
          in: query
          required: false
          schema:
            type: integer
          description: End of date range as Unix timestamp in milliseconds
          example: 1776150362000
        - name: pageNo
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (1-based)
          example: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of records per page
          example: 10
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: Document type filter (e.g. FORM_1099_Q, STATEMENT)
          example: "FORM_1099_Q"
      responses:
        '200':
          description: Paginated list of documents
          content:
            application/json:
              schema:
                type: object
                required:
                  - s
                  - d
                properties:
                  s:
                    type: string
                    enum: [ok, error]
                    description: Response status indicator
                  d:
                    type: object
                    required:
                      - pageNo
                      - pageSize
                      - totalElement
                      - totalPage
                      - data
                    properties:
                      pageNo:
                        type: integer
                        description: Current page number
                        example: 1
                      pageSize:
                        type: integer
                        description: Number of records per page
                        example: 10
                      totalElement:
                        type: integer
                        description: Total number of matching documents
                        example: 149
                      totalPage:
                        type: integer
                        description: Total number of pages
                        example: 1
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            clearAccount:
                              type: string
                              description: Clearing account number
                              example: "XXXXXXXX"
                            documentDate:
                              type: integer
                              description: Document date as Unix timestamp in milliseconds
                              example: 1667188800000
                            documentCategory:
                              type: string
                              description: Broad document category
                              example: "STATEMENT"
                            documentType:
                              type: string
                              description: Specific document type
                              example: "STATEMENT"
                            fullPath:
                              type: string
                              description: Relative path to the document file
                              example: "XXXXXXXX/statements/2022-10-31-STATEMENT.pdf"
                  errormsg:
                    type: ['string', 'null']
                    description: Error message when s is not ok
              example:
                s: ok
                d:
                  pageNo: 1
                  pageSize: 149
                  totalElement: 149
                  totalPage: 1
                  data:
                    - clearAccount: "XXXXXXXX"
                      documentDate: 1667188800000
                      documentCategory: "STATEMENT"
                      documentType: "STATEMENT"
                      fullPath: "XXXXXXXX/statements/2022-10-31-STATEMENT.pdf"
                errormsg: null
        '401':
          description: Unauthorized — missing or invalid authentication
          content:
            application/json:
              schema:
                type: object
                required:
                  - s
                  - errormsg
                properties:
                  s:
                    type: string
                    enum: [error]
                  errormsg:
                    type: string
              example:
                s: error
                errormsg: "Unauthorized"

  /document/{accountId}/documents/download:
    get:
      operationId: downloadDocument
      tags: [Documents]
      summary: Download Document
      description: Returns a temporary download URL for the specified document.
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
          description: Account identifier
          example: "lh000000000001"
        - name: fullPath
          in: query
          required: true
          schema:
            type: string
          description: Full path of the document as returned by the List Documents endpoint
          example: "XXXXXXXX/statements/2022-10-31-STATEMENT.pdf"
      responses:
        '200':
          description: Temporary download URL
          content:
            application/json:
              schema:
                type: object
                required:
                  - s
                  - d
                properties:
                  s:
                    type: string
                    enum: [ok, error]
                    description: Response status indicator
                  d:
                    type: object
                    properties:
                      url:
                        type: string
                        description: Temporary pre-signed download URL
                        example: "https://example.com/download/temporary-link"
                  errormsg:
                    type: ['string', 'null']
                    description: Error message when s is not ok
              example:
                s: ok
                d:
                  url: "https://example.com/download/temporary-link"
                errormsg: null
        '401':
          description: Unauthorized — missing or invalid authentication
          content:
            application/json:
              schema:
                type: object
                required:
                  - s
                  - errormsg
                properties:
                  s:
                    type: string
                    enum: [error]
                  errormsg:
                    type: string
              example:
                s: error
                errormsg: "Unauthorized"