api

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2026 License: Apache-2.0, BSD-3-Clause, MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	APIVersion = "v1"
	APIPrefix  = "/api/v1"
)

API version

Variables

This section is empty.

Functions

This section is empty.

Types

type APIMeta 

type APIMeta struct {
	RequestID   string  `json:"request_id,omitempty"`
	ProcessTime float64 `json:"process_time_ms,omitempty"`
	Version     string  `json:"version"`
}

APIMeta contains response metadata

type APIResponse 

type APIResponse struct {
	OK      bool        `json:"ok"`
	Data    interface{} `json:"data,omitempty"`
	Error   string      `json:"error,omitempty"`   // Error code (e.g., "BAD_REQUEST", "NOT_FOUND")
	Message string      `json:"message,omitempty"` // Human-readable error message
	Meta    *APIMeta    `json:"meta,omitempty"`    // Optional metadata (request_id, process_time_ms)
}

APIResponse is the base response structure Per AI.md PART 16: Unified Response Format (NON-NEGOTIABLE) Success: {"ok": true, "data": {...}} Error: {"ok": false, "error": "ERROR_CODE", "message": "Human readable message"}

type AuthHandler 

type AuthHandler struct {
	// contains filtered or unexported fields
}

AuthHandler handles authentication API requests

func NewAuthHandler 

func NewAuthHandler(cfg *config.Config, db *sql.DB, authManager *userpkg.AuthManager, totpManager *userpkg.TOTPManager, recoveryManager *userpkg.RecoveryManager, verificationManager *userpkg.VerificationManager) *AuthHandler

NewAuthHandler creates a new auth API handler

func (*AuthHandler) RegisterRoutes 

func (h *AuthHandler) RegisterRoutes(mux *http.ServeMux)

RegisterRoutes registers auth API routes

type AutodiscoverResponse 

type AutodiscoverResponse struct {
	Server struct {
		Name     string `json:"name"`
		Version  string `json:"version"`
		URL      string `json:"url"`
		Features struct {
			Auth     bool `json:"auth"`
			Search   bool `json:"search"`
			Register bool `json:"register"`
		} `json:"features"`
	} `json:"server"`
	Cluster struct {
		Primary string   `json:"primary"`
		Nodes   []string `json:"nodes"`
	} `json:"cluster"`
	API struct {
		Version  string `json:"version"`
		BasePath string `json:"base_path"`
	} `json:"api"`
}

AutodiscoverResponse represents /api/autodiscover response Per AI.md PART 36 line 38077-38157: Autodiscover endpoint for CLI/agent

type BangInfo 

type BangInfo struct {
	Shortcut    string   `json:"shortcut"`
	Name        string   `json:"name"`
	URL         string   `json:"url"`
	Category    string   `json:"category"`
	Description string   `json:"description,omitempty"`
	Aliases     []string `json:"aliases,omitempty"`
}

BangInfo represents bang information for API

type BuildInfo 

type BuildInfo struct {
	Commit string `json:"commit"` // git short hash (7 chars)
	Date   string `json:"date"`   // ISO 8601 build timestamp
}

BuildInfo represents build information per AI.md PART 13 Note: Fields are "commit" and "date" per spec, not "commit_id" and "build_date"

type CategoryInfo 

type CategoryInfo struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Icon        string `json:"icon"`
}

CategoryInfo represents category information

type ChangePasswordRequest 

type ChangePasswordRequest struct {
	CurrentPassword string `json:"current_password"`
	NewPassword     string `json:"new_password"`
}

ChangePasswordRequest represents a password change request

type ChecksInfo 

type ChecksInfo struct {
	Database  string `json:"database"`          // PART 10: "ok" or "error"
	Cache     string `json:"cache"`             // PART 10: "ok" or "error"
	Disk      string `json:"disk"`              // Disk space check
	Scheduler string `json:"scheduler"`         // PART 19: "ok" or "error"
	Cluster   string `json:"cluster,omitempty"` // PART 10: "ok" or "error" (if enabled)
	Tor       string `json:"tor,omitempty"`     // PART 32: "ok" or "error" (if enabled)
}

