API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/app/main.go
• internal/search/service.go
• internal/qdrant/client.go
• internal/embeddings/ollama.go
• internal/embeddings/openai.go
• setup-ollama.md

The MauQNotes application functions as a semantic search engine for personal notes. It does not expose its own API endpoints but rather consumes external APIs to perform its core tasks: generating vector embeddings from text and storing/querying these vectors in a vector database. This document details the external API endpoints consumed by the application, primarily those from an embedding provider (Ollama or OpenAI) and the Qdrant vector database.

The system is configured via environment variables, which determine which embedding provider to use and how to connect to the Qdrant instance. The main application logic orchestrates calls to these external services to first ingest notes and then perform semantic searches on them.

System Architecture

The application's architecture is centered around three main components: the MauQNotes application logic, an embedding service, and the Qdrant vector database. The data flow involves converting text to vectors via the embedding service and then using the Qdrant API to manage and search these vectors.

The following diagram illustrates the high-level interaction between these components.

This diagram shows the search.service module as the central orchestrator, which calls either the Ollama or OpenAI embedding module and the Qdrant client module to interact with their respective external APIs.

Sources: cmd/app/main.go, internal/search/service.go, internal/qdrant/client.go, internal/embeddings/ollama.go, internal/embeddings/openai.go

Configuration

The application's behavior, particularly which APIs it targets, is controlled by environment variables loaded via godotenv.

Variable	Description	Default Value	Source File
EMBEDDING_MODEL	Specifies the model to use for generating embeddings.	nomic-embed-text	internal/search/service.go:12
OLLAMA_URL	The base URL for the Ollama API service.	http://localhost:11434	internal/embeddings/ollama.go:25
OPENAI_API_KEY	The API key for authenticating with the OpenAI API.	(none)	internal/embeddings/openai.go:24
QDRANT_URL	The base URL for the Qdrant database instance.	(none)	internal/qdrant/client.go:82
QDRANT_API_KEY	The API key for authenticating with Qdrant.	(none)	internal/qdrant/client.go:83
QDRANT_COLLECTION	The name of the collection to use within Qdrant.	(none)	internal/qdrant/client.go:84

Sources: internal/search/service.go:10-14, internal/embeddings/ollama.go:23-31, internal/embeddings/openai.go:22-26, internal/qdrant/client.go:80-86

Embedding Generation APIs

To perform semantic search, text notes must be converted into numerical vectors (embeddings). The application supports two providers for this task: Ollama and OpenAI.

Ollama API

The application can connect to a local or remote Ollama instance to generate embeddings.

Endpoint: POST {OLLAMA_URL}/api/embeddings

The FromOllama function constructs and sends a request to this endpoint.

// internal/embeddings/ollama.go:16-20
type ollamaRequest struct {
	Model  string `json:"model"`
	Prompt string `json:"prompt"`
}

The response contains the generated vector.

// internal/embeddings/ollama.go:22-25
type ollamaResponse struct {
	Embedding []float64 `json:"embedding"`
	Error     string    `json:"error,omitempty"`
}

Sources: internal/embeddings/ollama.go:16-59

OpenAI API

Alternatively, the application can use the OpenAI API to generate embeddings.

Endpoint: POST https://api.openai.com/v1/embeddings

The FromOpenAI function handles the interaction with this endpoint, including authentication via a Bearer token.

// internal/embeddings/openai.go:13-16
type openAIRequest struct {
	Model string   `json:"model"`
	Input []string `json:"input"`
}

The response contains the embedding data.

// internal/embeddings/openai.go:18-24
type openAIResponse struct {
	Data []struct {
		Embedding []float64 `json:"embedding"`
	} `json:"data"`
	Error *struct {
		Message string `json:"message"`
	} `json:"error,omitempty"`
}

Sources: internal/embeddings/openai.go:13-54

Qdrant Vector DB API

The qdrant.client module provides a client for interacting with the Qdrant vector database's REST API. It handles collection creation, data upserting, and searching.

Sources: internal/qdrant/client.go

API Endpoints

The client interacts with the following Qdrant API endpoints:

Method	Endpoint	Description	Client Function
PUT	/collections/{collection_name}	Creates a new collection if it doesn't exist.	CreateCollectionIfNotExists
PUT	/collections/{collection_name}/points?wait=true	Upserts (creates or updates) points in a collection.	Upsert
POST	/collections/{collection_name}/points/search	Performs a vector similarity search.	Search

Sources: internal/qdrant/client.go:116, internal/qdrant/client.go:140, internal/qdrant/client.go:170

Data Structures

The following Go structs are used to model the JSON payloads for Qdrant API requests.

This diagram shows the main request data structures used for interacting with the Qdrant API.

Sources: internal/qdrant/client.go:20-27, internal/qdrant/client.go:29-31, internal/qdrant/client.go:34-41, internal/qdrant/client.go:14-19

Ingestion and Query Flows

The search service orchestrates the API calls for the two main application flows: ingesting notes and querying.

Ingestion Flow (IngestNotes)

This sequence diagram shows how a note is processed and stored in Qdrant.

Query Flow (Query)

This sequence diagram illustrates the process of performing a semantic search.