Claude, Grafana API.
The video asks whether Claude already knows an outside system like Grafana's API. It shows that Claude reads a skill file first, and that the file carries the account-specific details: time formats, alert surfaces and dashboard updates.
Someone might assume Claude already knows how to work with an outside system such as Grafana's API. The video says not quite: Claude is shown a file it reads before acting. It walks through what that file has to spell out, where Claude benefits from it, and where Claude can still go wrong.
Three time formats, and a wrong one fails quietly
Grafana's REST API uses three different time formats depending on the endpoint. Picking the wrong one does not return an error. It just comes back empty. Data source queries and point annotations both want Unix milliseconds, state history wants Unix seconds, and silences want RFC 3339. The example command in the skill only works with GNU date, and macOS's built-in date needs a different flag.
Roles, responses and a one-line helper
Every request carries a role: viewer, editor, or admin. A 403 means the identity is missing the role the call needs. Reading dashboards and querying data takes only viewer, while writing alert rules or silences takes editor or higher.
Data source query responses come back in Grafana's own frame format, not raw Prometheus JSON. A failure lands inside the response, in results.refId.error, while the HTTP status still reads 200. The skill also includes a one-line helper that wraps the bearer token, but it lives only for the session and is not saved anywhere.
Two alert surfaces
Alert rules live on two separate surfaces that answer different questions. The Prometheus API gives live state, firing, pending or inactive, and it is read only. The provisioning API gives the rule's definition, meaning the query, the condition and the labels, and supports full create, update and delete. Anything written through the provisioning API is locked in the Grafana UI unless the request adds a header telling Grafana to disable that lock.
Dashboards are replaced, not patched
Dashboards work differently again. There is no partial update. The pattern is to get the whole dashboard, change it, and post the whole thing back. If the version number is left out, Grafana returns a conflict instead of guessing which copy should win.
Batching and the annotations limit
Data source queries fan out to the underlying database on every call, so the design is to batch several queries into one request instead of looping separate calls. The annotations endpoint has no page parameter at all, so for a long time window the fix is to narrow the window rather than page through it.
Documented plainly versus easy to miss
Having the file does not mean Claude never trips. Where the file spells something out plainly, such as the time format warning up front or the exact field to check on a data source error, Claude follows it and skips the mistake. Where a point is a single line, or buried after the read-only examples, Claude can still get it wrong, the same way a person skimming the same page would.
The video's conclusion is that a skill does not make Claude know an API. It gives Claude a map of where the traps are, and Claude only avoids the ones the map actually marks.
Key takeaways
- Claude does not arrive already knowing a specific API; it reads a skill file before acting.
- Grafana endpoints use Unix milliseconds, Unix seconds or RFC 3339, and the wrong format returns empty results rather than an error.
- A 403 means the identity lacks the needed role; writing alert rules or silences takes editor or higher.
- Data source query errors appear inside the response body while the HTTP status stays 200.
- The Prometheus API shows live alert state; the provisioning API holds alert definitions.
- Dashboard updates replace the whole object and need the version number, or Grafana returns a conflict.
- A skill is a map of traps, and Claude only avoids the ones the map marks plainly.
Try it yourself
Pick an API you have never used with Claude before, even a small public one. Before letting it write any code, ask it to list the three things it would need confirmed first: how requests are authenticated, how paginated results come back, and any known regional or format quirk. Then have it write the first real call and check whether it actually used what it said it needed.
Chapters
Full transcript(auto-generated, with timestamps)
Cold open — does Claude already know the Grafana API?
[0:00]Someone assumed Claude already knows how to work with an outside system like Grafana's API. Not quite, it gets shown in a file it reads before acting. Here's what that file actually has to spell out. Grafana's REST API uses three
Anatomy — three time formats + role model + request setup
[0:13]Different time formats depending on the endpoint, and picking the wrong one doesn't return an error, it just comes back empty. The data source query and point annotations both want Unix milliseconds. State history wants Unix seconds. Silences want RFC 3339, and the example command only works with GNU date. macOS's built-in date needs a different flag. Every request also carries a role, viewer, editor, or admin. A 403 means the identity is missing the role the call needs. Reading dashboards and querying data only takes viewer. Writing alert rules or silences takes editor or higher. Data source query responses come back as Grafana's own frame format, not raw Prometheus JSON. A failure lands inside the response itself in results.refId.error with the HTTP status still reading 200. There's also a one-line helper that wraps the bearer token for you, but it only lives for the session. It isn't saved anywhere.
Design — two alert surfaces + dashboard replace + batching
[1:08]Alert rules live on two separate surfaces. The Prometheus API gives live state, firing, pending, or inactive, read only. The provisioning API gives the rules definition, the query, the condition, the labels, full create, update, and delete, but anything written through it is locked in the Grafana UI unless the request adds a header telling Grafana to disable that lock. Dashboards work differently again. There's no partial update, only get the whole thing, change it, and post the whole thing back, leave out the version number, and Grafana returns a conflict instead of guessing which copy wins. Data source queries fan out to the underlying database on every single call. So, the design here is to batch several queries into one request instead of looping separate calls. And the annotations endpoint has no page parameter at all. For a long time window, the fix is narrowing the window, not paging through it. So, does having
Both directions — documented plainly vs. easy to miss
[1:55]This file mean Claude never trips on Grafana's API? Not exactly. Where the file spells something out plainly, the time format warning up front, the exact field to check on a data source error, Claude follows it and skips the mistake entirely. Where it's one line or buried after the read-only examples, Claude can still get it wrong, the same way a person skimming the same page would. A skill doesn't
Carry-out
[2:16]Make Claude know an API. It gives Claude a map of where the traps are, and Claude only avoids the ones the map actually marks.
Your turn
[2:23]Your turn. Here's the prompt. Read it with me. Pick an API you've never used with Claude before, even a small public one. Before you let it write any code, ask it to list the three things it would need confirmed first: how requests are authenticated, how paginated results come back, and any known regional or format quirk. Then have it write the first real call and check whether it actually used what it just told you it needed. Claude Grafana API lay them in
Outro
[2:46]For bear
