Merge branch 'platform-pod/issues/1722' of github.com:SigNoz/signoz into platform-pod/issues/1722

.gitignore

@@ -229,5 +229,3 @@ cython_debug/
 pyrightconfig.json
 
 
-# cursor files
-frontend/.cursor/

ee/query-service/app/api/api.go

@@ -10,6 +10,7 @@ import (
 	"github.com/SigNoz/signoz/ee/query-service/usage"
 	"github.com/SigNoz/signoz/pkg/alertmanager"
 	"github.com/SigNoz/signoz/pkg/global"
+	"github.com/SigNoz/signoz/pkg/http/handler"
 	"github.com/SigNoz/signoz/pkg/http/middleware"
 	querierAPI "github.com/SigNoz/signoz/pkg/querier"
 	baseapp "github.com/SigNoz/signoz/pkg/query-service/app"
@@ -106,7 +107,10 @@ func (ah *APIHandler) RegisterRoutes(router *mux.Router, am *middleware.AuthZ) {
 	router.HandleFunc("/api/v4/query_range", am.ViewAccess(ah.queryRangeV4)).Methods(http.MethodPost)
 
 	// v5
-	router.HandleFunc("/api/v5/query_range", am.ViewAccess(ah.queryRangeV5)).Methods(http.MethodPost)
+	router.Handle("/api/v5/query_range", handler.New(
+		am.ViewAccess(ah.queryRangeV5),
+		querierAPI.QueryRangeV5OpenAPIDef,
+	)).Methods(http.MethodPost)
 
 	router.HandleFunc("/api/v5/substitute_vars", am.ViewAccess(ah.QuerierAPI.ReplaceVariables)).Methods(http.MethodPost)
 

ee/zeus/httpzeus/provider.go

@@ -3,6 +3,7 @@ package httpzeus
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"io"
 	"net/http"
 	"net/url"
@@ -10,6 +11,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/factory"
 	"github.com/SigNoz/signoz/pkg/http/client"
+	"github.com/SigNoz/signoz/pkg/types/zeustypes"
 	"github.com/SigNoz/signoz/pkg/zeus"
 	"github.com/tidwall/gjson"
 )
@@ -119,8 +121,13 @@ func (provider *Provider) PutMeters(ctx context.Context, key string, data []byte
 	return err
 }
 
-func (provider *Provider) PutProfile(ctx context.Context, key string, body []byte) error {
-	_, err := provider.do(
+func (provider *Provider) PutProfile(ctx context.Context, key string, profile *zeustypes.PostableProfile) error {
+	body, err := json.Marshal(profile)
+	if err != nil {
+		return err
+	}
+
+	_, err = provider.do(
 		ctx,
 		provider.config.URL.JoinPath("/v2/profiles/me"),
 		http.MethodPut,
@@ -131,10 +138,15 @@ func (provider *Provider) PutProfile(ctx context.Context, key string, body []byt
 	return err
 }
 
-func (provider *Provider) PutHost(ctx context.Context, key string, body []byte) error {
-	_, err := provider.do(
+func (provider *Provider) PutHost(ctx context.Context, key string, host *zeustypes.PostableHost) error {
+	body, err := json.Marshal(host)
+	if err != nil {
+		return err
+	}
+
+	_, err = provider.do(
 		ctx,
-		provider.config.URL.JoinPath("/v2/deployments/me/hosts"),
+		provider.config.URL.JoinPath("/v2/deployments/me/host"),
 		http.MethodPut,
 		key,
 		body,
@@ -169,21 +181,28 @@ func (provider *Provider) do(ctx context.Context, url *url.URL, method string, k
 		return body, nil
 	}
 
-	return nil, provider.errFromStatusCode(response.StatusCode)
+	errorMessage := gjson.GetBytes(body, "error").String()
+	if errorMessage == "" {
+		errorMessage = "an unknown error occurred"
+	}
+
+	return nil, provider.errFromStatusCode(response.StatusCode, errorMessage)
 }
 
 // This can be taken down to the client package
-func (provider *Provider) errFromStatusCode(statusCode int) error {
+func (provider *Provider) errFromStatusCode(statusCode int, errorMessage string) error {
 	switch statusCode {
 	case http.StatusBadRequest:
-		return errors.Newf(errors.TypeInvalidInput, errors.CodeInvalidInput, "bad request")
+		return errors.New(errors.TypeInvalidInput, errors.CodeInvalidInput, errorMessage)
 	case http.StatusUnauthorized:
-		return errors.Newf(errors.TypeUnauthenticated, errors.CodeUnauthenticated, "unauthenticated")
+		return errors.New(errors.TypeUnauthenticated, errors.CodeUnauthenticated, errorMessage)
 	case http.StatusForbidden:
-		return errors.Newf(errors.TypeForbidden, errors.CodeForbidden, "forbidden")
+		return errors.New(errors.TypeForbidden, errors.CodeForbidden, errorMessage)
 	case http.StatusNotFound:
-		return errors.Newf(errors.TypeNotFound, errors.CodeNotFound, "not found")
+		return errors.New(errors.TypeNotFound, errors.CodeNotFound, errorMessage)
+	case http.StatusConflict:
+		return errors.New(errors.TypeAlreadyExists, errors.CodeAlreadyExists, errorMessage)
 	}
 
-	return errors.Newf(errors.TypeInternal, errors.CodeInternal, "internal")
+	return errors.New(errors.TypeInternal, errors.CodeInternal, errorMessage)
 }

frontend/.cursor/rules/testing-conventions.mdc

@@ -0,0 +1,74 @@
+---
+description: Core testing conventions - imports, rendering, MSW, interactions, queries
+globs: **/*.test.{ts,tsx}
+alwaysApply: false
+---
+
+# Testing Conventions
+
+## Imports
+
+Always import from the test harness, never directly from `@testing-library/react`:
+
+```ts
+import { render, screen, userEvent, waitFor } from 'tests/test-utils';
+import { server, rest } from 'mocks-server/server';
+```
+
+## Router
+
+Use the built-in router in `render`:
+
+```ts
+render(<Page />, undefined, { initialRoute: '/traces-explorer' });
+```
+
+Only mock `useLocation` / `useParams` if the test depends on their values.
+
+## MSW
+
+Global MSW server runs automatically. Override per-test:
+
+```ts
+server.use(
+  rest.get('*/api/v1/foo', (_req, res, ctx) =>
+    res(ctx.status(200), ctx.json({ ok: true })))
+);
+```
+
+Keep large response fixtures in `mocks-server/__mockdata_`.
+
+## Interactions
+
+- Prefer `userEvent` for real user interactions (click, type, select, tab).
+- Use `fireEvent` only for low-level events not covered by `userEvent` (e.g., scroll, resize). Wrap in `act(...)` if needed.
+- Always `await` interactions:
+
+```ts
+const user = userEvent.setup({ pointerEventsCheck: 0 });
+await user.click(screen.getByRole('button', { name: /save/i }));
+```
+
+## Timers
+
+No global fake timers. Per-test only, for debounce/throttle:
+
+```ts
+jest.useFakeTimers();
+const user = userEvent.setup({ advanceTimers: (ms) => jest.advanceTimersByTime(ms) });
+await user.type(screen.getByRole('textbox'), 'query');
+jest.advanceTimersByTime(400);
+jest.useRealTimers();
+```
+
+## Queries
+
+Prefer accessible queries: `getByRole` > `findByRole` > `getByLabelText` > visible text > `data-testid` (last resort).
+
+## Anti-patterns
+
+- Never import from `@testing-library/react` directly
+- Never use global fake timers
+- Never wrap `render` in `act(...)`
+- Never mock infra dependencies locally (router, react-query)
+- Limit to 3-5 focused tests per file

frontend/.cursor/rules/testing-mock-strategy.mdc

@@ -0,0 +1,54 @@
+---
+description: When to use global vs local mocks in tests
+globs: **/*.test.{ts,tsx}
+alwaysApply: false
+---
+
+# Mock Strategy
+
+## Use Global Mocks For
+
+High-frequency dependencies (20+ test files):
+- Core infrastructure: react-router-dom, react-query, antd
+- Browser APIs: ResizeObserver, matchMedia, localStorage
+- Utility libraries: date-fns, lodash
+
+Available global mock files (from jest.config.ts):
+- `uplot` -> `__mocks__/uplotMock.ts`
+
+## Use Local Mocks For
+
+- Business logic dependencies (API endpoints, custom hooks, domain components)
+- Test-specific behavior (different data per test, error scenarios, loading states)
+
+## Decision Tree
+
+```
+Used in 20+ test files?
+  YES -> Global mock
+  NO  -> Business logic or test-specific?
+    YES -> Local mock
+    NO  -> Consider global if usage grows
+```
+
+## Correct Usage
+
+```ts
+// Global mocks are already available - just import
+import { useLocation } from 'react-router-dom';
+
+// Local mocks for business logic
+jest.mock('../api/tracesService', () => ({
+  getTraces: jest.fn(() => mockTracesData),
+}));
+```
+
+## Anti-patterns
+
+```ts
+// Never re-mock globally mocked dependencies locally
+jest.mock('react-router-dom', () => ({ ... }));
+
+// Never put test-specific data in global mocks
+jest.mock('../api/tracesService', () => ({ getTraces: jest.fn(() => specificTestData) }));
+```

frontend/.cursor/rules/testing-type-safety.mdc

@@ -0,0 +1,54 @@
+---
+description: TypeScript type safety requirements for Jest tests
+globs: **/*.test.{ts,tsx}
+alwaysApply: false
+---
+
+# TypeScript Type Safety in Tests
+
+All Jest tests must be fully type-safe. Never use `any`.
+
+## Mock Function Typing
+
+```ts
+// Use jest.mocked for module mocks
+import useFoo from 'hooks/useFoo';
+jest.mock('hooks/useFoo');
+const mockUseFoo = jest.mocked(useFoo);
+
+// Use jest.MockedFunction for standalone mocks
+const mockFetch = jest.fn() as jest.MockedFunction<(id: number) => Promise<User>>;
+```
+
+## Mock Data
+
+Define interfaces for all mock data:
+
+```ts
+const mockUser: User = { id: 1, name: 'John', email: 'john@example.com' };
+
+const mockProps: ComponentProps = {
+  title: 'Test',
+  data: [mockUser],
+  onSelect: jest.fn() as jest.MockedFunction<(user: User) => void>,
+};
+```
+
+## Hook Mocking Pattern
+
+```ts
+import useFoo from 'hooks/useFoo';
+jest.mock('hooks/useFoo');
+const mockUseFoo = jest.mocked(useFoo);
+mockUseFoo.mockReturnValue(/* minimal shape */);
+```
+
+Prefer helpers (`rqSuccess`, `rqLoading`, `rqError`) for React Query results.
+
+## Checklist
+
+- All mock functions use `jest.MockedFunction<T>` or `jest.mocked()`
+- All mock data has proper interfaces
+- No `any` types in test files
+- Component props are typed
+- API response types are defined

frontend/.cursorrules

@@ -1,484 +0,0 @@
-# Persona
-You are an expert developer with deep knowledge of Jest, React Testing Library, MSW, and TypeScript, tasked with creating unit tests for this repository.
-
-# Auto-detect TypeScript Usage
-Check for TypeScript in the project through tsconfig.json or package.json dependencies.
-Adjust syntax based on this detection.
-
-# TypeScript Type Safety for Jest Tests
-**CRITICAL**: All Jest tests MUST be fully type-safe with proper TypeScript types.
-
-**Type Safety Requirements:**
-- Use proper TypeScript interfaces for all mock data
-- Type all Jest mock functions with `jest.MockedFunction<T>`
-- Use generic types for React components and hooks
-- Define proper return types for mock functions
-- Use `as const` for literal types when needed
-- Avoid `any` type – use proper typing instead
-
-# Unit Testing Focus
-Focus on critical functionality (business logic, utility functions, component behavior)
-Mock dependencies (API calls, external modules) before imports
-Test multiple data scenarios (valid inputs, invalid inputs, edge cases)
-Write maintainable tests with descriptive names grouped in describe blocks
-
-# Global vs Local Mocks
-**Use Global Mocks for:**
-- High-frequency dependencies (20+ test files)
-- Core infrastructure (react-router-dom, react-query, antd)
-- Standard implementations across the app
-- Browser APIs (ResizeObserver, matchMedia, localStorage)
-- Utility libraries (date-fns, lodash)
-
-**Use Local Mocks for:**
-- Business logic dependencies (5-15 test files)
-- Test-specific behavior (different data per test)
-- API endpoints with specific responses
-- Domain-specific components
-- Error scenarios and edge cases
-
-**Global Mock Files Available (from jest.config.ts):**
-- `uplot` → `__mocks__/uplotMock.ts`
-
-# Repo-specific Testing Conventions
-
-## Imports
-Always import from our harness:
-```ts
-import { render, screen, userEvent, waitFor } from 'tests/test-utils';
-```
-For API mocks:
-```ts
-import { server, rest } from 'mocks-server/server';
-```
-Do not import directly from `@testing-library/react`.
-
-## Router
-Use the router built into render:
-```ts
-render(<Page />, undefined, { initialRoute: '/traces-explorer' });
-```
-Only mock `useLocation` / `useParams` if the test depends on them.
-
-## Hook Mocks
-Pattern:
-```ts
-import useFoo from 'hooks/useFoo';
-jest.mock('hooks/useFoo');
-const mockUseFoo = jest.mocked(useFoo);
-mockUseFoo.mockReturnValue(/* minimal shape */ as any);
-```
-Prefer helpers (`rqSuccess`, `rqLoading`, `rqError`) for React Query results.
-
-## MSW
-Global MSW server runs automatically.
-Override per-test:
-```ts
-server.use(
-  rest.get('*/api/v1/foo', (_req, res, ctx) => res(ctx.status(200), ctx.json({ ok: true })))
-);
-```
-Keep large responses in `mocks-server/__mockdata_`.
-
-## Interactions
-- Prefer `userEvent` for real user interactions (click, type, select, tab).
-- Use `fireEvent` only for low-level/programmatic events not covered by `userEvent` (e.g., scroll, resize, setting `element.scrollTop` for virtualization). Wrap in `act(...)` if needed.
-- Always await interactions:
-```ts
-const user = userEvent.setup({ pointerEventsCheck: 0 });
-await user.click(screen.getByRole('button', { name: /save/i }));
-```
-
-```ts
-// Example: virtualized list scroll (no userEvent helper)
-const scroller = container.querySelector('[data-test-id="virtuoso-scroller"]') as HTMLElement;
-scroller.scrollTop = targetScrollTop;
-act(() => { fireEvent.scroll(scroller); });
-```
-
-## Timers
-❌ No global fake timers.
-✅ Per-test only, for debounce/throttle:
-```ts
-jest.useFakeTimers();
-const user = userEvent.setup({ advanceTimers: (ms) => jest.advanceTimersByTime(ms) });
-await user.type(screen.getByRole('textbox'), 'query');
-jest.advanceTimersByTime(400);
-jest.useRealTimers();
-```
-
-## Queries
-Prefer accessible queries (`getByRole`, `findByRole`, `getByLabelText`).
-Fallback: visible text.
-Last resort: `data-testid`.
-
-# Example Test (using only configured global mocks)
-```ts
-import { render, screen, userEvent, waitFor } from 'tests/test-utils';
-import { server, rest } from 'mocks-server/server';
-import MyComponent from '../MyComponent';
-
-describe('MyComponent', () => {
-  it('renders and interacts', async () => {
-    const user = userEvent.setup({ pointerEventsCheck: 0 });
-
-    server.use(
-      rest.get('*/api/v1/example', (_req, res, ctx) => res(ctx.status(200), ctx.json({ value: 42 })))
-    );
-
-    render(<MyComponent />, undefined, { initialRoute: '/foo' });
-
-    expect(await screen.findByText(/value: 42/i)).toBeInTheDocument();
-    await user.click(screen.getByRole('button', { name: /refresh/i }));
-    await waitFor(() => expect(screen.getByText(/loading/i)).toBeInTheDocument());
-  });
-});
-```
-
-# Anti-patterns
-❌ Importing RTL directly
-❌ Using global fake timers
-❌ Wrapping render in `act(...)`
-❌ Mocking infra dependencies locally (router, react-query)
-✅ Use our harness (`tests/test-utils`)
-✅ Use MSW for API overrides
-✅ Use userEvent + await
-✅ Pin time only in tests that assert relative dates
-
-# Best Practices
-- **Critical Functionality**: Prioritize testing business logic and utilities
-- **Dependency Mocking**: Global mocks for infra, local mocks for business logic
-- **Data Scenarios**: Always test valid, invalid, and edge cases
-- **Descriptive Names**: Make test intent clear
-- **Organization**: Group related tests in describe
-- **Consistency**: Match repo conventions
-- **Edge Cases**: Test null, undefined, unexpected values
-- **Limit Scope**: 3–5 focused tests per file
-- **Use Helpers**: `rqSuccess`, `makeUser`, etc.
-- **No Any**: Enforce type safety
-
-# Example Test
-```ts
-import { render, screen, userEvent, waitFor } from 'tests/test-utils';
-import { server, rest } from 'mocks-server/server';
-import MyComponent from '../MyComponent';
-
-describe('MyComponent', () => {
-  it('renders and interacts', async () => {
-    const user = userEvent.setup({ pointerEventsCheck: 0 });
-
-    server.use(
-      rest.get('*/api/v1/example', (_req, res, ctx) => res(ctx.status(200), ctx.json({ value: 42 })))
-    );
-
-    render(<MyComponent />, undefined, { initialRoute: '/foo' });
-
-    expect(await screen.findByText(/value: 42/i)).toBeInTheDocument();
-    await user.click(screen.getByRole('button', { name: /refresh/i }));
-    await waitFor(() => expect(screen.getByText(/loading/i)).toBeInTheDocument());
-  });
-});
-```
-
-# Anti-patterns
-❌ Importing RTL directly
-❌ Using global fake timers
-❌ Wrapping render in `act(...)`
-❌ Mocking infra dependencies locally (router, react-query)
-✅ Use our harness (`tests/test-utils`)
-✅ Use MSW for API overrides
-✅ Use userEvent + await
-✅ Pin time only in tests that assert relative dates
-
-# TypeScript Type Safety Examples
-
-## Proper Mock Typing
-```ts
-// ✅ GOOD - Properly typed mocks
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-interface ApiResponse<T> {
-  data: T;
-  status: number;
-  message: string;
-}
-
-// Type the mock functions
-const mockFetchUser = jest.fn() as jest.MockedFunction<(id: number) => Promise<ApiResponse<User>>>;
-const mockUpdateUser = jest.fn() as jest.MockedFunction<(user: User) => Promise<ApiResponse<User>>>;
-
-// Mock implementation with proper typing
-mockFetchUser.mockResolvedValue({
-  data: { id: 1, name: 'John Doe', email: 'john@example.com' },
-  status: 200,
-  message: 'Success'
-});
-
-// ❌ BAD - Using any type
-const mockFetchUser = jest.fn() as any; // Don't do this
-```
-
-## React Component Testing with Types
-```ts
-// ✅ GOOD - Properly typed component testing
-interface ComponentProps {
-  title: string;
-  data: User[];
-  onUserSelect: (user: User) => void;
-  isLoading?: boolean;
-}
-
-const TestComponent: React.FC<ComponentProps> = ({ title, data, onUserSelect, isLoading = false }) => {
-  // Component implementation
-};
-
-describe('TestComponent', () => {
-  it('should render with proper props', () => {
-    // Arrange - Type the props properly
-    const mockProps: ComponentProps = {
-      title: 'Test Title',
-      data: [{ id: 1, name: 'John', email: 'john@example.com' }],
-      onUserSelect: jest.fn() as jest.MockedFunction<(user: User) => void>,
-      isLoading: false
-    };
-    
-    // Act
-    render(<TestComponent {...mockProps} />);
-    
-    // Assert
-    expect(screen.getByText('Test Title')).toBeInTheDocument();
-  });
-});
-```
-
-## Hook Testing with Types
-```ts
-// ✅ GOOD - Properly typed hook testing
-interface UseUserDataReturn {
-  user: User | null;
-  loading: boolean;
-  error: string | null;
-  refetch: () => void;
-}
-
-const useUserData = (id: number): UseUserDataReturn => {
-  // Hook implementation
-};
-
-describe('useUserData', () => {
-  it('should return user data with proper typing', () => {
-    // Arrange
-    const mockUser: User = { id: 1, name: 'John', email: 'john@example.com' };
-    mockFetchUser.mockResolvedValue({
-      data: mockUser,
-      status: 200,
-      message: 'Success'
-    });
-    
-    // Act
-    const { result } = renderHook(() => useUserData(1));
-    
-    // Assert
-    expect(result.current.user).toEqual(mockUser);
-    expect(result.current.loading).toBe(false);
-    expect(result.current.error).toBeNull();
-  });
-});
-```
-
-## Global Mock Type Safety
-```ts
-// ✅ GOOD - Type-safe global mocks
-// In __mocks__/routerMock.ts
-export const mockUseLocation = (overrides: Partial<Location> = {}): Location => ({
-  pathname: '/traces',
-  search: '',
-  hash: '',
-  state: null,
-  key: 'test-key',
-  ...overrides,
-});
-
-// In test files
-const location = useLocation(); // Properly typed from global mock
-expect(location.pathname).toBe('/traces');
-```
-
-# TypeScript Configuration for Jest
-
-## Required Jest Configuration
-```json
-// jest.config.ts
-{
-  "preset": "ts-jest/presets/js-with-ts-esm",
-  "globals": {
-    "ts-jest": {
-      "useESM": true,
-      "isolatedModules": true,
-      "tsconfig": "<rootDir>/tsconfig.jest.json"
-    }
-  },
-  "extensionsToTreatAsEsm": [".ts", ".tsx"],
-  "moduleFileExtensions": ["ts", "tsx", "js", "json"]
-}
-```
-
-## TypeScript Jest Configuration
-```json
-// tsconfig.jest.json
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "types": ["jest", "@testing-library/jest-dom"],
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "moduleResolution": "node"
-  },
-  "include": [
-    "src/**/*",
-    "**/*.test.ts",
-    "**/*.test.tsx",
-    "__mocks__/**/*"
-  ]
-}
-```
-
-## Common Type Safety Patterns
-
-### Mock Function Typing
-```ts
-// ✅ GOOD - Proper mock function typing
-const mockApiCall = jest.fn() as jest.MockedFunction<typeof apiCall>;
-const mockEventHandler = jest.fn() as jest.MockedFunction<(event: Event) => void>;
-
-// ❌ BAD - Using any
-const mockApiCall = jest.fn() as any;
-```
-
-### Generic Mock Typing
-```ts
-// ✅ GOOD - Generic mock typing
-interface MockApiResponse<T> {
-  data: T;
-  status: number;
-}
-
-const mockFetchData = jest.fn() as jest.MockedFunction<
-  <T>(endpoint: string) => Promise<MockApiResponse<T>>
->;
-
-// Usage
-mockFetchData<User>('/users').mockResolvedValue({
-  data: { id: 1, name: 'John' },
-  status: 200
-});
-```
-
-### React Testing Library with Types
-```ts
-// ✅ GOOD - Typed testing utilities
-import { render, screen, RenderResult } from '@testing-library/react';
-import { ComponentProps } from 'react';
-
-type TestComponentProps = ComponentProps<typeof TestComponent>;
-
-const renderTestComponent = (props: Partial<TestComponentProps> = {}): RenderResult => {
-  const defaultProps: TestComponentProps = {
-    title: 'Test',
-    data: [],
-    onSelect: jest.fn(),
-    ...props
-  };
-  
-  return render(<TestComponent {...defaultProps} />);
-};
-```
-
-### Error Handling with Types
-```ts
-// ✅ GOOD - Typed error handling
-interface ApiError {
-  message: string;
-  code: number;
-  details?: Record<string, unknown>;
-}
-
-const mockApiError: ApiError = {
-  message: 'API Error',
-  code: 500,
-  details: { endpoint: '/users' }
-};
-
-mockFetchUser.mockRejectedValue(new Error(JSON.stringify(mockApiError)));
-```
-
-## Type Safety Checklist
-- [ ] All mock functions use `jest.MockedFunction<T>`
-- [ ] All mock data has proper interfaces
-- [ ] No `any` types in test files
-- [ ] Generic types are used where appropriate
-- [ ] Error types are properly defined
-- [ ] Component props are typed
-- [ ] Hook return types are defined
-- [ ] API response types are defined
-- [ ] Global mocks are type-safe
-- [ ] Test utilities are properly typed
-
-# Mock Decision Tree
-```
-Is it used in 20+ test files?
-├─ YES → Use Global Mock
-│   ├─ react-router-dom
-│   ├─ react-query
-│   ├─ antd components
-│   └─ browser APIs
-│
-└─ NO → Is it business logic?
-    ├─ YES → Use Local Mock
-    │   ├─ API endpoints
-    │   ├─ Custom hooks
-    │   └─ Domain components
-    │
-    └─ NO → Is it test-specific?
-        ├─ YES → Use Local Mock
-        │   ├─ Error scenarios
-        │   ├─ Loading states
-        │   └─ Specific data
-        │
-        └─ NO → Consider Global Mock
-            └─ If it becomes frequently used
-```
-
-# Common Anti-Patterns to Avoid
-
-❌ **Don't mock global dependencies locally:**
-```js
-// BAD - This is already globally mocked
-jest.mock('react-router-dom', () => ({ ... }));
-```
-
-❌ **Don't create global mocks for test-specific data:**
-```js
-// BAD - This should be local
-jest.mock('../api/tracesService', () => ({
-  getTraces: jest.fn(() => specificTestData)
-}));
-```
-
-✅ **Do use global mocks for infrastructure:**
-```js
-// GOOD - Use global mock
-import { useLocation } from 'react-router-dom';
-```
-
-✅ **Do create local mocks for business logic:**
-```js
-// GOOD - Local mock for specific test needs
-jest.mock('../api/tracesService', () => ({
-  getTraces: jest.fn(() => mockTracesData)
-}));
-```

frontend/src/api/generated/services/query/index.ts

@@ -0,0 +1,107 @@
+/**
+ * ! Do not edit manually
+ * * The file has been auto-generated using Orval for SigNoz
+ * * regenerate with 'yarn generate:api'
+ * SigNoz
+ */
+import type {
+	MutationFunction,
+	UseMutationOptions,
+	UseMutationResult,
+} from 'react-query';
+import { useMutation } from 'react-query';
+
+import { GeneratedAPIInstance } from '../../../index';
+import type {
+	Querybuildertypesv5QueryRangeRequestDTO,
+	QueryRangeV5200,
+	RenderErrorResponseDTO,
+} from '../sigNoz.schemas';
+
+type AwaitedInput<T> = PromiseLike<T> | T;
+
+type Awaited<O> = O extends AwaitedInput<infer T> ? T : never;
+
+/**
+ * Execute a composite query over a time range. Supports builder queries (traces, logs, metrics), formulas, trace operators, PromQL, and ClickHouse SQL.
+ * @summary Query range
+ */
+export const queryRangeV5 = (
+	querybuildertypesv5QueryRangeRequestDTO: Querybuildertypesv5QueryRangeRequestDTO,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<QueryRangeV5200>({
+		url: `/api/v5/query_range`,
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		data: querybuildertypesv5QueryRangeRequestDTO,
+		signal,
+	});
+};
+
+export const getQueryRangeV5MutationOptions = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof queryRangeV5>>,
+		TError,
+		{ data: Querybuildertypesv5QueryRangeRequestDTO },
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof queryRangeV5>>,
+	TError,
+	{ data: Querybuildertypesv5QueryRangeRequestDTO },
+	TContext
+> => {
+	const mutationKey = ['queryRangeV5'];
+	const { mutation: mutationOptions } = options
+		? options.mutation &&
+		  'mutationKey' in options.mutation &&
+		  options.mutation.mutationKey
+			? options
+			: { ...options, mutation: { ...options.mutation, mutationKey } }
+		: { mutation: { mutationKey } };
+
+	const mutationFn: MutationFunction<
+		Awaited<ReturnType<typeof queryRangeV5>>,
+		{ data: Querybuildertypesv5QueryRangeRequestDTO }
+	> = (props) => {
+		const { data } = props ?? {};
+
+		return queryRangeV5(data);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type QueryRangeV5MutationResult = NonNullable<
+	Awaited<ReturnType<typeof queryRangeV5>>
+>;
+export type QueryRangeV5MutationBody = Querybuildertypesv5QueryRangeRequestDTO;
+export type QueryRangeV5MutationError = RenderErrorResponseDTO;
+
+/**
+ * @summary Query range
+ */
+export const useQueryRangeV5 = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof queryRangeV5>>,
+		TError,
+		{ data: Querybuildertypesv5QueryRangeRequestDTO },
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof queryRangeV5>>,
+	TError,
+	{ data: Querybuildertypesv5QueryRangeRequestDTO },
+	TContext
+> => {
+	const mutationOptions = getQueryRangeV5MutationOptions(options);
+
+	return useMutation(mutationOptions);
+};

frontend/src/api/generated/services/zeus/index.ts

@@ -0,0 +1,279 @@
+/**
+ * ! Do not edit manually
+ * * The file has been auto-generated using Orval for SigNoz
+ * * regenerate with 'yarn generate:api'
+ * SigNoz
+ */
+import type {
+	InvalidateOptions,
+	MutationFunction,
+	QueryClient,
+	QueryFunction,
+	QueryKey,
+	UseMutationOptions,
+	UseMutationResult,
+	UseQueryOptions,
+	UseQueryResult,
+} from 'react-query';
+import { useMutation, useQuery } from 'react-query';
+
+import { GeneratedAPIInstance } from '../../../index';
+import type {
+	GetDeploymentsFromZeus200,
+	RenderErrorResponseDTO,
+	ZeustypesPostableHostDTO,
+	ZeustypesPostableProfileDTO,
+} from '../sigNoz.schemas';
+
+type AwaitedInput<T> = PromiseLike<T> | T;
+
+type Awaited<O> = O extends AwaitedInput<infer T> ? T : never;
+
+/**
+ * This endpoint gets the host info from zeus.
+ * @summary Get host info from Zeus.
+ */
+export const getDeploymentsFromZeus = (signal?: AbortSignal) => {
+	return GeneratedAPIInstance<GetDeploymentsFromZeus200>({
+		url: `/api/v2/zeus/hosts`,
+		method: 'GET',
+		signal,
+	});
+};
+
+export const getGetDeploymentsFromZeusQueryKey = () => {
+	return ['getDeploymentsFromZeus'] as const;
+};
+
+export const getGetDeploymentsFromZeusQueryOptions = <
+	TData = Awaited<ReturnType<typeof getDeploymentsFromZeus>>,
+	TError = RenderErrorResponseDTO
+>(options?: {
+	query?: UseQueryOptions<
+		Awaited<ReturnType<typeof getDeploymentsFromZeus>>,
+		TError,
+		TData
+	>;
+}) => {
+	const { query: queryOptions } = options ?? {};
+
+	const queryKey = queryOptions?.queryKey ?? getGetDeploymentsFromZeusQueryKey();
+
+	const queryFn: QueryFunction<
+		Awaited<ReturnType<typeof getDeploymentsFromZeus>>
+	> = ({ signal }) => getDeploymentsFromZeus(signal);
+
+	return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
+		Awaited<ReturnType<typeof getDeploymentsFromZeus>>,
+		TError,
+		TData
+	> & { queryKey: QueryKey };
+};
+
+export type GetDeploymentsFromZeusQueryResult = NonNullable<
+	Awaited<ReturnType<typeof getDeploymentsFromZeus>>
+>;
+export type GetDeploymentsFromZeusQueryError = RenderErrorResponseDTO;
+
+/**
+ * @summary Get host info from Zeus.
+ */
+
+export function useGetDeploymentsFromZeus<
+	TData = Awaited<ReturnType<typeof getDeploymentsFromZeus>>,
+	TError = RenderErrorResponseDTO
+>(options?: {
+	query?: UseQueryOptions<
+		Awaited<ReturnType<typeof getDeploymentsFromZeus>>,
+		TError,
+		TData
+	>;
+}): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+	const queryOptions = getGetDeploymentsFromZeusQueryOptions(options);
+
+	const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+		queryKey: QueryKey;
+	};
+
+	query.queryKey = queryOptions.queryKey;
+
+	return query;
+}
+
+/**
+ * @summary Get host info from Zeus.
+ */
+export const invalidateGetDeploymentsFromZeus = async (
+	queryClient: QueryClient,
+	options?: InvalidateOptions,
+): Promise<QueryClient> => {
+	await queryClient.invalidateQueries(
+		{ queryKey: getGetDeploymentsFromZeusQueryKey() },
+		options,
+	);
+
+	return queryClient;
+};
+
+/**
+ * This endpoint saves the host of a deployment to zeus.
+ * @summary Put host in Zeus for a deployment.
+ */
+export const putHostInZeus = (
+	zeustypesPostableHostDTO: ZeustypesPostableHostDTO,
+) => {
+	return GeneratedAPIInstance<void>({
+		url: `/api/v2/zeus/hosts`,
+		method: 'PUT',
+		headers: { 'Content-Type': 'application/json' },
+		data: zeustypesPostableHostDTO,
+	});
+};
+
+export const getPutHostInZeusMutationOptions = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof putHostInZeus>>,
+		TError,
+		{ data: ZeustypesPostableHostDTO },
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof putHostInZeus>>,
+	TError,
+	{ data: ZeustypesPostableHostDTO },
+	TContext
+> => {
+	const mutationKey = ['putHostInZeus'];
+	const { mutation: mutationOptions } = options
+		? options.mutation &&
+		  'mutationKey' in options.mutation &&
+		  options.mutation.mutationKey
+			? options
+			: { ...options, mutation: { ...options.mutation, mutationKey } }
+		: { mutation: { mutationKey } };
+
+	const mutationFn: MutationFunction<
+		Awaited<ReturnType<typeof putHostInZeus>>,
+		{ data: ZeustypesPostableHostDTO }
+	> = (props) => {
+		const { data } = props ?? {};
+
+		return putHostInZeus(data);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type PutHostInZeusMutationResult = NonNullable<
+	Awaited<ReturnType<typeof putHostInZeus>>
+>;
+export type PutHostInZeusMutationBody = ZeustypesPostableHostDTO;
+export type PutHostInZeusMutationError = RenderErrorResponseDTO;
+
+/**
+ * @summary Put host in Zeus for a deployment.
+ */
+export const usePutHostInZeus = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof putHostInZeus>>,
+		TError,
+		{ data: ZeustypesPostableHostDTO },
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof putHostInZeus>>,
+	TError,
+	{ data: ZeustypesPostableHostDTO },
+	TContext
+> => {
+	const mutationOptions = getPutHostInZeusMutationOptions(options);
+
+	return useMutation(mutationOptions);
+};
+/**
+ * This endpoint saves the profile of a deployment to zeus.
+ * @summary Put profile in Zeus for a deployment.
+ */
+export const putProfileInZeus = (
+	zeustypesPostableProfileDTO: ZeustypesPostableProfileDTO,
+) => {
+	return GeneratedAPIInstance<void>({
+		url: `/api/v2/zeus/profiles`,
+		method: 'PUT',
+		headers: { 'Content-Type': 'application/json' },
+		data: zeustypesPostableProfileDTO,
+	});
+};
+
+export const getPutProfileInZeusMutationOptions = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof putProfileInZeus>>,
+		TError,
+		{ data: ZeustypesPostableProfileDTO },
+		TContext
+	>;
+}): UseMutationOptions<
+	Awaited<ReturnType<typeof putProfileInZeus>>,
+	TError,
+	{ data: ZeustypesPostableProfileDTO },
+	TContext
+> => {
+	const mutationKey = ['putProfileInZeus'];
+	const { mutation: mutationOptions } = options
+		? options.mutation &&
+		  'mutationKey' in options.mutation &&
+		  options.mutation.mutationKey
+			? options
+			: { ...options, mutation: { ...options.mutation, mutationKey } }
+		: { mutation: { mutationKey } };
+
+	const mutationFn: MutationFunction<
+		Awaited<ReturnType<typeof putProfileInZeus>>,
+		{ data: ZeustypesPostableProfileDTO }
+	> = (props) => {
+		const { data } = props ?? {};
+
+		return putProfileInZeus(data);
+	};
+
+	return { mutationFn, ...mutationOptions };
+};
+
+export type PutProfileInZeusMutationResult = NonNullable<
+	Awaited<ReturnType<typeof putProfileInZeus>>
+>;
+export type PutProfileInZeusMutationBody = ZeustypesPostableProfileDTO;
+export type PutProfileInZeusMutationError = RenderErrorResponseDTO;
+
+/**
+ * @summary Put profile in Zeus for a deployment.
+ */
+export const usePutProfileInZeus = <
+	TError = RenderErrorResponseDTO,
+	TContext = unknown
+>(options?: {
+	mutation?: UseMutationOptions<
+		Awaited<ReturnType<typeof putProfileInZeus>>,
+		TError,
+		{ data: ZeustypesPostableProfileDTO },
+		TContext
+	>;
+}): UseMutationResult<
+	Awaited<ReturnType<typeof putProfileInZeus>>,
+	TError,
+	{ data: ZeustypesPostableProfileDTO },
+	TContext
+> => {
+	const mutationOptions = getPutProfileInZeusMutationOptions(options);
+
+	return useMutation(mutationOptions);
+};

pkg/apiserver/signozapiserver/provider.go

@@ -22,6 +22,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/modules/user"
 	"github.com/SigNoz/signoz/pkg/types"
 	"github.com/SigNoz/signoz/pkg/types/ctxtypes"
+	"github.com/SigNoz/signoz/pkg/zeus"
 	"github.com/gorilla/mux"
 )
 
@@ -44,6 +45,7 @@ type provider struct {
 	gatewayHandler         gateway.Handler
 	fieldsHandler          fields.Handler
 	authzHandler           authz.Handler
+	zeusHandler            zeus.Handler
 }
 
 func NewFactory(
@@ -63,6 +65,7 @@ func NewFactory(
 	gatewayHandler gateway.Handler,
 	fieldsHandler fields.Handler,
 	authzHandler authz.Handler,
+	zeusHandler zeus.Handler,
 ) factory.ProviderFactory[apiserver.APIServer, apiserver.Config] {
 	return factory.NewProviderFactory(factory.MustNewName("signoz"), func(ctx context.Context, providerSettings factory.ProviderSettings, config apiserver.Config) (apiserver.APIServer, error) {
 		return newProvider(
@@ -85,6 +88,7 @@ func NewFactory(
 			gatewayHandler,
 			fieldsHandler,
 			authzHandler,
+			zeusHandler,
 		)
 	})
 }
@@ -109,6 +113,7 @@ func newProvider(
 	gatewayHandler gateway.Handler,
 	fieldsHandler fields.Handler,
 	authzHandler authz.Handler,
+	zeusHandler zeus.Handler,
 ) (apiserver.APIServer, error) {
 	settings := factory.NewScopedProviderSettings(providerSettings, "github.com/SigNoz/signoz/pkg/apiserver/signozapiserver")
 	router := mux.NewRouter().UseEncodedPath()
@@ -131,6 +136,7 @@ func newProvider(
 		gatewayHandler:         gatewayHandler,
 		fieldsHandler:          fieldsHandler,
 		authzHandler:           authzHandler,
+		zeusHandler:            zeusHandler,
 	}
 
 	provider.authZ = middleware.NewAuthZ(settings.Logger(), orgGetter, authz)
@@ -199,6 +205,10 @@ func (provider *provider) AddToRouter(router *mux.Router) error {
 		return err
 	}
 
+	if err := provider.addZeusRoutes(router); err != nil {
+		return err
+	}
+
 	return nil
 }
 

pkg/apiserver/signozapiserver/zeus.go

@@ -0,0 +1,65 @@
+package signozapiserver
+
+import (
+	"net/http"
+
+	"github.com/SigNoz/signoz/pkg/http/handler"
+	"github.com/SigNoz/signoz/pkg/types"
+	"github.com/SigNoz/signoz/pkg/types/zeustypes"
+	"github.com/gorilla/mux"
+)
+
+func (provider *provider) addZeusRoutes(router *mux.Router) error {
+	if err := router.Handle("/api/v2/zeus/profiles", handler.New(provider.authZ.AdminAccess(provider.zeusHandler.PutProfile), handler.OpenAPIDef{
+		ID:                  "PutProfileInZeus",
+		Tags:                []string{"zeus"},
+		Summary:             "Put profile in Zeus for a deployment.",
+		Description:         "This endpoint saves the profile of a deployment to zeus.",
+		Request:             new(zeustypes.PostableProfile),
+		RequestContentType:  "application/json",
+		Response:            nil,
+		ResponseContentType: "",
+		SuccessStatusCode:   http.StatusNoContent,
+		ErrorStatusCodes:    []int{http.StatusBadRequest, http.StatusUnauthorized, http.StatusForbidden, http.StatusNotFound, http.StatusConflict},
+		Deprecated:          false,
+		SecuritySchemes:     newSecuritySchemes(types.RoleAdmin),
+	})).Methods(http.MethodPut).GetError(); err != nil {
+		return err
+	}
+
+	if err := router.Handle("/api/v2/zeus/hosts", handler.New(provider.authZ.AdminAccess(provider.zeusHandler.GetHostFromZeus), handler.OpenAPIDef{
+		ID:                  "GetDeploymentsFromZeus",
+		Tags:                []string{"zeus"},
+		Summary:             "Get host info from Zeus.",
+		Description:         "This endpoint gets the host info from zeus.",
+		Request:             nil,
+		RequestContentType:  "",
+		Response:            new(zeustypes.GettableZeusHost),
+		ResponseContentType: "application/json",
+		SuccessStatusCode:   http.StatusOK,
+		ErrorStatusCodes:    []int{http.StatusBadRequest, http.StatusUnauthorized, http.StatusForbidden, http.StatusNotFound},
+		Deprecated:          false,
+		SecuritySchemes:     newSecuritySchemes(types.RoleAdmin),
+	})).Methods(http.MethodGet).GetError(); err != nil {
+		return err
+	}
+
+	if err := router.Handle("/api/v2/zeus/hosts", handler.New(provider.authZ.AdminAccess(provider.zeusHandler.PutHost), handler.OpenAPIDef{
+		ID:                  "PutHostInZeus",
+		Tags:                []string{"zeus"},
+		Summary:             "Put host in Zeus for a deployment.",
+		Description:         "This endpoint saves the host of a deployment to zeus.",
+		Request:             new(zeustypes.PostableHost),
+		RequestContentType:  "application/json",
+		Response:            nil,
+		ResponseContentType: "",
+		SuccessStatusCode:   http.StatusNoContent,
+		ErrorStatusCodes:    []int{http.StatusBadRequest, http.StatusUnauthorized, http.StatusForbidden, http.StatusNotFound, http.StatusConflict},
+		Deprecated:          false,
+		SecuritySchemes:     newSecuritySchemes(types.RoleAdmin),
+	})).Methods(http.MethodPut).GetError(); err != nil {
+		return err
+	}
+
+	return nil
+}

pkg/http/handler/handler.go

@@ -7,6 +7,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/http/render"
 	"github.com/swaggest/openapi-go"
+	"github.com/swaggest/openapi-go/openapi3"
 )
 
 type ServeOpenAPIFunc func(openapi.OperationContext)
@@ -59,7 +60,39 @@ func (handler *handler) ServeOpenAPI(opCtx openapi.OperationContext) {
 	}
 
 	// Add request structure
-	opCtx.AddReqStructure(handler.openAPIDef.Request, openapi.WithContentType(handler.openAPIDef.RequestContentType))
+	reqOpts := []openapi.ContentOption{openapi.WithContentType(handler.openAPIDef.RequestContentType)}
+	if len(handler.openAPIDef.RequestExamples) > 0 {
+		reqOpts = append(reqOpts, openapi.WithCustomize(func(cor openapi.ContentOrReference) {
+			rbOrRef, ok := cor.(*openapi3.RequestBodyOrRef)
+			if !ok || rbOrRef.RequestBody == nil {
+				return
+			}
+			ct := handler.openAPIDef.RequestContentType
+			if ct == "" {
+				ct = "application/json"
+			}
+			mt, exists := rbOrRef.RequestBody.Content[ct]
+			if !exists {
+				return
+			}
+			if mt.Examples == nil {
+				mt.Examples = make(map[string]openapi3.ExampleOrRef)
+			}
+			for _, ex := range handler.openAPIDef.RequestExamples {
+				val := ex.Value
+				oaExample := openapi3.Example{Value: &val}
+				if ex.Summary != "" {
+					oaExample.WithSummary(ex.Summary)
+				}
+				if ex.Description != "" {
+					oaExample.WithDescription(ex.Description)
+				}
+				mt.Examples[ex.Name] = openapi3.ExampleOrRef{Example: &oaExample}
+			}
+			rbOrRef.RequestBody.Content[ct] = mt
+		}))
+	}
+	opCtx.AddReqStructure(handler.openAPIDef.Request, reqOpts...)
 
 	// Add request query structure
 	opCtx.AddReqStructure(handler.openAPIDef.RequestQuery)

pkg/http/handler/openapi.go

@@ -9,6 +9,14 @@ import (
 	"github.com/swaggest/rest/openapi"
 )
 
+// OpenAPIExample is a named example for an OpenAPI operation.
+type OpenAPIExample struct {
+	Name        string
+	Summary     string
+	Description string
+	Value       any
+}
+
 // Def is the definition of an OpenAPI operation
 type OpenAPIDef struct {
 	ID                  string
@@ -18,6 +26,7 @@ type OpenAPIDef struct {
 	Request             any
 	RequestQuery        any
 	RequestContentType  string
+	RequestExamples     []OpenAPIExample
 	Response            any
 	ResponseContentType string
 	SuccessStatusCode   int

pkg/querier/openapi.go

@@ -0,0 +1,454 @@
+package querier
+
+import (
+	"net/http"
+
+	"github.com/SigNoz/signoz/pkg/http/handler"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/ctxtypes"
+)
+
+// QueryRangeV5OpenAPIDef is the OpenAPI definition for the /api/v5/query_range endpoint.
+var QueryRangeV5OpenAPIDef = handler.OpenAPIDef{
+	ID:                  "QueryRangeV5",
+	Tags:                []string{"query"},
+	Summary:             "Query range",
+	Description:         "Execute a composite query over a time range. Supports builder queries (traces, logs, metrics), formulas, trace operators, PromQL, and ClickHouse SQL.",
+	Request:             new(qbtypes.QueryRangeRequest),
+	RequestContentType:  "application/json",
+	RequestExamples:     queryRangeV5Examples,
+	Response:            new(qbtypes.QueryRangeResponse),
+	ResponseContentType: "application/json",
+	SuccessStatusCode:   http.StatusOK,
+	ErrorStatusCodes:    []int{http.StatusBadRequest},
+	SecuritySchemes: []handler.OpenAPISecurityScheme{
+		{Name: ctxtypes.AuthTypeAPIKey.StringValue(), Scopes: []string{"VIEWER"}},
+		{Name: ctxtypes.AuthTypeTokenizer.StringValue(), Scopes: []string{"VIEWER"}},
+	},
+}
+
+var queryRangeV5Examples = []handler.OpenAPIExample{
+	{
+		Name:    "traces_time_series",
+		Summary: "Time series: count spans grouped by service",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "traces",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "span_count"},
+							},
+							"stepInterval": "60s",
+							"filter":       map[string]any{"expression": "service.name = 'frontend'"},
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+							"order":        []any{map[string]any{"key": map[string]any{"name": "span_count"}, "direction": "desc"}},
+							"limit":        10,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "logs_time_series",
+		Summary: "Time series: count error logs grouped by service",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "logs",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "log_count"},
+							},
+							"stepInterval": "60s",
+							"filter":       map[string]any{"expression": "severity_text = 'ERROR'"},
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+							"order":        []any{map[string]any{"key": map[string]any{"name": "log_count"}, "direction": "desc"}},
+							"limit":        10,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_gauge_time_series",
+		Summary: "Time series: latest gauge value averaged across series",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "system.cpu.utilization", "timeAggregation": "latest", "spaceAggregation": "avg"},
+							},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "host.name", "fieldContext": "resource"}},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_rate_time_series",
+		Summary: "Time series: rate of cumulative counter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "http.server.duration.count", "timeAggregation": "rate", "spaceAggregation": "sum"},
+							},
+							"stepInterval": 120,
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_histogram_time_series",
+		Summary: "Time series: p99 latency from histogram",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "http.server.duration.bucket", "spaceAggregation": "p99"},
+							},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "logs_raw",
+		Summary: "Raw: fetch raw log records",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "raw",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "logs",
+							"filter": map[string]any{"expression": "severity_text = 'ERROR'"},
+							"selectFields": []any{
+								map[string]any{"name": "body", "fieldContext": "log"},
+								map[string]any{"name": "service.name", "fieldContext": "resource"},
+							},
+							"order": []any{
+								map[string]any{"key": map[string]any{"name": "timestamp", "fieldContext": "log"}, "direction": "desc"},
+								map[string]any{"key": map[string]any{"name": "id"}, "direction": "desc"},
+							},
+							"limit":  50,
+							"offset": 0,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "traces_raw",
+		Summary: "Raw: fetch raw span records",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "raw",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "traces",
+							"filter": map[string]any{"expression": "service.name = 'frontend' AND has_error = true"},
+							"selectFields": []any{
+								map[string]any{"name": "name", "fieldContext": "span"},
+								map[string]any{"name": "duration_nano", "fieldContext": "span"},
+							},
+							"order": []any{
+								map[string]any{"key": map[string]any{"name": "timestamp", "fieldContext": "span"}, "direction": "desc"},
+							},
+							"limit": 100,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "traces_scalar",
+		Summary: "Scalar: total span count",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "traces",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "span_count"},
+							},
+							"filter": map[string]any{"expression": "service.name = 'frontend'"},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "logs_scalar",
+		Summary: "Scalar: total error log count",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "logs",
+							"aggregations": []any{
+								map[string]any{"expression": "count()", "alias": "error_count"},
+							},
+							"filter": map[string]any{"expression": "severity_text = 'ERROR'"},
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "metrics_scalar",
+		Summary: "Scalar: single reduced metric value",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":   "A",
+							"signal": "metrics",
+							"aggregations": []any{
+								map[string]any{"metricName": "http.server.duration.count", "timeAggregation": "rate", "spaceAggregation": "sum", "reduceTo": "sum"},
+							},
+							"stepInterval": "60s",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "formula",
+		Summary: "Formula: error rate from two trace queries",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":         "A",
+							"signal":       "traces",
+							"aggregations": []any{map[string]any{"expression": "countIf(has_error = true)"}},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+					map[string]any{
+						"type": "builder_query",
+						"spec": map[string]any{
+							"name":         "B",
+							"signal":       "traces",
+							"aggregations": []any{map[string]any{"expression": "count()"}},
+							"stepInterval": "60s",
+							"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+						},
+					},
+					map[string]any{
+						"type": "builder_formula",
+						"spec": map[string]any{
+							"name":       "error_rate",
+							"expression": "A / B * 100",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "promql",
+		Summary: "PromQL: request rate with UTF-8 metric name",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "promql",
+						"spec": map[string]any{
+							"name":  "request_rate",
+							"query": "sum(rate({\"http.server.duration.count\"}[5m])) by (\"service.name\")",
+							"step":  60,
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "clickhouse_sql_traces_time_series",
+		Summary: "ClickHouse SQL: traces time series with resource filter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "time_series",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "clickhouse_sql",
+						"spec": map[string]any{
+							"name": "span_rate",
+							"query": "WITH __resource_filter AS (" +
+								" SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource" +
+								" WHERE seen_at_ts_bucket_start >= $start_timestamp - 1800 AND seen_at_ts_bucket_start <= $end_timestamp" +
+								" ) SELECT toStartOfInterval(timestamp, INTERVAL 60 SECOND) AS ts, count() AS value" +
+								" FROM signoz_traces.distributed_signoz_index_v3" +
+								" WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)" +
+								" AND timestamp >= $start_datetime AND timestamp <= $end_datetime" +
+								" AND ts_bucket_start >= $start_timestamp - 1800 AND ts_bucket_start <= $end_timestamp" +
+								" GROUP BY ts ORDER BY ts",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "clickhouse_sql_logs_raw",
+		Summary: "ClickHouse SQL: raw logs with resource filter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "raw",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "clickhouse_sql",
+						"spec": map[string]any{
+							"name": "recent_errors",
+							"query": "WITH __resource_filter AS (" +
+								" SELECT fingerprint FROM signoz_logs.distributed_logs_v2_resource" +
+								" WHERE seen_at_ts_bucket_start >= $start_timestamp - 1800 AND seen_at_ts_bucket_start <= $end_timestamp" +
+								" ) SELECT timestamp, body" +
+								" FROM signoz_logs.distributed_logs_v2" +
+								" WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)" +
+								" AND timestamp >= $start_timestamp_nano AND timestamp <= $end_timestamp_nano" +
+								" AND ts_bucket_start >= $start_timestamp - 1800 AND ts_bucket_start <= $end_timestamp" +
+								" AND severity_text = 'ERROR'" +
+								" ORDER BY timestamp DESC LIMIT 100",
+						},
+					},
+				},
+			},
+		},
+	},
+	{
+		Name:    "clickhouse_sql_traces_scalar",
+		Summary: "ClickHouse SQL: scalar aggregate with resource filter",
+		Value: map[string]any{
+			"schemaVersion": "v1",
+			"start":         1640995200000,
+			"end":           1640998800000,
+			"requestType":   "scalar",
+			"compositeQuery": map[string]any{
+				"queries": []any{
+					map[string]any{
+						"type": "clickhouse_sql",
+						"spec": map[string]any{
+							"name": "total_spans",
+							"query": "WITH __resource_filter AS (" +
+								" SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource" +
+								" WHERE seen_at_ts_bucket_start >= $start_timestamp - 1800 AND seen_at_ts_bucket_start <= $end_timestamp" +
+								" ) SELECT count() AS value" +
+								" FROM signoz_traces.distributed_signoz_index_v3" +
+								" WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)" +
+								" AND timestamp >= $start_datetime AND timestamp <= $end_datetime" +
+								" AND ts_bucket_start >= $start_timestamp - 1800 AND ts_bucket_start <= $end_timestamp",
+						},
+					},
+				},
+			},
+		},
+	},
+}

pkg/signoz/handler.go

@@ -31,6 +31,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/modules/tracefunnel/impltracefunnel"
 	"github.com/SigNoz/signoz/pkg/querier"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/zeus"
 )
 
 type Handlers struct {
@@ -48,6 +49,7 @@ type Handlers struct {
 	GatewayHandler  gateway.Handler
 	Fields          fields.Handler
 	AuthzHandler    authz.Handler
+	ZeusHandler     zeus.Handler
 }
 
 func NewHandlers(
@@ -60,6 +62,7 @@ func NewHandlers(
 	gatewayService gateway.Gateway,
 	telemetryMetadataStore telemetrytypes.MetadataStore,
 	authz authz.AuthZ,
+	zeusService zeus.Zeus,
 ) Handlers {
 	return Handlers{
 		SavedView:       implsavedview.NewHandler(modules.SavedView),
@@ -76,5 +79,6 @@ func NewHandlers(
 		GatewayHandler:  gateway.NewHandler(gatewayService),
 		Fields:          implfields.NewHandler(providerSettings, telemetryMetadataStore),
 		AuthzHandler:    signozauthzapi.NewHandler(authz),
+		ZeusHandler:     zeus.NewHandler(zeusService, licensing),
 	}
 }

pkg/signoz/handler_test.go

@@ -42,7 +42,7 @@ func TestNewHandlers(t *testing.T) {
 	dashboardModule := impldashboard.NewModule(impldashboard.NewStore(sqlstore), providerSettings, nil, orgGetter, queryParser)
 	modules := NewModules(sqlstore, tokenizer, emailing, providerSettings, orgGetter, alertmanager, nil, nil, nil, nil, nil, nil, nil, queryParser, Config{}, dashboardModule)
 
-	handlers := NewHandlers(modules, providerSettings, nil, nil, nil, nil, nil, nil, nil)
+	handlers := NewHandlers(modules, providerSettings, nil, nil, nil, nil, nil, nil, nil, nil)
 	reflectVal := reflect.ValueOf(handlers)
 	for i := 0; i < reflectVal.NumField(); i++ {
 		f := reflectVal.Field(i)

pkg/signoz/openapi.go

@@ -1,7 +1,10 @@
 package signoz
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
+	"net/http"
 	"os"
 	"reflect"
 
@@ -22,10 +25,14 @@ import (
 	"github.com/SigNoz/signoz/pkg/modules/promote"
 	"github.com/SigNoz/signoz/pkg/modules/session"
 	"github.com/SigNoz/signoz/pkg/modules/user"
+	"github.com/SigNoz/signoz/pkg/querier"
 	"github.com/SigNoz/signoz/pkg/types/ctxtypes"
+	"github.com/gorilla/mux"
+	"github.com/SigNoz/signoz/pkg/zeus"
 	"github.com/swaggest/jsonschema-go"
 	"github.com/swaggest/openapi-go"
 	"github.com/swaggest/openapi-go/openapi3"
+	"gopkg.in/yaml.v2"
 )
 
 type OpenAPI struct {
@@ -52,11 +59,16 @@ func NewOpenAPI(ctx context.Context, instrumentation instrumentation.Instrumenta
 		struct{ gateway.Handler }{},
 		struct{ fields.Handler }{},
 		struct{ authz.Handler }{},
+		struct{ zeus.Handler }{},
 	).New(ctx, instrumentation.ToProviderSettings(), apiserver.Config{})
 	if err != nil {
 		return nil, err
 	}
 
+	// Register routes that live outside the APIServer modules
+	// so they are discovered by the OpenAPI walker.
+	registerQueryRoutes(apiserver.Router())
+
 	reflector := openapi3.NewReflector()
 	reflector.JSONSchemaReflector().DefaultOptions = append(reflector.JSONSchemaReflector().DefaultOptions, jsonschema.InterceptDefName(func(t reflect.Type, defaultDefName string) string {
 		if defaultDefName == "RenderSuccessResponse" {
@@ -90,10 +102,67 @@ func (openapi *OpenAPI) CreateAndWrite(path string) error {
 		return err
 	}
 
-	spec, err := openapi.reflector.Spec.MarshalYAML()
+	// The library's MarshalYAML does a JSON round-trip that converts all numbers
+	// to float64, causing large integers (e.g. epoch millisecond timestamps) to
+	// render in scientific notation (1.6409952e+12).
+	jsonData, err := openapi.reflector.Spec.MarshalJSON()
+	if err != nil {
+		return err
+	}
+
+	dec := json.NewDecoder(bytes.NewReader(jsonData))
+	dec.UseNumber()
+
+	var v any
+	if err := dec.Decode(&v); err != nil {
+		return err
+	}
+
+	convertJSONNumbers(v)
+
+	spec, err := yaml.Marshal(v)
 	if err != nil {
 		return err
 	}
 
 	return os.WriteFile(path, spec, 0o600)
 }
+
+// convertJSONNumbers recursively walks a decoded JSON structure and converts
+// json.Number values to int64 (preferred) or float64 so that YAML marshaling
+// renders them as plain numbers instead of quoted strings.
+func convertJSONNumbers(v interface{}) {
+	switch val := v.(type) {
+	case map[string]interface{}:
+		for k, elem := range val {
+			if n, ok := elem.(json.Number); ok {
+				if i, err := n.Int64(); err == nil {
+					val[k] = i
+				} else if f, err := n.Float64(); err == nil {
+					val[k] = f
+				}
+			} else {
+				convertJSONNumbers(elem)
+			}
+		}
+	case []interface{}:
+		for i, elem := range val {
+			if n, ok := elem.(json.Number); ok {
+				if i64, err := n.Int64(); err == nil {
+					val[i] = i64
+				} else if f, err := n.Float64(); err == nil {
+					val[i] = f
+				}
+			} else {
+				convertJSONNumbers(elem)
+			}
+		}
+	}
+}
+
+func registerQueryRoutes(router *mux.Router) {
+	router.Handle("/api/v5/query_range", handler.New(
+		func(http.ResponseWriter, *http.Request) {},
+		querier.QueryRangeV5OpenAPIDef,
+	)).Methods(http.MethodPost)
+}

pkg/signoz/provider.go

@@ -252,6 +252,7 @@ func NewAPIServerProviderFactories(orgGetter organization.Getter, authz authz.Au
 			handlers.GatewayHandler,
 			handlers.Fields,
 			handlers.AuthzHandler,
+			handlers.ZeusHandler,
 		),
 	)
 }

pkg/signoz/signoz.go

@@ -392,7 +392,7 @@ func New(
 	userService := impluser.NewService(providerSettings, impluser.NewStore(sqlstore, providerSettings), modules.User, orgGetter, authz, config.User.Root)
 
 	// Initialize all handlers for the modules
-	handlers := NewHandlers(modules, providerSettings, querier, licensing, global, flagger, gateway, telemetryMetadataStore, authz)
+	handlers := NewHandlers(modules, providerSettings, querier, licensing, global, flagger, gateway, telemetryMetadataStore, authz, zeus)
 
 	// Initialize the API server
 	apiserver, err := factory.NewProviderFromNamedMap(

pkg/types/metrictypes/metrictypes.go

@@ -172,7 +172,6 @@ var (
 
 func (TimeAggregation) Enum() []any {
 	return []any{
-		TimeAggregationUnspecified,
 		TimeAggregationLatest,
 		TimeAggregationSum,
 		TimeAggregationAvg,
@@ -205,7 +204,6 @@ var (
 
 func (SpaceAggregation) Enum() []any {
 	return []any{
-		SpaceAggregationUnspecified,
 		SpaceAggregationSum,
 		SpaceAggregationAvg,
 		SpaceAggregationMin,

pkg/types/querybuildertypes/querybuildertypesv5/builder_elements.go

@@ -10,10 +10,35 @@ import (
 	"github.com/SigNoz/signoz/pkg/types/metrictypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/swaggest/jsonschema-go"
 )
 
 type Step struct{ time.Duration }
 
+var _ jsonschema.Exposer = Step{}
+
+// JSONSchema returns a custom schema for Step that accepts either a duration string or a number (seconds).
+func (Step) JSONSchema() (jsonschema.Schema, error) {
+	s := jsonschema.Schema{}
+	s.WithDescription("Step interval. Accepts a Go duration string (e.g., \"60s\", \"1m\", \"1h\") or a number representing seconds (e.g., 60).")
+
+	strSchema := jsonschema.Schema{}
+	strSchema.WithType(jsonschema.String.Type())
+	strSchema.WithExamples("60s", "5m", "1h")
+	strSchema.WithDescription("Duration string (e.g., \"60s\", \"5m\", \"1h\").")
+
+	numSchema := jsonschema.Schema{}
+	numSchema.WithType(jsonschema.Number.Type())
+	numSchema.WithExamples(60, 300, 3600)
+	numSchema.WithDescription("Duration in seconds.")
+
+	s.OneOf = []jsonschema.SchemaOrBool{
+		strSchema.ToSchemaOrBool(),
+		numSchema.ToSchemaOrBool(),
+	}
+	return s, nil
+}
+
 func (s *Step) UnmarshalJSON(b []byte) error {
 	if len(b) == 0 {
 		return nil
@@ -181,6 +206,14 @@ var (
 	OrderDirectionDesc = OrderDirection{valuer.NewString("desc")}
 )
 
+// Enum returns the acceptable values for OrderDirection.
+func (OrderDirection) Enum() []any {
+	return []any{
+		OrderDirectionAsc,
+		OrderDirectionDesc,
+	}
+}
+
 var (
 	OrderDirectionMap = map[string]OrderDirection{
 		"asc":  OrderDirectionAsc,
@@ -203,6 +236,19 @@ var (
 	ReduceToMedian  = ReduceTo{valuer.NewString("median")}
 )
 
+// Enum returns the acceptable values for ReduceTo.
+func (ReduceTo) Enum() []any {
+	return []any{
+		ReduceToSum,
+		ReduceToCount,
+		ReduceToAvg,
+		ReduceToMin,
+		ReduceToMax,
+		ReduceToLast,
+		ReduceToMedian,
+	}
+}
+
 // FunctionReduceTo applies the reduceTo operator to a time series and returns a new series with the reduced value
 // reduceTo can be one of: last, sum, avg, min, max, count, median
 // if reduceTo is not recognized, the function returns the original series

pkg/types/querybuildertypes/querybuildertypesv5/functions.go

@@ -36,6 +36,30 @@ var (
 	FunctionNameFillZero      = FunctionName{valuer.NewString("fillZero")}
 )
 
+// Enum returns the acceptable values for FunctionName.
+func (FunctionName) Enum() []any {
+	return []any{
+		FunctionNameCutOffMin,
+		FunctionNameCutOffMax,
+		FunctionNameClampMin,
+		FunctionNameClampMax,
+		FunctionNameAbsolute,
+		FunctionNameRunningDiff,
+		FunctionNameLog2,
+		FunctionNameLog10,
+		FunctionNameCumulativeSum,
+		FunctionNameEWMA3,
+		FunctionNameEWMA5,
+		FunctionNameEWMA7,
+		FunctionNameMedian3,
+		FunctionNameMedian5,
+		FunctionNameMedian7,
+		FunctionNameTimeShift,
+		FunctionNameAnomaly,
+		FunctionNameFillZero,
+	}
+}
+
 // Validate checks if the FunctionName is valid and one of the known types
 func (fn FunctionName) Validate() error {
 	validFunctions := []FunctionName{

pkg/types/querybuildertypes/querybuildertypesv5/join.go

@@ -16,6 +16,17 @@ var (
 	JoinTypeCross = JoinType{valuer.NewString("cross")}
 )
 
+// Enum returns the acceptable values for JoinType.
+func (JoinType) Enum() []any {
+	return []any{
+		JoinTypeInner,
+		JoinTypeLeft,
+		JoinTypeRight,
+		JoinTypeFull,
+		JoinTypeCross,
+	}
+}
+
 type QueryRef struct {
 	Name string `json:"name"`
 }

pkg/types/querybuildertypes/querybuildertypesv5/query.go

@@ -2,6 +2,8 @@ package querybuildertypesv5
 
 import (
 	"context"
+
+	"github.com/swaggest/jsonschema-go"
 )
 
 type Query interface {
@@ -29,4 +31,12 @@ type ExecStats struct {
 	StepIntervals map[string]uint64 `json:"stepIntervals,omitempty"`
 }
 
+var _ jsonschema.Preparer = &ExecStats{}
+
+// PrepareJSONSchema adds description to the ExecStats schema.
+func (e *ExecStats) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Execution statistics for the query, including rows scanned, bytes scanned, and duration.")
+	return nil
+}
+
 type TimeRange struct{ From, To uint64 } // ms since epoch

pkg/types/querybuildertypes/querybuildertypesv5/query_type.go

@@ -16,3 +16,17 @@ var (
 	QueryTypeClickHouseSQL = QueryType{valuer.NewString("clickhouse_sql")}
 	QueryTypePromQL        = QueryType{valuer.NewString("promql")}
 )
+
+// Enum returns the acceptable values for QueryType.
+func (QueryType) Enum() []any {
+	return []any{
+		QueryTypeBuilder,
+		QueryTypeFormula,
+		// Not yet supported.
+		// QueryTypeSubQuery,
+		// QueryTypeJoin,
+		QueryTypeTraceOperator,
+		QueryTypeClickHouseSQL,
+		QueryTypePromQL,
+	}
+}

pkg/types/querybuildertypes/querybuildertypesv5/req.go

@@ -9,6 +9,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/types/metrictypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/swaggest/jsonschema-go"
 )
 
 type QueryEnvelope struct {
@@ -18,6 +19,71 @@ type QueryEnvelope struct {
 	Spec any `json:"spec"`
 }
 
+// queryEnvelopeBuilderTrace is the OpenAPI schema for a QueryEnvelope with type=builder_query and signal=traces.
+type queryEnvelopeBuilderTrace struct {
+	Type QueryType                           `json:"type" description:"The type of the query."`
+	Spec QueryBuilderQuery[TraceAggregation] `json:"spec" description:"The trace builder query specification."`
+}
+
+// queryEnvelopeBuilderLog is the OpenAPI schema for a QueryEnvelope with type=builder_query and signal=logs.
+type queryEnvelopeBuilderLog struct {
+	Type QueryType                         `json:"type" description:"The type of the query."`
+	Spec QueryBuilderQuery[LogAggregation] `json:"spec" description:"The log builder query specification."`
+}
+
+// queryEnvelopeBuilderMetric is the OpenAPI schema for a QueryEnvelope with type=builder_query and signal=metrics.
+type queryEnvelopeBuilderMetric struct {
+	Type QueryType                            `json:"type" description:"The type of the query."`
+	Spec QueryBuilderQuery[MetricAggregation] `json:"spec" description:"The metric builder query specification."`
+}
+
+// queryEnvelopeFormula is the OpenAPI schema for a QueryEnvelope with type=builder_formula.
+type queryEnvelopeFormula struct {
+	Type QueryType           `json:"type" description:"The type of the query."`
+	Spec QueryBuilderFormula `json:"spec" description:"The formula specification."`
+}
+
+// queryEnvelopeJoin is the OpenAPI schema for a QueryEnvelope with type=builder_join.
+// type queryEnvelopeJoin struct {
+// 	Type QueryType        `json:"type" description:"The type of the query."`
+// 	Spec QueryBuilderJoin `json:"spec" description:"The join specification."`
+// }
+
+// queryEnvelopeTraceOperator is the OpenAPI schema for a QueryEnvelope with type=builder_trace_operator.
+type queryEnvelopeTraceOperator struct {
+	Type QueryType                 `json:"type" description:"The type of the query."`
+	Spec QueryBuilderTraceOperator `json:"spec" description:"The trace operator specification."`
+}
+
+// queryEnvelopePromQL is the OpenAPI schema for a QueryEnvelope with type=promql.
+type queryEnvelopePromQL struct {
+	Type QueryType `json:"type" description:"The type of the query."`
+	Spec PromQuery `json:"spec" description:"The PromQL query specification."`
+}
+
+// queryEnvelopeClickHouseSQL is the OpenAPI schema for a QueryEnvelope with type=clickhouse_sql.
+type queryEnvelopeClickHouseSQL struct {
+	Type QueryType       `json:"type" description:"The type of the query."`
+	Spec ClickHouseQuery `json:"spec" description:"The ClickHouse SQL query specification."`
+}
+
+var _ jsonschema.OneOfExposer = QueryEnvelope{}
+
+// JSONSchemaOneOf returns the oneOf variants for the QueryEnvelope discriminated union.
+// Each variant represents a different query type with its corresponding spec schema.
+func (QueryEnvelope) JSONSchemaOneOf() []any {
+	return []any{
+		queryEnvelopeBuilderTrace{},
+		queryEnvelopeBuilderLog{},
+		queryEnvelopeBuilderMetric{},
+		queryEnvelopeFormula{},
+		// queryEnvelopeJoin{},
+		queryEnvelopeTraceOperator{},
+		queryEnvelopePromQL{},
+		queryEnvelopeClickHouseSQL{},
+	}
+}
+
 // implement custom json unmarshaler for the QueryEnvelope
 func (q *QueryEnvelope) UnmarshalJSON(data []byte) error {
 	var shadow struct {
@@ -130,6 +196,12 @@ type CompositeQuery struct {
 	Queries []QueryEnvelope `json:"queries"`
 }
 
+// PrepareJSONSchema adds description to the CompositeQuery schema.
+func (c *CompositeQuery) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Composite query containing one or more query envelopes. Each query envelope specifies its type and corresponding spec.")
+	return nil
+}
+
 // UnmarshalJSON implements custom JSON unmarshaling to provide better error messages
 func (c *CompositeQuery) UnmarshalJSON(data []byte) error {
 	type Alias CompositeQuery
@@ -192,6 +264,16 @@ var (
 	TextBoxVariableType = VariableType{valuer.NewString("text")}
 )
 
+// Enum returns the acceptable values for VariableType.
+func (VariableType) Enum() []any {
+	return []any{
+		QueryVariableType,
+		DynamicVariableType,
+		CustomVariableType,
+		TextBoxVariableType,
+	}
+}
+
 type VariableItem struct {
 	Type  VariableType `json:"type"`
 	Value any          `json:"value"`
@@ -217,6 +299,12 @@ type QueryRangeRequest struct {
 	FormatOptions *FormatOptions `json:"formatOptions,omitempty"`
 }
 
+// PrepareJSONSchema adds description to the QueryRangeRequest schema.
+func (q *QueryRangeRequest) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Request body for the v5 query range endpoint. Supports builder queries (traces, logs, metrics), formulas, joins, trace operators, PromQL, and ClickHouse SQL queries.")
+	return nil
+}
+
 func (r *QueryRangeRequest) StepIntervalForQuery(name string) int64 {
 	stepsMap := make(map[string]int64)
 	for _, query := range r.CompositeQuery.Queries {

pkg/types/querybuildertypes/querybuildertypesv5/request_type.go

@@ -30,3 +30,15 @@ var (
 func (r RequestType) IsAggregation() bool {
 	return r == RequestTypeTimeSeries || r == RequestTypeScalar || r == RequestTypeDistribution
 }
+
+// Enum implements jsonschema.Enum; returns the acceptable values for RequestType.
+func (RequestType) Enum() []any {
+	return []any{
+		RequestTypeScalar,
+		RequestTypeTimeSeries,
+		RequestTypeRaw,
+		RequestTypeRawStream,
+		RequestTypeTrace,
+		// RequestTypeDistribution,
+	}
+}

pkg/types/querybuildertypes/querybuildertypesv5/resp.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/swaggest/jsonschema-go"
 )
 
 type QBEvent struct {
@@ -42,6 +43,17 @@ type QueryData struct {
 	Results []any `json:"results"`
 }
 
+var _ jsonschema.OneOfExposer = QueryData{}
+
+// JSONSchemaOneOf documents the polymorphic result types in QueryData.Results.
+func (QueryData) JSONSchemaOneOf() []any {
+	return []any{
+		TimeSeriesData{},
+		ScalarData{},
+		RawData{},
+	}
+}
+
 type QueryRangeResponse struct {
 	Type RequestType `json:"type"`
 	Data QueryData   `json:"data"`
@@ -52,6 +64,14 @@ type QueryRangeResponse struct {
 	QBEvent *QBEvent `json:"-"`
 }
 
+var _ jsonschema.Preparer = &QueryRangeResponse{}
+
+// PrepareJSONSchema adds description to the QueryRangeResponse schema.
+func (q *QueryRangeResponse) PrepareJSONSchema(schema *jsonschema.Schema) error {
+	schema.WithDescription("Response from the v5 query range endpoint. The data.results array contains typed results depending on the requestType: TimeSeriesData for time_series, ScalarData for scalar, or RawData for raw requests.")
+	return nil
+}
+
 type TimeSeriesData struct {
 	QueryName    string               `json:"queryName"`
 	Aggregations []*AggregationBucket `json:"aggregations"`
@@ -159,6 +179,14 @@ var (
 	ColumnTypeAggregation = ColumnType{valuer.NewString("aggregation")}
 )
 
+// Enum returns the acceptable values for ColumnType.
+func (ColumnType) Enum() []any {
+	return []any{
+		ColumnTypeGroup,
+		ColumnTypeAggregation,
+	}
+}
+
 type ColumnDescriptor struct {
 	telemetrytypes.TelemetryFieldKey
 	QueryName        string `json:"queryName"`

pkg/types/telemetrytypes/field_context.go

@@ -172,3 +172,18 @@ func isContextValidForSignal(ctx FieldContext, signal Signal) bool {
 	}
 	return true
 }
+
+// Enum returns the acceptable values for FieldContext.
+func (FieldContext) Enum() []any {
+	return []any{
+		FieldContextMetric,
+		FieldContextLog,
+		FieldContextSpan,
+		// FieldContextTrace,
+		FieldContextResource,
+		// FieldContextScope,
+		FieldContextAttribute,
+		// FieldContextEvent,
+		FieldContextBody,
+	}
+}

pkg/types/telemetrytypes/field_datatype.go

@@ -177,3 +177,19 @@ func (f FieldDataType) TagDataType() string {
 		return "string"
 	}
 }
+
+// Enum returns the acceptable values for FieldDataType.
+func (FieldDataType) Enum() []any {
+	return []any{
+		FieldDataTypeString,
+		FieldDataTypeBool,
+		FieldDataTypeFloat64,
+		FieldDataTypeInt64,
+		FieldDataTypeNumber,
+		// FieldDataTypeArrayString,
+		// FieldDataTypeArrayFloat64,
+		// FieldDataTypeArrayBool,
+		// FieldDataTypeArrayInt64,
+		// FieldDataTypeArrayNumber,
+	}
+}

pkg/types/telemetrytypes/signal.go

@@ -12,3 +12,12 @@ var (
 	SignalMetrics     = Signal{valuer.NewString("metrics")}
 	SignalUnspecified = Signal{valuer.NewString("")}
 )
+
+// Enum returns the acceptable values for Signal.
+func (Signal) Enum() []any {
+	return []any{
+		SignalTraces,
+		SignalLogs,
+		SignalMetrics,
+	}
+}

pkg/types/telemetrytypes/source.go

@@ -10,3 +10,10 @@ var (
 	SourceMeter       = Source{valuer.NewString("meter")}
 	SourceUnspecified = Source{valuer.NewString("")}
 )
+
+// Enum returns the acceptable values for Source.
+func (Source) Enum() []any {
+	return []any{
+		SourceMeter,
+	}
+}

pkg/types/zeustypes/types.go

@@ -0,0 +1,54 @@
+package zeustypes
+
+import "github.com/tidwall/gjson"
+
+type PostableHost struct {
+	Name string `json:"name" required:"true"`
+}
+
+type PostableProfile struct {
+	UsesOtel                     bool     `json:"uses_otel"`
+	HasExistingObservabilityTool bool     `json:"has_existing_observability_tool"`
+	ExistingObservabilityTool    string   `json:"existing_observability_tool"`
+	ReasonsForInterestInSigNoz   []string `json:"reasons_for_interest_in_signoz"`
+	LogsScalePerDayInGB          int64    `json:"logs_scale_per_day_in_gb"`
+	NumberOfServices             int64    `json:"number_of_services"`
+	NumberOfHosts                int64    `json:"number_of_hosts"`
+	WhereDidYouDiscoverSigNoz    string   `json:"where_did_you_discover_signoz"`
+	TimelineForMigratingToSigNoz string   `json:"timeline_for_migrating_to_signoz"`
+}
+
+type GettableZeusHost struct {
+	Name  string `json:"name"`
+	State string `json:"state"`
+	Tier  string `json:"tier"`
+	Hosts []Host `json:"hosts"`
+}
+
+type Host struct {
+	Name      string `json:"name"`
+	IsDefault bool   `json:"is_default"`
+	URL       string `json:"url"`
+}
+
+func NewGettableZeusHost(data []byte) *GettableZeusHost {
+	parsed := gjson.ParseBytes(data)
+	dns := parsed.Get("cluster.region.dns").String()
+
+	hostResults := parsed.Get("hosts").Array()
+	hosts := make([]Host, len(hostResults))
+
+	for i, h := range hostResults {
+		name := h.Get("name").String()
+		hosts[i].Name = name
+		hosts[i].IsDefault = h.Get("is_default").Bool()
+		hosts[i].URL = name + "." + dns
+	}
+
+	return &GettableZeusHost{
+		Name:  parsed.Get("name").String(),
+		State: parsed.Get("state").String(),
+		Tier:  parsed.Get("tier").String(),
+		Hosts: hosts,
+	}
+}

pkg/zeus/handler.go

@@ -0,0 +1,114 @@
+package zeus
+
+import (
+	"net/http"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/http/binding"
+	"github.com/SigNoz/signoz/pkg/http/render"
+	"github.com/SigNoz/signoz/pkg/licensing"
+	"github.com/SigNoz/signoz/pkg/types/authtypes"
+	"github.com/SigNoz/signoz/pkg/types/zeustypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+type handler struct {
+	zeus      Zeus
+	licensing licensing.Licensing
+}
+
+func NewHandler(zeus Zeus, licensing licensing.Licensing) Handler {
+	return &handler{
+		zeus:      zeus,
+		licensing: licensing,
+	}
+}
+
+func (h *handler) PutProfile(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	claims, err := authtypes.ClaimsFromContext(ctx)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	license, err := h.licensing.GetActive(ctx, valuer.MustNewUUID(claims.OrgID))
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	req := new(zeustypes.PostableProfile)
+	if err := binding.JSON.BindBody(r.Body, req); err != nil {
+		render.Error(rw, errors.New(errors.TypeInvalidInput, errors.CodeInvalidInput, "invalid request body"))
+		return
+	}
+
+	if err := h.zeus.PutProfile(ctx, license.Key, req); err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	render.Success(rw, http.StatusNoContent, nil)
+}
+
+func (h *handler) GetHostFromZeus(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	claims, err := authtypes.ClaimsFromContext(ctx)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	license, err := h.licensing.GetActive(ctx, valuer.MustNewUUID(claims.OrgID))
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	deploymentBytes, err := h.zeus.GetDeployment(ctx, license.Key)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	response := zeustypes.NewGettableZeusHost(deploymentBytes)
+
+	render.Success(rw, http.StatusOK, response)
+}
+
+func (h *handler) PutHost(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	claims, err := authtypes.ClaimsFromContext(ctx)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	license, err := h.licensing.GetActive(ctx, valuer.MustNewUUID(claims.OrgID))
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	req := new(zeustypes.PostableHost)
+	if err := binding.JSON.BindBody(r.Body, req); err != nil {
+		render.Error(rw, errors.New(errors.TypeInvalidInput, errors.CodeInvalidInput, "invalid request body"))
+		return
+	}
+
+	if req.Name == "" {
+		render.Error(rw, errors.New(errors.TypeInvalidInput, errors.CodeInvalidInput, "name is required"))
+		return
+	}
+
+	if err := h.zeus.PutHost(ctx, license.Key, req); err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	render.Success(rw, http.StatusNoContent, nil)
+}

pkg/zeus/noopzeus/provider.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/types/zeustypes"
 	"github.com/SigNoz/signoz/pkg/zeus"
 )
 
@@ -40,10 +41,10 @@ func (provider *provider) PutMeters(_ context.Context, _ string, _ []byte) error
 	return errors.New(errors.TypeUnsupported, zeus.ErrCodeUnsupported, "putting meters is not supported")
 }
 
-func (provider *provider) PutProfile(_ context.Context, _ string, _ []byte) error {
+func (provider *provider) PutProfile(_ context.Context, _ string, _ *zeustypes.PostableProfile) error {
 	return errors.New(errors.TypeUnsupported, zeus.ErrCodeUnsupported, "putting profile is not supported")
 }
 
-func (provider *provider) PutHost(_ context.Context, _ string, _ []byte) error {
+func (provider *provider) PutHost(_ context.Context, _ string, _ *zeustypes.PostableHost) error {
 	return errors.New(errors.TypeUnsupported, zeus.ErrCodeUnsupported, "putting host is not supported")
 }

pkg/zeus/zeus.go

@@ -2,8 +2,10 @@ package zeus
 
 import (
 	"context"
+	"net/http"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/types/zeustypes"
 )
 
 var (
@@ -28,8 +30,19 @@ type Zeus interface {
 	PutMeters(context.Context, string, []byte) error
 
 	// Put profile for the given license key.
-	PutProfile(context.Context, string, []byte) error
+	PutProfile(context.Context, string, *zeustypes.PostableProfile) error
 
 	// Put host for the given license key.
-	PutHost(context.Context, string, []byte) error
+	PutHost(context.Context, string, *zeustypes.PostableHost) error
+}
+
+type Handler interface {
+	// API level handler for PutProfile
+	PutProfile(http.ResponseWriter, *http.Request)
+
+	// API level handler for GetDeployment
+	GetHostFromZeus(http.ResponseWriter, *http.Request)
+
+	// API level handler for PutHost
+	PutHost(http.ResponseWriter, *http.Request)
 }