Luminary Documents API

openapi: 3.0.3
info:
  description: RESTful API for managing Luminary data
  title: Luminary Documents API
  version: 1.0.0
servers:
- description: Luminary API v1 server
  url: https://{subdomain}.withluminary.com/api/public/v1
  variables:
    subdomain:
      default: lum
      description: Your Luminary subdomain
security:
- oauth2Profiles: []
tags:
- name: Documents
paths:
  /document-summaries:
    get:
      description: Retrieve a paginated list of document summaries using cursor-based pagination
      operationId: listAllDocumentSummaries
      parameters:
      - description: Filter summaries by household ID
        in: query
        name: household_id
        schema:
          type: string
      - description: Filter summaries by document ID
        in: query
        name: document_id
        schema:
          type: string
      - $ref: '#/components/parameters/AfterCursor'
      - $ref: '#/components/parameters/BeforeCursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSummaryList'
          description: List of document summaries
        default:
          $ref: '#/components/responses/DefaultError'
      summary: List all document summaries
      tags:
      - Documents
  /document-summaries/{id}:
    parameters:
    - description: Document Summary ID
      in: path
      name: id
      required: true
      schema:
        type: string
    get:
      description: Retrieve a specific document summary
      operationId: getDocumentSummary
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSummary'
          description: Document summary found
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Get a document summary by ID
      tags:
      - Documents
    put:
      description: Update an existing document summary
      operationId: updateDocumentSummary
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDocumentSummaryRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSummary'
          description: Document summary updated successfully
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Update a document summary
      tags:
      - Documents
  /document-summaries/{id}/download:
    parameters:
    - description: Document Summary ID
      in: path
      name: id
      required: true
      schema:
        type: string
    - description: Output format for the download
      in: query
      name: format
      schema:
        default: pdf
        enum:
        - pdf
        type: string
    get:
      description: Download the document summary content in the specified format
      operationId: downloadDocumentSummary
      responses:
        '200':
          content:
            application/pdf:
              schema:
                format: binary
                type: string
          description: Document summary file
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Download document summary as PDF
      tags:
      - Documents
  /documents:
    get:
      description: Retrieve a paginated list of documents using cursor-based pagination
      operationId: listDocuments
      parameters:
      - description: Filter documents by household ID
        in: query
        name: household_id
        schema:
          type: string
      - description: Filter by document type
        in: query
        name: type
        schema:
          $ref: '#/components/schemas/DocumentType'
      - $ref: '#/components/parameters/AfterCursor'
      - $ref: '#/components/parameters/BeforeCursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
          description: List of documents
        default:
          $ref: '#/components/responses/DefaultError'
      summary: List all documents
      tags:
      - Documents
    post:
      description: Create a new document with file content
      operationId: createDocument
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
          description: Document created successfully
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Upload a new document
      tags:
      - Documents
  /documents/{id}:
    parameters:
    - description: Document ID
      in: path
      name: id
      required: true
      schema:
        type: string
    delete:
      description: Soft delete a document (marks as deleted but preserves data)
      operationId: deleteDocument
      responses:
        '204':
          description: Document deleted successfully
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Delete a document
      tags:
      - Documents
    get:
      description: Retrieve document metadata
      operationId: getDocument
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
          description: Document found
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Get a document by ID
      tags:
      - Documents
    put:
      description: Update document metadata only
      operationId: updateDocument
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDocumentRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
          description: Document updated successfully
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Update a document
      tags:
      - Documents
  /documents/{id}/document-summaries:
    parameters:
    - description: Document ID
      in: path
      name: id
      required: true
      schema:
        type: string
    get:
      description: Retrieve all summaries associated with a specific document
      operationId: listDocumentSummaries
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/DocumentSummary'
                    type: array
                required:
                - data
                type: object
          description: List of document summaries
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Get summaries for a document
      tags:
      - Documents
  /documents/{id}/download:
    parameters:
    - description: Document ID
      in: path
      name: id
      required: true
      schema:
        type: string
    get:
      description: Download the binary content of the document file
      operationId: downloadDocument
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
            application/pdf:
              schema:
                format: binary
                type: string
            application/vnd.apple.numbers:
              schema:
                format: binary
                type: string
            application/vnd.apple.pages:
              schema:
                format: binary
                type: string
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                format: binary
                type: string
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                format: binary
                type: string
            image/jpeg:
              schema:
                format: binary
                type: string
            image/png:
              schema:
                format: binary
                type: string
            text/csv:
              schema:
                format: binary
                type: string
            text/plain:
              schema:
                format: binary
                type: string
          description: Document file content
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Download document file content
      tags:
      - Documents
  /households/{id}/documents:
    parameters:
    - description: Household ID
      in: path
      name: id
      required: true
      schema:
        type: string
    get:
      description: Retrieve a paginated list of documents belonging to a specific household
      operationId: listHouseholdDocuments
      parameters:
      - description: Filter by document type
        in: query
        name: type
        schema:
          $ref: '#/components/schemas/DocumentType'
      - $ref: '#/components/parameters/AfterCursor'
      - $ref: '#/components/parameters/BeforeCursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
          description: List of documents in the household
        default:
          $ref: '#/components/responses/DefaultError'
      summary: List all documents in a household
      tags:
      - Documents
