OpenAPI Explorer
Read ../idmp-shared/SKILL.md first.
What this skill covers
- Find the exact
service.resource.method for an IDMP operation.
- Inspect required path, query, and body inputs before execution.
- Prefer generated commands for validation, paging, and risk handling.
- Use raw API only as a controlled fallback.
Recommended reference
Missing context to resolve first
| Context |
Why it must be resolved before a raw or generated write |
| Target operation |
You need the exact service.resource.method or raw API path before you can trust the payload shape. |
| Owner scope |
Path or query IDs such as elementId, elementTemplateId, or eventId must be fixed before mutation. |
| Generated-command availability |
Decide whether a structured command already exists before falling back to raw API. |
| Verification target |
Decide which follow-up read will prove the write actually matched the intended scope. |
| Risk level |
Decide whether the operation is safe for preview only or for a real --ack-risk execution. |
Constrained live behaviors
- For writes, inspect schema first, preview with
--dry-run, execute with --ack-risk, and verify by reading the result back.
- Prefer generated commands whenever they exist; raw API is the controlled fallback, not the default path.
- A schema path that looks close is not good enough for mutation; confirm the exact path and required body before sending the write.
- Raw API success is not proof of correctness unless the equivalent generated-command scope and reread match.
Operator workflow
- Start with the nearest domain skill first, such as element, attribute, analysis, panel, dashboard, event, notification, or a workflow skill.
- Use
idmp-cli schema or idmp-cli schema search to identify the exact schema path, risk level, and required fields.
- Prefer generated commands after the schema check so validation, paging, and risk prompts stay intact.
- Use raw API only when no generated command covers the case or when low-level request confirmation is necessary.
- For writes, inspect schema first, preview with
--dry-run, execute with --ack-risk, and verify by reading the result back.
Key commands
idmp-cli schema
idmp-cli schema search element
idmp-cli schema element.elements.list
idmp-cli schema attribute.historydata.list
idmp-cli element elements list --params '{"parentId":123}'
idmp-cli attribute historydata list --params '{"elementId":1,"attributeId":2,"current":1,"size":20,"start":1704067200000,"end":1704153600000}'
idmp-cli api GET /api/v1/elements --params '{"parentId":123}'
idmp-cli api POST /api/v1/elements/batch/attributes/data --data '{"elementIds":[123],"attributeNames":["temperature"]}'
idmp-cli api POST /api/v1/elements/batch/attributes/data --ack-risk --dry-run --data '{"elementIds":[123],"attributeNames":["temperature"]}'
Exception paths
schema search returns no match: broaden the search term, inspect the adjacent domain, and only then consider raw API.- A generated command exists but validation fails: fix the inputs using
idmp-cli schema ... instead of switching immediately to raw API.
- The panel verify split is unclear:
panel verify create only accepts the time-range body with from and to via plain --data; owner params such as elementId and full panel DTO fields belong on panel.panels.query / panel.panels.create, while panel verify create-post is reserved for the advanced-query DTO.
- A paginated read looks incomplete: use
--page-all, --page-limit, and a small --page-delay.
- Raw API works but the product still looks wrong: confirm you used the same IDs, scope, and root context as the generated command flow.
- A write path is unclear: stop, inspect schema again, and do not guess the request body.
Validation scenarios
- Find a schema path with
idmp-cli schema search element.
- Inspect an exact schema such as
idmp-cli schema element.elements.list.
- Run the corresponding generated command for a known element scope.
- Inspect a second schema in another domain, such as
attribute.historydata.list.
- Use a raw API call only after the schema check with
idmp-cli api POST /api/v1/elements/batch/attributes/data --data '{"elementIds":[123],"attributeNames":["temperature"]}', then confirm the safe preview path and the generated-command behavior still match.
1---2name: idmp-openapi-explorer3description: IDMP OpenAPI explorer skill. Use it to inspect schema paths, required inputs, and generated commands; fall back to raw API only after schema and generated commands are exhausted.4---56# OpenAPI Explorer78**Read [`../idmp-shared/SKILL.md`](../idmp-shared/SKILL.md) first.**910## What this skill covers1112- Find the exact `service.resource.method` for an IDMP operation.13- Inspect required path, query, and body inputs before execution.14- Prefer generated commands for validation, paging, and risk handling.15- Use raw API only as a controlled fallback.1617## Recommended reference1819- [`OpenAPI explorer`](references/openapi-explorer.md)2021## Missing context to resolve first2223| Context | Why it must be resolved before a raw or generated write |24| --- | --- |25| Target operation | You need the exact `service.resource.method` or raw API path before you can trust the payload shape. |26| Owner scope | Path or query IDs such as `elementId`, `elementTemplateId`, or `eventId` must be fixed before mutation. |27| Generated-command availability | Decide whether a structured command already exists before falling back to raw API. |28| Verification target | Decide which follow-up read will prove the write actually matched the intended scope. |29| Risk level | Decide whether the operation is safe for preview only or for a real `--ack-risk` execution. |3031## Constrained live behaviors3233- For writes, inspect schema first, preview with `--dry-run`, execute with `--ack-risk`, and verify by reading the result back.34- Prefer generated commands whenever they exist; raw API is the controlled fallback, not the default path.35- A schema path that looks close is not good enough for mutation; confirm the exact path and required body before sending the write.36- Raw API success is not proof of correctness unless the equivalent generated-command scope and reread match.3738## Operator workflow39401. Start with the nearest domain skill first, such as element, attribute, analysis, panel, dashboard, event, notification, or a workflow skill.412. Use `idmp-cli schema` or `idmp-cli schema search` to identify the exact schema path, risk level, and required fields.423. Prefer generated commands after the schema check so validation, paging, and risk prompts stay intact.434. Use raw API only when no generated command covers the case or when low-level request confirmation is necessary.445. For writes, inspect schema first, preview with `--dry-run`, execute with `--ack-risk`, and verify by reading the result back.4546## Key commands4748```bash49idmp-cli schema50idmp-cli schema search element51idmp-cli schema element.elements.list52idmp-cli schema attribute.historydata.list5354idmp-cli element elements list --params '{"parentId":123}'55idmp-cli attribute historydata list --params '{"elementId":1,"attributeId":2,"current":1,"size":20,"start":1704067200000,"end":1704153600000}'5657idmp-cli api GET /api/v1/elements --params '{"parentId":123}'58idmp-cli api POST /api/v1/elements/batch/attributes/data --data '{"elementIds":[123],"attributeNames":["temperature"]}'59idmp-cli api POST /api/v1/elements/batch/attributes/data --ack-risk --dry-run --data '{"elementIds":[123],"attributeNames":["temperature"]}'60```6162## Exception paths6364- `schema search` returns no match: broaden the search term, inspect the adjacent domain, and only then consider raw API.65- A generated command exists but validation fails: fix the inputs using `idmp-cli schema ...` instead of switching immediately to raw API.66- The panel verify split is unclear: `panel verify create` only accepts the time-range body with `from` and `to` via plain `--data`; owner params such as `elementId` and full panel DTO fields belong on `panel.panels.query` / `panel.panels.create`, while `panel verify create-post` is reserved for the advanced-query DTO.67- A paginated read looks incomplete: use `--page-all`, `--page-limit`, and a small `--page-delay`.68- Raw API works but the product still looks wrong: confirm you used the same IDs, scope, and root context as the generated command flow.69- A write path is unclear: stop, inspect schema again, and do not guess the request body.7071## Validation scenarios72731. Find a schema path with `idmp-cli schema search element`.742. Inspect an exact schema such as `idmp-cli schema element.elements.list`.753. Run the corresponding generated command for a known element scope.764. Inspect a second schema in another domain, such as `attribute.historydata.list`.775. Use a raw API call only after the schema check with `idmp-cli api POST /api/v1/elements/batch/attributes/data --data '{"elementIds":[123],"attributeNames":["temperature"]}'`, then confirm the safe preview path and the generated-command behavior still match.
taosdata