ChecksInfo represents component health per AI.md PART 13 (line 16298-16308)

type ClusterInfo 

type ClusterInfo struct {
	Enabled   bool     `json:"enabled"`
	Status    string   `json:"status,omitempty"`     // "connected", "disconnected"
	Primary   string   `json:"primary,omitempty"`    // primary node public URL
	Nodes     []string `json:"nodes,omitempty"`      // all node public URLs
	NodeCount int      `json:"node_count,omitempty"` // total nodes
	Role      string   `json:"role,omitempty"`       // "primary" or "member"
}

ClusterInfo represents cluster status per AI.md PART 13

type CreateTokenRequest 

type CreateTokenRequest struct {
	Name        string   `json:"name"`
	Permissions []string `json:"permissions"`
	ExpiresIn   int      `json:"expires_in_days"`
}

CreateTokenRequest represents a token creation request

type DirectAnswerResponse 

type DirectAnswerResponse struct {
	Type        string                 `json:"type"`
	Term        string                 `json:"term"`
	Title       string                 `json:"title"`
	Description string                 `json:"description,omitempty"`
	Content     string                 `json:"content"`
	Data        map[string]interface{} `json:"data,omitempty"`
	Source      string                 `json:"source,omitempty"`
	SourceURL   string                 `json:"source_url,omitempty"`
	CacheTTL    int                    `json:"cache_ttl_seconds,omitempty"`
	Error       string                 `json:"error,omitempty"`
	Found       bool                   `json:"found"`
}

DirectAnswerResponse represents direct answer API response

type Disable2FARequest 

type Disable2FARequest struct {
	Password string `json:"password"`
	Code     string `json:"code"`
}

Disable2FARequest represents a 2FA disable request

type Enable2FARequest 

type Enable2FARequest struct {
	Code string `json:"code"`
}

Enable2FARequest represents a 2FA enable request

type EngineInfo 

type EngineInfo struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Enabled     bool     `json:"enabled"`
	Priority    int      `json:"priority"`
	Categories  []string `json:"categories"`
	Description string   `json:"description,omitempty"`
	Homepage    string   `json:"homepage,omitempty"`
}

EngineInfo represents engine information

type EnginesSummary 

type EnginesSummary struct {
	Total   int `json:"total"`
	Enabled int `json:"enabled"`
}

EnginesSummary provides engine statistics

type FeaturesInfo 

type FeaturesInfo struct {
	Tor           TorInfo `json:"tor"`                     // PART 32: Tor Hidden Service
	GeoIP         bool    `json:"geoip"`                   // PART 20: GeoIP enabled
	MultiUser     bool    `json:"multi_user,omitempty"`    // PART 34: Multi-user mode
	Organizations bool    `json:"organizations,omitempty"` // PART 35: Organizations
}

FeaturesInfo represents feature status per AI.md PART 13 (line 16269-16288)

type ForgotPasswordRequest 

type ForgotPasswordRequest struct {
	Email string `json:"email"`
}

ForgotPasswordRequest represents a password reset request

type GraphQLHandler 

type GraphQLHandler struct {
	// contains filtered or unexported fields
}

GraphQLHandler handles GraphQL requests

func NewGraphQLHandler 

func NewGraphQLHandler(h *Handler) (*GraphQLHandler, error)

NewGraphQLHandler creates a new GraphQL handler

func (*GraphQLHandler) ServeGraphiQL 

func (g *GraphQLHandler) ServeGraphiQL(w http.ResponseWriter, r *http.Request)

ServeGraphiQL serves the GraphiQL UI

func (*GraphQLHandler) ServeHTTP 

