[karl-power]

Summary

Documents minAutoGranularity on MetricSource and PromqlSource in the v2 OpenAPI spec.

• GET, POST and PUT /api/v2/sources already accept and return minAutoGranularity (validated by the shared SourceSchema), but the spec never listed it, so clients generated from openapi.json drop or reject it. The cloud gateway allow-lists fields from the generated types with failOnMissedValidators: true, so it rejects the field outright.
• Adds the property to both schema blocks in sources.ts with the SQL interval pattern (^\d+ (second|minute|hour|day)$) and example 1 minute, and regenerates openapi.json.
• The field is documented in the format it already ships in. Unlike materializedViews[].minGranularity, it is not mapped to the short form (1m); changing the response format would break existing self-hosted clients, so the description calls out the difference instead.
• Adds two v2 integration tests to pin the contract: 1 minute round-trips through POST, and 1m returns 400.

How to reproduce

Starting point: yarn dev with an API key (Team settings → API keys).

On main:

1. Open /api/v2/docs and expand MetricSource or PromqlSource. minAutoGranularity is not listed.
2. POST /api/v2/sources with a metric source body plus "minAutoGranularity": "1 minute". The request succeeds and the response echoes the field, so the API and the spec disagree.

On this branch:

1. Open /api/v2/docs. minAutoGranularity is listed on both MetricSource and PromqlSource with the SQL interval pattern.
2. make dev-int FILE=sources-crud passes, including the two new round-trip tests.

How to test on Vercel preview

N/A — non-UI change

References

• Related PRs: Add a per-source floor for Auto Granularity #3149, feat: Support minimum auto granularity on PromQL sources #3292

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hyperdx-oss	Ready	Preview	Nov 9, 2026 7:31pm UTC
hyperdx-storybook	Ready	Preview	Nov 9, 2026 7:31pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 80b9df0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

• Touches API routes or data models — hidden complexity risk

Additional context: grazes a critical path (10 lines in packages/api/src/routers/external-api/v2/sources.ts) inside a 22-line PR, so it is tiered on size

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats

• Production files changed: 2
• Production lines changed: 22 (+ 29 in test files, excluded from tier calculation)
• Branch: claude/document-min-auto-granularity-external-api
• Author: karl-power

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

Duplicate code analysis

No new duplicate code introduced by this PR.

---

jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 110 in total (1.21%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

[github-actions]

PR Review

✅ No issues found.

[github-actions]

Deep Review

✅ No critical issues found. This is a narrow, accurate documentation PR: the OpenAPI JSDoc pattern ^\d+ (second|minute|hour|day)$ exactly matches the authoritative SQLIntervalSchema regex in packages/common-utils/src/types.ts, the field is correctly scoped to only MetricSource and PromqlSource (matching the Zod schemas), the generated openapi.json escaping is correct (\\d parses back to \d), and the two new integration tests exercise real validation (1 minute round-trips, 1m → 400) rather than incidental failures.

No P2 findings.

🔵 P3 nitpicks (3)

• packages/api/src/routers/external-api/v2/sources.ts:723 — the documented pattern implies an empty string is a 400, but MinAutoGranularitySchema preprocesses '' to undefined, so the API silently accepts minAutoGranularity: "" as "unset"; a client generated strictly from the pattern would wrongly treat '' as invalid.
  • Fix: Note in the description that an empty string is accepted and means "no minimum", or leave as-is since the documented path is to omit the field.
• packages/api/src/routers/external-api/__tests__/sources-crud.int.test.ts:279 — minAutoGranularity is documented on PromqlSource but the new tests only exercise it through a Metric source, leaving the separately-defined PromqlSourceSchema field (types.ts:2856) unpinned by the external-API contract tests.
  • Fix: Add a POST PromQL-source test sending minAutoGranularity: '1 minute' and asserting it round-trips in the response and persists.
  • _{testing, correctness}
• packages/api/src/routers/external-api/v2/sources.ts:723 — the pattern ^\d+ (second|minute|hour|day)$ is hand-copied into two JSDoc blocks, decoupled from the SQLIntervalSchema source of truth, so a future regex change would silently drift the docs.
  • Fix: Add a comment beside SQLIntervalSchema in packages/common-utils/src/types.ts:150 noting the JSDoc copies exist so a regex change prompts updating them.

---

Reviewers (4): correctness, api-contract, testing, maintainability.

Testing gaps: The new tests cover only POST on a Metric source; PUT/GET round-trips, PromQL-source coverage, and the ''/omitted → unset behavior are exercised only indirectly via the shared kind-agnostic formatExternalSource + SourceSchemaNoId path.

_{No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond}

[github-actions]

E2E Test Results

✅ All tests passed • 465 passed • 1 skipped • 1423s

Status	Count
✅ Passed	465
❌ Failed	0
⚠️ Flaky	1
⏭️ Skipped	1

Tests ran across 4 shards in parallel.

View full report →