Library Search API

The Library Search API provides hybrid search over the Astrolock documentation archive and knowledge base. Content is indexed as embedded chunks for semantic similarity search, with a text fallback using trigram matching. The archive includes SGP4 theory documents, API references, source notes, and other technical material.

Search

Query the documentation library using semantic vector search, text matching, or a hybrid combination of both.

GET /api/library/search

Parameters

Parameter	Type	Default	Range / Values	Description
q	string	—	1 – 500 chars	Search query (required)
mode	string	hybrid	hybrid, semantic, text	Search strategy
content_type	string	—	page, source_note	Filter results by content type (optional)
section	string	—	max 200 chars	Section prefix filter (optional)
limit	integer	10	1 – 50	Maximum number of results

Response

{
  "query": "SGP4 propagation accuracy",
  "results": [
    {
      "title": "SGP4 Theory and Practice",
      "slug": "sgp4-theory-and-practice",
      "section": "reference/theory",
      "content_type": "source_note",
      "description": "Detailed treatment of the Simplified General Perturbations model",
      "snippet": "...the SGP4 propagation model achieves sub-kilometer accuracy for LEO objects within 2-3 days of the TLE epoch...",
      "url": null,
      "pdf_source": "spacetrack_report_3.pdf",
      "score": 0.8742,
      "source": "both"
    },
    {
      "title": "Satellite Tracking Overview",
      "slug": "satellite-tracking-overview",
      "section": "guides",
      "content_type": "page",
      "description": "How Astrolock tracks satellites in real time",
      "snippet": "...propagation uses the SGP4/SDP4 algorithm suite to predict satellite positions from two-line element sets...",
      "url": "/guides/satellite-tracking-overview",
      "pdf_source": null,
      "score": 0.7319,
      "source": "semantic"
    }
  ],
  "count": 2,
  "mode": "hybrid"
}

Result Fields

Field	Type	Description
title	string	Document title
slug	string	URL-safe identifier, unique across the library
section	string	Section path (e.g. reference/theory, guides)
content_type	string	page for documentation pages, source_note for archived reference material
description	string	null
snippet	string	Matched text chunk (up to 200 characters) with surrounding context
url	string	null
pdf_source	string	null
score	float	Relevance score, 0 – 1 (higher is better)
source	string	Which search method matched: semantic, text, or both

---

Search Modes

The mode parameter controls which search strategies are used.

Hybrid (default)

Runs both semantic and text search in parallel, then merges results. Documents found by both methods receive a score boost (+0.1, capped at 1.0) and are marked with source: "both". Results are deduplicated by slug and sorted by final score.

GET /api/library/search?q=orbital+mechanics&mode=hybrid

Semantic

Uses cosine distance against pgvector embeddings of document chunks. Each document is split into overlapping chunks at indexing time, and the query is embedded using the same model. Returns the closest matches by vector similarity.

GET /api/library/search?q=how+does+atmospheric+drag+affect+LEO+orbits&mode=semantic

Tip

Semantic mode works best for natural-language questions and conceptual queries. It finds relevant content even when the exact words do not appear in the document — for example, searching “orbit decay causes” can match content about “atmospheric drag at low altitudes.”

Text

Uses PostgreSQL ILIKE with GIN trigram indexes on the title and body columns. This is a straightforward substring match, useful when you know the exact terminology.

GET /api/library/search?q=Brouwer+mean+elements&mode=text

Tip

Text mode is deterministic and fast. Use it when searching for exact terms, variable names, equation labels, or specific document titles. If semantic search is unavailable (embedding service down), hybrid mode falls back to text automatically.

---

Filtering

By Content Type

Restrict results to documentation pages or archived source notes.

GET /api/library/search?q=TLE+format&content_type=page

GET /api/library/search?q=Hoots+Roehrich&content_type=source_note

Value	Description
page	Published documentation pages with site URLs
source_note	Archived reference material, often derived from PDF sources

By Section

Filter results to a specific section prefix. Matches any document whose section field starts with the given string.

GET /api/library/search?q=propagation&section=reference/theory

Note

The section parameter uses prefix matching, so section=reference matches both reference/theory and reference/api. Use the full path for precise filtering.

---

Score Interpretation

Score Range	Typical Meaning
0.85 – 1.0	Strong match — query closely aligns with document content
0.65 – 0.84	Good match — related content with partial overlap
0.40 – 0.64	Moderate match — tangentially related
< 0.40	Weak match — included to fill results up to the limit

Text-only matches receive a fixed score of 0.5. When a document appears in both semantic and text results, the semantic score is boosted by 0.1 (capped at 1.0) and the source is set to both.