func (g *GraphQLHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles GraphQL HTTP requests

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler handles API requests

func NewHandler 

func NewHandler(cfg *config.Config, registry *engines.Registry, aggregator *search.Aggregator) *Handler

NewHandler creates a new API handler

func (*Handler) HandleAutocomplete 

func (h *Handler) HandleAutocomplete(w http.ResponseWriter, r *http.Request)

HandleAutocomplete is the public method for autocomplete suggestions

func (*Handler) RegisterGraphQLRoutes 

func (h *Handler) RegisterGraphQLRoutes(mux *http.ServeMux) error

RegisterGraphQLRoutes registers GraphQL routes per AI.md spec /graphql GET → GraphiQL interface /graphql POST → GraphQL queries

func (*Handler) RegisterOpenAPIRoutes 

func (h *Handler) RegisterOpenAPIRoutes(mux *http.ServeMux)

RegisterOpenAPIRoutes registers the OpenAPI/Swagger routes Per AI.md spec: /openapi (Swagger UI), /openapi.json (JSON only, no YAML)

func (*Handler) RegisterRoutes 

func (h *Handler) RegisterRoutes(mux *http.ServeMux)

RegisterRoutes registers API routes

func (*Handler) ServeOpenAPISpec 

func (h *Handler) ServeOpenAPISpec(w http.ResponseWriter, r *http.Request)

ServeOpenAPISpec serves the OpenAPI JSON specification Per AI.md spec: JSON only, no YAML endpoint

func (*Handler) ServeSwaggerUI 

func (h *Handler) ServeSwaggerUI(w http.ResponseWriter, r *http.Request)

ServeSwaggerUI serves the Swagger UI HTML page

func (*Handler) SetDirectManager 

func (h *Handler) SetDirectManager(dm *direct.Manager)

SetDirectManager sets the direct answer manager for the API handler

func (*Handler) SetInstantManager 

func (h *Handler) SetInstantManager(im *instant.Manager)

SetInstantManager sets the instant answer manager for the API handler

func (*Handler) SetRelatedSearches 

func (h *Handler) SetRelatedSearches(rs *search.RelatedSearches)

SetRelatedSearches sets the related searches provider for the API handler

func (*Handler) SetWidgetManager 

func (h *Handler) SetWidgetManager(wm *widget.Manager)

SetWidgetManager sets the widget manager for the API handler

type HealthResponse 

type HealthResponse struct {
	// 1. Project identification (PART 16: branding config)
	Project ProjectInfo `json:"project"`

	// 2. Overall status
	Status         string   `json:"status"`                    // "healthy", "unhealthy", "degraded"
	PendingRestart bool     `json:"pending_restart,omitempty"` // true if restart needed
	RestartReason  []string `json:"restart_reason,omitempty"`  // settings that changed

	// 3. Version & build info (PART 7: binary requirements)
	Version   string    `json:"version"`    // SemVer "1.0.0"
	GoVersion string    `json:"go_version"` // "go1.23.0"
	Build     BuildInfo `json:"build"`

	// 4. Runtime info (PART 6: application modes)
	Uptime    string `json:"uptime"`    // human readable "2d 5h 30m"
	Mode      string `json:"mode"`      // "production" or "development"
	Timestamp string `json:"timestamp"` // current UTC time ISO 8601

	// 5. Cluster info (PART 10: database & cluster)
	Cluster ClusterInfo `json:"cluster"`

	// 6. Features - PUBLIC only (PARTS 20, 32, 34, 35)
	Features FeaturesInfo `json:"features"`

	// 7. Component health checks (per spec line 16298-16308)
	Checks ChecksInfo `json:"checks"`

	// 8. Statistics (public-safe aggregates)
	Stats StatsInfo `json:"stats"`
}

HealthResponse represents health check response per AI.md PART 13 All fields use canonical order from spec (line 16208-16244)

type InfoResponse 

type InfoResponse struct {
	Name        string          `json:"name"`
	Version     string          `json:"version"`
	Description string          `json:"description"`
	Uptime      string          `json:"uptime"`
	Mode        string          `json:"mode"`
	Engines     EnginesSummary  `json:"engines"`
	System      SystemInfo      `json:"system"`
	Features    map[string]bool `json:"features"`
}

InfoResponse represents server info response

type InstantAnswerResponse 

type InstantAnswerResponse struct {
	Query   string                 `json:"query"`
	Type    string                 `json:"type,omitempty"`
	Title   string                 `json:"title,omitempty"`
	Content string                 `json:"content,omitempty"`
	Data    map[string]interface{} `json:"data,omitempty"`
	Source  string                 `json:"source,omitempty"`
	Found   bool                   `json:"found"`
}

InstantAnswerResponse represents instant answer API response

type LoginRequest 

type LoginRequest struct {
	Username   string `json:"username"`
	Password   string `json:"password"`
	RememberMe bool   `json:"remember_me"`
	TOTPCode   string `json:"totp_code,omitempty"`
}

LoginRequest represents a login request

type LoginResponse 

type LoginResponse struct {
	User        UserResponse `json:"user"`
	SessionID   string       `json:"session_id,omitempty"`
	ExpiresAt   time.Time    `json:"expires_at"`
	Requires2FA bool         `json:"requires_2fa,omitempty"`
}

LoginResponse represents a successful login response

type NodeInfo 

type NodeInfo struct {
	ID       string `json:"id"`
	Hostname string `json:"hostname"`
}

NodeInfo represents node information for cluster mode

type PageSection 

type PageSection struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Content string `json:"content"`
}

