> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poelis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List properties for an item

> Retrieve all properties for a specific item with optional filtering and versioning support.

    ## Overview

    This endpoint returns a unified response that includes all property types (numeric, text, date, status)
    in a single response format. Each property includes its value, metadata, references, and versioning information.

    ## Property Types

    The endpoint supports the following property types: numeric, formula, matrix, text, date, status. See the response model's `value`, `category`, and `display_unit` field descriptions for numeric (plain number), formula (computed), and matrix semantics.

    ## Versioning

    - **Omit or null** `version`: returns **draft** properties only.
    - **Integer** (e.g. `version=5`): returns properties as of that product version.
    - **`baseline`**: returns properties as of the product's baseline version.

    ## Filtering

    - **Type Filter**: Use `type` parameter to filter by property type (numeric, formula, matrix, text, date, status)
    - **Deleted Items**: Use `includeDeleted=true` to include soft-deleted properties



## OpenAPI

````yaml /openapi.json get /v1/public/properties
openapi: 3.1.0
info:
  title: Poelis Public API
  description: |2-

            Poelis Public API - REST endpoints for external clients and integrations.
            
            ## Authentication
            
            All endpoints require an API key in the `Authorization` header:
            ```
            Authorization: Bearer poelis_api_...
            ```
            
            Get your API key from the web application's API Keys section.
            
            ## Rate Limiting
            
            API requests are rate-limited per organization. Contact support for higher limits.
            
            ## Support
            
            For questions or issues, contact support@poelis.com
            
  version: 1.0.0
servers:
  - url: https://api.poelis.com
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /v1/public/properties:
    get:
      tags:
        - Properties
      summary: List properties for an item
      description: >-
        Retrieve all properties for a specific item with optional filtering and
        versioning support.

            ## Overview

            This endpoint returns a unified response that includes all property types (numeric, text, date, status)
            in a single response format. Each property includes its value, metadata, references, and versioning information.

            ## Property Types

            The endpoint supports the following property types: numeric, formula, matrix, text, date, status. See the response model's `value`, `category`, and `display_unit` field descriptions for numeric (plain number), formula (computed), and matrix semantics.

            ## Versioning

            - **Omit or null** `version`: returns **draft** properties only.
            - **Integer** (e.g. `version=5`): returns properties as of that product version.
            - **`baseline`**: returns properties as of the product's baseline version.

            ## Filtering

            - **Type Filter**: Use `type` parameter to filter by property type (numeric, formula, matrix, text, date, status)
            - **Deleted Items**: Use `includeDeleted=true` to include soft-deleted properties
      operationId: list_properties_v1_public_properties_get
      parameters:
        - name: item_id
          in: query
          required: true
          schema:
            type: string
            description: >-
              The unique identifier (UUID) of the item to retrieve properties
              for
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            title: Item Id
          description: The unique identifier (UUID) of the item to retrieve properties for
        - name: version
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Product version number (integer) or "baseline" to get properties
              from the baseline version. Omit to get draft properties.
            examples:
              - null
            title: Version
          description: >-
            Product version number (integer) or "baseline" to get properties
            from the baseline version. Omit to get draft properties.
        - name: include_deleted
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              If true, includes soft-deleted properties in the response.
              Defaults to false.
            examples:
              - false
            default: false
            title: Include Deleted
          description: >-
            If true, includes soft-deleted properties in the response. Defaults
            to false.
        - name: type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter properties by type. Allowed values: numeric, formula,
              matrix, text, date, status. Case-insensitive.
            examples:
              - numeric
            title: Type
          description: >-
            Filter properties by type. Allowed values: numeric, formula, matrix,
            text, date, status. Case-insensitive.
      responses:
        '200':
          description: >-
            Unified list of all property types for the specified item with
            metadata, references, createdBy, updatedBy (id, userName, imageUrl),
            createdAt, and updatedAt (ISO 8601) when available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPropertiesResponse'
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '400':
          description: Bad Request
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '401':
          description: Unauthorized - Invalid or missing API key
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: Invalid or missing API key
        '403':
          description: Forbidden - Access denied
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: forbidden
                message: Access denied
        '404':
          description: Not found
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: not_found
                message: Not found
        '422':
          description: Validation error - Invalid request body or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: validation_error
                message: Invalid data format
                details:
                  errors:
                    - loc:
                        - body
                        - field_name
                      msg: field required
                      type: value_error.missing
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: rate_limit_exceeded
                message: Too many requests
      security:
        - API Key: []
