openapi: 3.0.3
info:
  title: 'Pixel House API Documentation'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://partners.pixelhouse.com.au'
tags:
  -
    name: Endpoints
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: '<h2>Important Authentication Information</h2><p>All API requests must include the <code>X-Api-Key</code> header with your assigned Partner API key.</p><p>For authenticated user requests, first authenticate using the authentication endpoint. Once authenticated, include both:</p><ul><li>The token returned by the authentication endpoint: <code>Authorization: Bearer &lt;token&gt;</code></li><li>The <code>X-Api-Key</code> header</li></ul><p>This ensures secure access to the API and proper authentication for user-specific requests.</p>'
security:
  -
    default: []
paths:
  /api/v1/healthcheck:
    get:
      summary: ''
      operationId: getApiV1Healthcheck
      description: ''
      parameters:
        -
          in: header
          name: X-Api-Key
          description: ''
          example: your-api-key
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: up
                properties:
                  status:
                    type: string
                    example: up
      tags:
        - Endpoints
      security: []
  /api/v1/users/auth:
    post:
      summary: 'Authenticate with User'
      operationId: authenticateWithUser
      description: "Authenticate with the user and get a token to use in future requests.\nAlways returns 200 with a token. On failure, the token encodes the error\nso the downstream magic-link endpoint can return an error page URL."
      parameters:
        -
          in: header
          name: X-Api-Key
          description: ''
          example: your-api-key
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    token: 'encrypted string'
                properties:
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        example: 'encrypted string'
      tags:
        - Endpoints
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: 'The User ID from your system'
                  example: 1
                  nullable: false
                email:
                  type: string
                  description: 'The email of the user'
                  example: test@example.com
                  nullable: false
      security: []
  /api/v1/insights:
    get:
      summary: 'Combined Insights'
      operationId: combinedInsights
      description: 'Returns one combined dashboard insight summary across Introductions, Proposals, and Price Updates.'
      parameters:
        -
          in: query
          name: filter
          description: 'Date filter. Supported values: all-time, today, last-7-days, this-month, last-60-days, last-90-days.'
          example: last-7-days
          required: false
          schema:
            type: string
            description: 'Date filter. Supported values: all-time, today, last-7-days, this-month, last-60-days, last-90-days.'
            example: last-7-days
            nullable: false
        -
          in: query
          name: scope
          description: 'Insight scope. Supported values: user, office.'
          example: user
          required: false
          schema:
            type: string
            description: 'Insight scope. Supported values: user, office.'
            example: user
            nullable: false
        -
          in: query
          name: aggregate_by
          description: 'Optional aggregation. Use type to return separate summaries for introductions, proposals, and price_updates.'
          example: type
          required: false
          schema:
            type: string
            description: 'Optional aggregation. Use type to return separate summaries for introductions, proposals, and price_updates.'
            example: type
            nullable: false
        -
          in: header
          name: X-Api-Key
          description: ''
          example: your-api-key
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    scope: user
                    filter: last-7-days
                    total: 19
                    published: 12
                    viewed: 5
                    accepted: 1
                    draft: 3
                    unpublished: 2
                    archived: 0
                    total_views: 38
                properties:
                  data:
                    type: object
                    properties:
                      scope:
                        type: string
                        example: user
                      filter:
                        type: string
                        example: last-7-days
                      total:
                        type: integer
                        example: 19
                      published:
                        type: integer
                        example: 12
                      viewed:
                        type: integer
                        example: 5
                      accepted:
                        type: integer
                        example: 1
                      draft:
                        type: integer
                        example: 3
                      unpublished:
                        type: integer
                        example: 2
                      archived:
                        type: integer
                        example: 0
                      total_views:
                        type: integer
                        example: 38
      tags:
        - Endpoints
  '/api/v1/insights/{type}':
    get:
      summary: 'Insights by Type'
      operationId: insightsByType
      description: 'Returns one dashboard insight summary filtered to Introductions, Proposals, or Price Updates.'
      parameters:
        -
          in: query
          name: filter
          description: 'Date filter. Supported values: all-time, today, last-7-days, this-month, last-60-days, last-90-days.'
          example: last-7-days
          required: false
          schema:
            type: string
            description: 'Date filter. Supported values: all-time, today, last-7-days, this-month, last-60-days, last-90-days.'
            example: last-7-days
            nullable: false
        -
          in: query
          name: scope
          description: 'Insight scope. Supported values: user, office.'
          example: user
          required: false
          schema:
            type: string
            description: 'Insight scope. Supported values: user, office.'
            example: user
            nullable: false
        -
          in: header
          name: X-Api-Key
          description: ''
          example: your-api-key
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    type: proposal
                    scope: user
                    filter: last-7-days
                    total: 12
                    published: 8
                    viewed: 3
                    accepted: 1
                    draft: 2
                    unpublished: 1
                    archived: 0
                    total_views: 24
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        example: proposal
                      scope:
                        type: string
                        example: user
                      filter:
                        type: string
                        example: last-7-days
                      total:
                        type: integer
                        example: 12
                      published:
                        type: integer
                        example: 8
                      viewed:
                        type: integer
                        example: 3
                      accepted:
                        type: integer
                        example: 1
                      draft:
                        type: integer
                        example: 2
                      unpublished:
                        type: integer
                        example: 1
                      archived:
                        type: integer
                        example: 0
                      total_views:
                        type: integer
                        example: 24
      tags:
        - Endpoints
    parameters:
      -
        in: path
        name: type
        description: 'Insight type. Supported values: introductions, proposals, price-updates.'
        example: proposals
        required: true
        schema:
          type: string
  /api/v1/prospects/magic-link:
    post:
      summary: 'Magic Links'
      operationId: magicLinks
      description: 'This endpoint lets you generate a magic link to redirect your user to create a prospect against a property'
      parameters:
        -
          in: header
          name: X-Api-Key
          description: ''
          example: your-api-key
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    magic_link: string
                properties:
                  data:
                    type: object
                    properties:
                      magic_link:
                        type: string
                        example: string
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: enum
                  description: ''
                  example: introduction
                  nullable: false
                  enum:
                    - introduction
                    - proposal
                    - price_update
                property_id:
                  type: string
                  description: 'The ID of the property (from your system) to create a prospect against'
                  example: 123
                  nullable: false
                classification:
                  type: string
                  description: 'Optional classification to preselect and skip in the wizard. Supported values: residential_sale, property_management, strata.'
                  example: residential_sale
                  nullable: false
              required:
                - type
                - property_id