PageSection represents a section of a server info page

type Pagination 

type Pagination struct {
	Page  int `json:"page"`
	Limit int `json:"limit"`
	Total int `json:"total"`
	Pages int `json:"pages"`
}

Pagination represents standard pagination info per AI.md PART 14

type ProjectInfo 

type ProjectInfo struct {
	Name        string `json:"name"`        // branding.app_name
	Tagline     string `json:"tagline"`     // branding.tagline (short slogan)
	Description string `json:"description"` // server.description (longer)
}

ProjectInfo represents project identification per AI.md PART 13

type RecoveryKeyRequest 

type RecoveryKeyRequest struct {
	Username    string `json:"username"`
	RecoveryKey string `json:"recovery_key"`
}

RecoveryKeyRequest represents a recovery key login request

type RegisterRequest 

type RegisterRequest struct {
	Username string `json:"username"`
	Email    string `json:"email"`
	Password string `json:"password"`
}

RegisterRequest represents a registration request

type RelatedSearchResponse 

type RelatedSearchResponse struct {
	Query       string   `json:"query"`
	Suggestions []string `json:"suggestions"`
	Count       int      `json:"count"`
}

RelatedSearchResponse represents related searches API response

type ResetPasswordRequest 

type ResetPasswordRequest struct {
	Token       string `json:"token"`
	NewPassword string `json:"new_password"`
}

ResetPasswordRequest represents a password reset completion request

type SearchRequest 

type SearchRequest struct {
	Query      string   `json:"query"`
	Category   string   `json:"category"`
	Page       int      `json:"page"`
	Limit      int      `json:"limit"`
	Engines    []string `json:"engines,omitempty"`
	SafeSearch string   `json:"safe_search,omitempty"`
	TimeRange  string   `json:"time_range,omitempty"`
	Language   string   `json:"language,omitempty"`
}

SearchRequest represents a search API request

type SearchResponse 

type SearchResponse struct {
	Query      string         `json:"query"`
	Category   string         `json:"category"`
	Results    []SearchResult `json:"results"`
	Pagination Pagination     `json:"pagination"`
	SearchTime float64        `json:"search_time_ms"`
	Engines    []string       `json:"engines_used"`
}

SearchResponse represents search API response per AI.md PART 14 pagination format

type SearchResult 

type SearchResult struct {
	Title       string  `json:"title"`
	URL         string  `json:"url"`
	Description string  `json:"description"`
	Engine      string  `json:"engine"`
	Score       float64 `json:"score"`
	Category    string  `json:"category"`
	Thumbnail   string  `json:"thumbnail,omitempty"`
	Date        string  `json:"date,omitempty"`
	Domain      string  `json:"domain,omitempty"`
}

SearchResult represents a single search result

type ServerPageResponse 

