Knack Reader

Purpose

REST-based access to Knack Objects and Views for data extraction and transformation. Primary skill for reading HTI operational data from Knack database.

Core Functions

get_records

Endpoint:

GET /v1/objects/{object_key}/records

Parameters:

• object_key

  (string, required): Knack object identifier (e.g., "object_1", "object_5")

• rows_per_page

  (integer, optional): Number of records per page (default: 1000, max: 1000)

• page

  (integer, optional): Page number to retrieve (default: 1)

• filters

  (object, optional): Filter criteria (see knack_filter_sort skill)

• sort

  (object, optional): Sort configuration (see knack_filter_sort skill)

Headers Required:

• X-Knack-Application-Id

  : HTI Knack application ID

• X-Knack-REST-API-Key

  : API key for authentication

Example Usage:

const laptops = await get_records({
  object_key: "object_1",
  params: {
    rows_per_page: 1000,
    page: 1
  }
});

Response Format:

{
  "records": [...],
  "total_pages": 5,
  "current_page": 1,
  "total_records": 4327
}

get_view_records

Endpoint:

GET /v1/pages/{scene_id}/views/{view_id}/records

Parameters:

• scene_id

  (string, required): Knack scene/page identifier

• view_id

  (string, required): Knack view identifier

• user_token

  (string, optional): For user-specific data

Use Case: Retrieve data formatted according to view-level rules (calculated fields, display rules, permissions).

Example Usage:

const dashboardData = await get_view_records({
  scene_id: "scene_12",
  view_id: "view_45"
});

HTI-Specific Objects

Common Object Keys

• Laptop Inventory: Primary device tracking
• Donations: Donor organization records
• Training Sessions: Digital literacy event tracking
• Counties: Geographic distribution data

Best Practices

1. Always use pagination for datasets >1000 records (see knack_pagination skill)
2. Cache results for frequently accessed data (see knack_cache_optimizer skill)
3. Use filters to reduce payload size when possible
4. Respect rate limits: 10 requests/second maximum

Integration Points

• knack_pagination: For retrieving full datasets
• knack_filter_sort: For query optimization
• knack_cache_optimizer: For performance
• knack_data_cleaner: For post-retrieval validation

Error Handling

Common errors:

• 401 Unauthorized

  : Check API credentials

• 404 Not Found

  : Verify object_key/view_id

• 429 Too Many Requests

  : Rate limit exceeded (use cache_optimizer)

• 500 Internal Server Error

  : Retry with exponential backoff

Grant Reporting Use

Essential for quarterly reports:

• Acquired laptops count
• Converted/ready devices
• Discarded/recycled units
• Training session attendance