components:
  schemas:
    PageInfo:
      properties:
        end_cursor:
          description: Cursor pointing to the last item in the current page
          example: eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9
          nullable: true
          type: string
        has_next_page:
          description: When paginating forwards, are there more items?
          example: true
          type: boolean
        has_previous_page:
          description: When paginating backwards, are there more items?
          example: false
          type: boolean
        start_cursor:
          description: Cursor pointing to the first item in the current page
          example: eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9
          nullable: true
          type: string
      required:
      - has_next_page
      - has_previous_page
      type: object
    CreateDocumentRequest:
      properties:
        enable_ai_suggestions:
          default: false
          description: Whether this document should be used for AI suggestions
          type: boolean
        entity_id:
          description: Entity ID if this document is owned by an entity
          example: entity_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        file:
          description: The document file to upload
          format: binary
          type: string
        household_id:
          description: Household ID this document belongs to
          example: household_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        individual_id:
          description: Individual ID if associated with an individual
          example: client_profile_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        name:
          description: Display name of the document
          example: Trust Agreement.pdf
          minLength: 1
          type: string
        type:
          $ref: '#/components/schemas/DocumentType'
      required:
      - name
      - type
      - household_id
      - file
      type: object
    DocumentType:
      description: Type of document
      enum:
      - GRAT_DESIGN_SUMMARY
      - GENERATED_PRESENTATION
      - ASSET_VALUATION
      - SIGNED_TRUST_DOCUMENT
      - TRUST_AMENDMENT
      - TRANSFER_CONFIRMATION
      - EXISTING_REMAINDER_TRUST_DOCUMENT
      - BALANCE_SHEET
      - WILL
      - WILL_CODICIL
      - POWER_OF_ATTORNEY
      - ASSIGNMENT_OF_INTEREST
      - ASSIGNMENT_OF_TANGIBLE_PROPERTY
      - LOAN_NOTE_AGREEMENT
      - ARTICLES_OF_INCORPORATION
      - OPERATING_AGREEMENT
      - PARTNERSHIP_AGREEMENT
      - ACCOUNT_DOCUMENTATION_STATEMENT
      - TAX_ID_CONFIRMATION
      - GIFT_TAX_RETURN
      - INCOME_TAX_RETURN
      - TAX_RECEIPT
      - TAX_FILING
      - CORPORATE_BYLAWS
      - LLC_AGREEMENT
      - LLC_AGREEMENT_AMENDMENT
      - OPERATING_AGREEMENT_AMENDMENT
      - PARTNERSHIP_AGREEMENT_AMENDMENT
      - SHAREHOLDERS_AGREEMENT
      - STATE_BUSINESS_FILING
      - LOGGED_CONTRIBUTION
      - LOGGED_DISTRIBUTION
      - INSURANCE_POLICY
      - CRUMMEY_LETTER
      - INSURANCE_PREMIUM_PAYMENT
      - BENEFICIAL_OWNERSHIP_INFORMATION_REPORT
      - FINCEN_FILING
      - HEALTHCARE_PROXY
      - LIVING_WILL
      - DRIVERS_LICENSE
      - PASSPORT
      - DEED
      - OTHER
      type: string
    DocumentSummaryList:
      properties:
        data:
          items:
            $ref: '#/components/schemas/DocumentSummary'
          type: array
        page_info:
          $ref: '#/components/schemas/PageInfo'
        total_count:
          description: Total number of items matching the query (across all pages)
          example: 100
          type: integer
      required:
      - data
      - page_info
      - total_count
      type: object
    Error:
      properties:
        code:
          description: Error code
          example: INVALID_REQUEST
          type: string
        details:
          items:
            $ref: '#/components/schemas/FieldError'
          nullable: true
          type: array
        message:
          description: Error message
          example: Invalid request parameters
          type: string
      required:
      - code
      - message
      type: object
    UpdateDocumentSummaryRequest:
      properties:
        display_name:
          description: Display name for the summary
          minLength: 1
          type: string
        entry_mode:
          $ref: '#/components/schemas/DocumentSummaryEntryMode'
        summary:
          description: The summary text content
          type: string
        summary_format:
          $ref: '#/components/schemas/DocumentSummaryFormat'
      type: object
    DocumentSummary:
      properties:
        created_at:
          description: Timestamp when the summary was created
          format: date-time
          type: string
        display_name:
          description: Display name for the summary
          example: Default summary
          type: string
        document_id:
          description: ID of the document this summary belongs to
          example: document_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        entry_mode:
          $ref: '#/components/schemas/DocumentSummaryEntryMode'
        household_id:
          description: ID of the household this summary belongs to
          example: household_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        id:
          description: Unique identifier for the document summary
          example: document_summary_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        summary:
          description: The summary text content
          type: string
        summary_format:
          $ref: '#/components/schemas/DocumentSummaryFormat'
        updated_at:
          description: Timestamp when the summary was last updated
          format: date-time
          type: string
      required:
      - id
      - document_id
      - household_id
      - summary
      - display_name
      - created_at
      - updated_at
      type: object
    UpdateDocumentRequest:
      properties:
        enable_ai_suggestions:
          description: Whether this document should be used for AI suggestions
          type: boolean
        entity_id:
          description: Entity ID if this document is owned by an entity
          nullable: true
          type: string
        individual_id:
          description: Individual ID if associated with an individual
          nullable: true
          type: string
        name:
          description: Display name of the document
          minLength: 1
          type: string
        type:
          $ref: '#/components/schemas/DocumentType'
      type: object
    DocumentSummaryFormat:
      default: MARKDOWN
      description: Format of the summary content
      enum:
      - MARKDOWN
      - PLAIN_TEXT
      type: string
    DocumentSummaryEntryMode:
      default: AI_AUTO
      description: Indicates if the summary was AI-generated or user-entered
      enum:
      - AI_AUTO
      - USER
      type: string
    Document:
      properties:
        created_at:
          description: Timestamp when the document was created
          example: '2024-01-15T09:30:00Z'
          format: date-time
          type: string
        enable_ai_suggestions:
          default: false
          description: Whether this document should be used for AI suggestions
          type: boolean
        entity_id:
          description: Entity ID if this document is owned by an entity
          example: entity_01ARZ3NDEKTSV4RRFFQ69G5FAV
          nullable: true
          type: string
        household_id:
          description: Household ID this document belongs to
          example: household_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        id:
          description: Unique identifier with document_ prefix
          example: document_01ARZ3NDEKTSV4RRFFQ69G5FAV
          type: string
        individual_id:
          description: Individual ID if this document is associated with an individual
          example: client_profile_01ARZ3NDEKTSV4RRFFQ69G5FAV
          nullable: true
          type: string
        name:
          description: Display name of the document
          example: Trust Agreement.pdf
          type: string
        type:
          $ref: '#/components/schemas/DocumentType'
        updated_at:
          description: Timestamp when the document was last updated
          example: '2024-01-20T14:45:00Z'
          format: date-time
          type: string
      required:
      - id
      - name
      - type
      - household_id
      - created_at
      - updated_at
      type: object
    DocumentList:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Document'
          type: array
        page_info:
          $ref: '#/components/schemas/PageInfo'
        total_count:
          description: Total number of items matching the query (across all pages)
          example: 100
          type: integer
      required:
      - data
      - page_info
      - total_count
      type: object
    FieldError:
      properties:
        field:
          description: Field that failed validation
          example: name
          type: string
        message:
          description: Error message
          example: Name is required
          type: string
      required:
      - field
      - message
      type: object
  parameters:
    Limit:
      description: Maximum number of items to return
      in: query
      name: limit
      schema:
        default: 50
        maximum: 1000
        minimum: 1
        type: integer
    AfterCursor:
      description: Cursor for forward pagination. Returns items after this cursor.
      in: query
      name: after
      schema:
        example: eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9
        type: string
    BeforeCursor:
      description: Cursor for backward pagination. Returns items before this cursor.
      in: query
      name: before
      schema:
        example: eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9
        type: string
  responses:
    DefaultError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: General Error
  securitySchemes:
    oauth2Profiles:
      flows:
        authorizationCode:
          authorizationUrl: https://auth.withluminary.com/oauth2/authorize
          scopes: {}
          tokenUrl: https://auth.withluminary.com/oauth2/token
        clientCredentials:
          scopes: {}
          tokenUrl: https://auth.withluminary.com/oauth2/token
      type: oauth2