type ServerPageResponse struct {
	Title       string            `json:"title"`
	Description string            `json:"description,omitempty"`
	Content     string            `json:"content,omitempty"`
	Sections    []PageSection     `json:"sections,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

ServerPageResponse represents server info page API response Per AI.md PART 16: Server info pages return structured JSON

type SessionInfo 

type SessionInfo struct {
	ID         int64     `json:"id"`
	DeviceName string    `json:"device_name"`
	IPAddress  string    `json:"ip_address"`
	CreatedAt  time.Time `json:"created_at"`
	LastUsed   time.Time `json:"last_used"`
	ExpiresAt  time.Time `json:"expires_at"`
	IsCurrent  bool      `json:"is_current"`
}

SessionInfo represents session information for API

type Setup2FARequest 

type Setup2FARequest struct {
	Password string `json:"password"`
}

Setup2FARequest represents a 2FA setup request

type StatsInfo 

type StatsInfo struct {
	RequestsTotal int64 `json:"requests_total"`     // Total HTTP requests (lifetime)
	Requests24h   int64 `json:"requests_24h"`       // Requests in last 24 hours
	ActiveConns   int   `json:"active_connections"` // Current active connections
}

StatsInfo represents health statistics per AI.md PART 13 (line 16310-16317)

type SwaggerUIData 

type SwaggerUIData struct {
	SpecURL string
}

SwaggerUIData holds template data for Swagger UI

type SystemInfo 

type SystemInfo struct {
	GoVersion    string `json:"go_version"`
	NumCPU       int    `json:"num_cpu"`
	NumGoroutine int    `json:"num_goroutine"`
	MemAlloc     string `json:"mem_alloc"`
}

SystemInfo provides system information

type TorInfo 

type TorInfo struct {
	Enabled  bool   `json:"enabled"`  // Tor binary found and config enabled
	Running  bool   `json:"running"`  // Hidden service active
	Status   string `json:"status"`   // "healthy", "starting", "error"
	Hostname string `json:"hostname"` // "abc123...xyz.onion" (56 chars, v3)
}

TorInfo represents Tor status per AI.md PART 13 (line 16290-16296)

type TwoFactorVerifyRequest 

type TwoFactorVerifyRequest struct {
	Code      string `json:"code"`
	SessionID string `json:"session_id"`
}

TwoFactorVerifyRequest represents a 2FA verification request

type UpdateProfileRequest 

type UpdateProfileRequest struct {
	DisplayName       string `json:"display_name"`
	Bio               string `json:"bio"`
	AvatarURL         string `json:"avatar_url"`
	NotificationEmail string `json:"notification_email,omitempty"`
}

UpdateProfileRequest represents a profile update request

type UserHandler 

type UserHandler struct {
	// contains filtered or unexported fields
}

UserHandler handles user API requests

func NewUserHandler 

func NewUserHandler(cfg *config.Config, db *sql.DB, authManager *userpkg.AuthManager, totpManager *userpkg.TOTPManager, recoveryManager *userpkg.RecoveryManager, tokenManager *userpkg.TokenManager) *UserHandler

NewUserHandler creates a new user API handler

func (*UserHandler) RegisterRoutes 

func (h *UserHandler) RegisterRoutes(mux *http.ServeMux)

RegisterRoutes registers user API routes Per AI.md PART 14: All resource names MUST be plural

type UserResponse 

type UserResponse struct {
	ID            int64      `json:"id"`
	Username      string     `json:"username"`
	Email         string     `json:"email"`
	DisplayName   string     `json:"display_name,omitempty"`
	AvatarURL     string     `json:"avatar_url,omitempty"`
	Role          string     `json:"role"`
	EmailVerified bool       `json:"email_verified"`
	CreatedAt     time.Time  `json:"created_at"`
	LastLogin     *time.Time `json:"last_login,omitempty"`
}

UserResponse represents user data in API responses

type VerifyEmailRequest 

type VerifyEmailRequest struct {
	Token string `json:"token"`
}

VerifyEmailRequest represents an email verification request

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.