research-lightdash-api - SKILL.md Agent Skill

name: research-lightdash-api description: Research and investigate Lightdash API endpoints to understand request/response schemas and behavior.

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:

API Endpoint: (e.g., /api/v1/projects/:projectUuid/spaces)
HTTP Method: (GET, POST, PUT, DELETE, PATCH)
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.

2. Live Schema Verification

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

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

Execution:

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

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

For POST/PUT requests with a body:

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

Alternatively, use the Schema Verification Script if a Go-based execution is preferred:

LIGHTDASH_API_KEY=your_key LIGHTDASH_URL=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

Assets

Schema Verification Script