components:
  schemas:
    PublicPropertiesResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PublicProperty'
          type: array
          title: Items
        count:
          type: integer
          title: Count
      type: object
      required:
        - items
        - count
      title: PublicPropertiesResponse
      description: Response payload for listing properties.
      example:
        count: 1
        items:
          - category: POWER
            createdBy:
              id: auth0|550e8400-e29b-41d4-a716-446655440000
              imageUrl: https://example.com/avatar.png
              userName: Jane Doe
            deleted: false
            display_unit: kW
            id: 550e8400-e29b-41d4-a716-446655440000
            item_id: 660e8400-e29b-41d4-a716-446655440001
            name: Maximum Power
            readable_id: max-power
            references:
              - file_link_id: 890e8400-e29b-41d4-a716-446655440000
                page: 42
            type: numeric
            value: 150.5
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error code (e.g. validation_error, item_not_found).
        message:
          type: string
          description: Human-readable error message.
        details:
          type: object
          description: >-
            Additional error context (optional). For validation errors, contains
            a list of field-level issues.
          nullable: true
      required:
        - error
        - message
    PublicProperty:
      properties:
        id:
          type: string
          title: Id
        readable_id:
          type: string
          title: Readable Id
          description: Human-readable property ID
        item_id:
          type: string
          title: Item Id
        name:
          type: string
          title: Name
        type:
          type: string
          enum:
            - numeric
            - text
            - date
            - status
            - matrix
            - formula
          title: Type
        value:
          title: Value
          description: >-
            Property value. Numeric: plain number or matrix
            (category/display_unit always set; matrix value string e.g.
            "[[1,2,3],[4,5,6]]") or formula (category/display_unit never set;
            value is the result of the computation including unit if any). Text:
            string. Date: string, ISO date (e.g. "2025-01-29"). Status: string,
            one of "Draft", "Under Review", "Done".
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
          description: >-
            Category. For numeric (plain number or matrix) always set; for
            formula never set.
        display_unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Unit
          description: >-
            Display unit. For numeric (plain number or matrix) always set; for
            formula never set.
        draft_property_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Draft Property Id
        deleted:
          type: boolean
          title: Deleted
        references:
          items:
            $ref: '#/components/schemas/PublicPropertyReference'
          type: array
          title: References
          description: References to source documents for this property
        formula_expression:
          anyOf:
            - type: string
            - type: 'null'
          title: Formula Expression
          description: >-
            Formula expression for numeric properties that calculate their value
            from other properties. Uses @{property_id} syntax to reference
            dependencies. The value field holds the result of this computation,
            including unit if any.
        createdBy:
          anyOf:
            - $ref: '#/components/schemas/PublicUser'
            - type: 'null'
          description: User who created the property
        createdAt:
          anyOf:
            - type: string
            - type: 'null'
          title: Createdat
          description: ISO 8601 creation timestamp
        updatedAt:
          anyOf:
            - type: string
            - type: 'null'
          title: Updatedat
          description: ISO 8601 last-update timestamp
        updatedBy:
          anyOf:
            - $ref: '#/components/schemas/PublicUser'
            - type: 'null'
          description: User who last updated the property
      type: object
      required:
        - id
        - readable_id
        - item_id
        - name
        - type
        - value
        - deleted
      title: PublicProperty
      description: Unified public property representation.
      examples:
        - category: POWER
          createdBy:
            id: auth0|550e8400-e29b-41d4-a716-446655440000
            imageUrl: https://example.com/avatar.png
            userName: Jane Doe
          deleted: false
          display_unit: kW
          id: 550e8400-e29b-41d4-a716-446655440000
          item_id: 660e8400-e29b-41d4-a716-446655440001
          name: Maximum Power
          readable_id: max-power
          references:
            - file_link_id: 890e8400-e29b-41d4-a716-446655440000
              page: 42
          type: numeric
          value: 150.5
        - createdBy:
            id: auth0|550e8400-e29b-41d4-a716-446655440000
            imageUrl: https://example.com/avatar.png
            userName: Jane Doe
          deleted: false
          id: 550e8400-e29b-41d4-a716-446655440003
          item_id: 660e8400-e29b-41d4-a716-446655440001
          name: Material
          readable_id: material
          references: []
          type: text
          value: Aluminum Alloy 6061
    PublicPropertyReference:
      properties:
        file_link_id:
          anyOf:
            - type: string
            - type: 'null'
          title: File Link Id
          description: Referenced file link ID
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
          description: Page number in the source document
        item_document_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Item Document Id
          description: Legacy field removed from storage; always null. Use file_link_id.
          deprecated: true
      type: object
      title: PublicPropertyReference
      description: Reference from a property to a source document page.
      example:
        file_link_id: 890e8400-e29b-41d4-a716-446655440000
        page: 42
    PublicUser:
      properties:
        id:
          type: string
          title: Id
          description: User ID
        userName:
          type: string
          title: Username
          description: Display name
        imageUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Imageurl
          description: Avatar URL
      type: object
      required:
        - id
        - userName
      title: PublicUser
      description: >-
        User representation in public API responses (owner, createdBy,
        updatedBy).
      example:
        id: auth0|550e8400-e29b-41d4-a716-446655440000
        imageUrl: https://example.com/avatar.png
        userName: Jane Doe
  headers:
    RequestId:
      description: >-
        Request correlation ID. Echoes the incoming `x-request-id` header or a
        server-generated ID.
      schema:
        type: string
    RateLimitLimit:
      description: Request limit for the current rate limit window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Remaining requests in the current rate limit window.
      schema:
        type: integer
    RateLimitReset:
      description: Unix timestamp (seconds) when the current rate limit window resets.
      schema:
        type: integer
  securitySchemes:
    API Key:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Enter your API key. Example: Bearer poelis_api_...'

````