Research Lightdash API

Description

This skill is used to thoroughly research and investigate a Lightdash API endpoint. It involves researching official documentation and performing live verification against a running Lightdash instance to confirm the actual JSON schema, including request parameters and response bodies.

Input

The user should provide:

1. API Endpoint: (e.g., /api/v1/projects/:projectUuid/spaces)
2. HTTP Method: (GET, POST, PUT, DELETE, PATCH)
3. Documentation URL: (Optional) Link to the official Lightdash API docs.

Workflow

1. Documentation Research

• Search: Use web_search or WebFetch to find the endpoint details in the Lightdash API Docs.
• Analysis:

- Identify required and optional request parameters (path, query, body). - Note the expected response structure. - Check if it uses the standard [API Response Envelope](../implement-verified-lightdash-api-client/references/response_envelope.md).

2. Live Schema Verification

If you have access to a Lightdash instance and an API key:

• Environment Setup:

- Check for LIGHTDASHAPIKEY and LIGHTDASHURL (defaults to https://app.lightdash.cloud) in the environment or .env file. - If missing, inform the user: "To perform live verification, please provide LIGHTDASHAPIKEY and LIGHTDASHURL."

• Execution:

- Use curl to fetch the live response. This is the preferred method.

``bash # Example for GET request curl -X GET "${LIGHTDASHURL}/api/v1/your/endpoint" \ -H "Authorization: ApiKey ${LIGHTDASHAPI_KEY}" \ -H "Content-Type: application/json" ``

- For POST/PUT requests with a body:

``bash curl -X POST "${LIGHTDASHURL}/api/v1/your/endpoint" \ -H "Authorization: ApiKey ${LIGHTDASHAPI_KEY}" \ -H "Content-Type: application/json" \ -d '{"key": "value"}' ``

- Alternatively, use the [Schema Verification Script](assets/verify_schema.go) if a Go-based execution is preferred:

``bash LIGHTDASHAPIKEY=yourkey LIGHTDASHURL=https://app.lightdash.cloud go run .claude/skills/research-lightdash-api/assets/verify_schema.go /api/v1/your/endpoint ``

• Discrepancy Analysis:

- Compare the live JSON response with the documentation. - Document any undocumented fields, differences in data types, or unexpected behaviors. - For POST/PUT/PATCH requests, verify if the request body schema matches the documentation.

3. Response Analysis

• Envelope Check: Verify if the response is wrapped in the standard { "status": "ok", "results": ... } envelope.
• Model Mapping: Draft the Go struct definitions (models) based on the verified schema, ensuring proper types (e.g., UUID strings, timestamps, nullable fields).

Reference

• Lightdash API Documentation
• [API Response Envelope](../implement-verified-lightdash-api-client/references/response_envelope.md)

Assets

• [Schema Verification Script](assets/verify_schema.go)