api

Documentation

Index

• Constants
• func Error(w http.ResponseWriter, status int, code string, message string)
• func ErrorWithDetails(w http.ResponseWriter, status int, code string, message string, ...)
• func JSON(w http.ResponseWriter, status int, data interface{})
• func NewRouter(cfg RouterConfig) *mux.Router
• type ErrorResponse
• type RouterConfig

Constants

const (
	ErrCodeInvalidRequest   = "invalid_request"
	ErrCodeNotFound         = "not_found"
	ErrCodeUnauthorized     = "unauthorized"
	ErrCodeForbidden        = "forbidden"
	ErrCodeRateLimited      = "rate_limited"
	ErrCodeInternalError    = "internal_error"
	ErrCodeServiceUnavail   = "service_unavailable"
	ErrCodeFileTooLarge     = "file_too_large"
	ErrCodeUnsupportedMedia = "unsupported_media_type"
	ErrCodeConflict         = "conflict"
)

Standard error codes aligned with the OpenAPI spec.

Functions

func Error

func Error(w http.ResponseWriter, status int, code string, message string)

Error writes a standardised error response.

func ErrorWithDetails

func ErrorWithDetails(w http.ResponseWriter, status int, code string, message string, details interface{})

ErrorWithDetails writes a standardised error response that includes additional structured details (e.g. validation errors).

func JSON

func JSON(w http.ResponseWriter, status int, data interface{})

JSON writes a JSON response with the given HTTP status code. If encoding fails the error is logged, but the status code has already been sent on the wire so the client will receive the original status with a potentially truncated body.

func NewRouter

func NewRouter(cfg RouterConfig) *mux.Router

NewRouter builds a fully-configured *mux.Router with all routes from the OpenAPI specification and the middleware chain applied.

Types

type ErrorResponse

type ErrorResponse struct {
	Code    string      `json:"code"`
	Message string      `json:"message"`
	Details interface{} `json:"details,omitempty"`
}

ErrorResponse is the standard error envelope returned to clients.

type RouterConfig

type RouterConfig struct {
	// AllowedOrigins for CORS. Use ["*"] during development.
	AllowedOrigins []string

	// DevMode enables development conveniences such as auth bypass headers.
	DevMode bool

	// ClerkSecretKey is the Clerk JWT signing secret.
	ClerkSecretKey string

	// HealthHandler serves GET /api/v1/health.
	HealthHandler http.Handler

	// File handlers
	UploadFileHandler http.Handler // POST /api/v1/files/upload
	ListFilesHandler  http.Handler // GET  /api/v1/files

	// Analysis handlers
	CreateAnalysisHandler     http.Handler // POST /api/v1/analysis
	ListAnalysesHandler       http.Handler // GET  /api/v1/analysis
	GetAnalysisHandler        http.Handler // GET  /api/v1/analysis/{job_id}
	GetDashboardHandler       http.Handler // GET  /api/v1/analysis/{job_id}/dashboard
	AggregatesHandler         http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/aggregates
	ExceptionsHandler         http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/exceptions
	GapsHandler               http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/gaps
	ThreadsHandler            http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/threads
	FiltersHandler            http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/filters
	QueuedCallsHandler        http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/queued-calls
	LoggingActivityHandler    http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/logging-activity
	FileMetadataHandler       http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/file-metadata
	DelayedEscalationsHandler http.Handler // GET  /api/v1/analysis/{job_id}/dashboard/delayed-escalations
	SearchLogsHandler         http.Handler // GET  /api/v1/analysis/{job_id}/search
	GetLogEntryHandler        http.Handler // GET  /api/v1/analysis/{job_id}/entries/{entry_id}
	GetEntryContextHandler    http.Handler // GET  /api/v1/analysis/{job_id}/entries/{entry_id}/context
	GetTraceHandler           http.Handler // GET  /api/v1/analysis/{job_id}/trace/{trace_id}
	GetWaterfallHandler       http.Handler // GET  /api/v1/analysis/{job_id}/trace/{trace_id}/waterfall
	SearchTransactionsHandler http.Handler // GET  /api/v1/analysis/{job_id}/transactions
	ExportTraceHandler        http.Handler // GET  /api/v1/analysis/{job_id}/trace/{trace_id}/export
	TraceAIHandler            http.Handler // POST /api/v1/analysis/{job_id}/trace/ai-analyze
	GetRecentTracesHandler    http.Handler // GET  /api/v1/trace/recent
	ExportHandler             http.Handler // GET  /api/v1/analysis/{job_id}/search/export
	QueryAIHandler            http.Handler // POST /api/v1/analysis/{job_id}/ai
	GenerateReportHandler     http.Handler // POST /api/v1/analysis/{job_id}/report

	// Search handlers
	AutocompleteHandler      http.Handler // GET  /api/v1/search/autocomplete
	SavedSearchHandler       http.Handler // GET/POST /api/v1/search/saved
	DeleteSavedSearchHandler http.Handler // DELETE /api/v1/search/saved/{search_id}
	SearchHistoryHandler     http.Handler // GET  /api/v1/search/history

	// WebSocket handler
	WSHandler http.Handler // GET /api/v1/ws

	// AI handlers
	AIStreamHandler           http.Handler // POST /api/v1/ai/stream
	ListSkillsHandler         http.Handler // GET /api/v1/ai/skills
	ConversationsHandler      http.Handler // GET/POST /api/v1/ai/conversations
	ConversationDetailHandler http.Handler // GET/DELETE /api/v1/ai/conversations/{id}
}

RouterConfig holds all dependencies required to build the API router. Handler fields that are nil will receive a default "not implemented" handler, allowing the router to be constructed incrementally as features are built out.