Corpus Search API

Getting Started

Quick Start

Three examples to get you going — from fully automatic to fully manual.

Minimal — AI handles everything

POST /api/search

{
  "query": "tel aviv this week"
}

With timezone + LLM re-ranking

POST /api/search

{
  "query": "paris tonight",
  "timezone": "America/New_York",
  "rerank": true
}

Fully manual — no AI, fastest

POST /api/search

{
  "query": "earthquake",
  "expand": false,
  "extractMeta": false,
  "strategy": "embed_time",
  "timePreset": "last_30d",
  "topK": 50
}

Full Pipeline

Search

Runs the complete search flow in one call: AI extraction → expansion → embed → Pinecone query → post-filter → proximity re-rank → optional LLM re-rank.

POST /api/search Full search pipeline

All parameters except query are optional — AI fills in strategy, time, and location if extractMeta is enabled.

Request Body

Parameter	Type	Default	Description
query required	string		Natural language search text
expand	boolean	true	Claude enriches the query with 5–15 contextual keywords before embedding
extractMeta	boolean	true	Claude infers strategy, time preset, location, and media type from the query
timezone	string	"UTC"	IANA timezone for time preset resolution. If AI detects a location, that timezone overrides this.
strategy	string	AI decides	Search strategy — omit to let AI choose. See strategy table below.
timePreset	string	AI decides	Time window: today, tonight, yesterday, this_week, last_week, this_month, last_30d, last_90d, all
startMs	number		Explicit time range start (UTC ms). Overrides timePreset.
endMs	number		Explicit time range end (UTC ms). Overrides timePreset.
type	string		Media type filter: image, video, text, audio
lat	number	AI decides	Reference latitude for proximity re-ranking
lng	number	AI decides	Reference longitude
radiusKm	number	50	Proximity boost radius in km
weight	number	0.15	Proximity boost weight (0–1). Higher = location matters more.
country	string		Exact country metadata match (Pinecone pre-filter)
city	string		Exact city metadata match (Pinecone pre-filter)
topK	integer	100	Max results. Range: 1–10,000
filterMode	string	"pre"	"pre" = Pinecone-level filter (faster). "post" = server-side filter.
rerank	boolean	false	Enable LLM semantic re-ranking via Claude
rerankPool	integer	10	Candidates to feed into Claude for re-ranking
rerankReturn	integer	5	Results to return after LLM scoring. Must be ≤ rerankPool.

Strategy Values

Value	Behavior
`embed`	Pure vector similarity — no time or location filtering
`embed_time`	Vector + time window filter
`embed_time_meta`	Vector + time + city/country string match
`embed_time_coord`	Vector + time + coordinate-based proximity re-ranking

200 OK 400 Missing query 500 Server error

Response structure

{
  "matches": [...],       // Vector search results
  "count": 100,
  "reranked": [...],      // LLM-reranked (null if disabled)
  "extraction": {...},    // AI extraction (null if disabled)
  "expansion": {...},     // Query expansion info
  "params": {...},        // Actual parameters used
  "debug": {...},         // Diagnostic info
  "timing": {...}         // Pipeline step timings (ms)
}

AI

Metadata Extraction

POST /api/extract Claude extracts structured metadata

Uses Claude to extract strategy, time preset, location (with timezone), and media type from a natural language query.

Request Body

Parameter	Type	Description
query required	string	Natural language query
timezone	string	IANA timezone for context

Example response

{
  "strategy": "embed_time_coord",
  "timePreset": "yesterday",
  "type": null,
  "location": {
    "country": "Palestine",
    "city": "Gaza",
    "lat": 31.5, "lng": 34.47,
    "radiusKm": 50,
    "timezone": "Asia/Gaza"
  }
}

200 OK 400 Missing query

POST /api/expand Claude enriches queries with keywords

Adds 5–15 contextually relevant keywords to improve vector search recall. Original words kept at the start.

Request Body

Parameter	Type	Description
query required	string	Query to expand

Example response

{
  "expanded": "tel aviv this week Israel protests IDF military Mediterranean"
}

200 OK 400 Missing query

Search

Embedding & Query

POST /api/embed Generate 768-dim text embedding

Generates a 768-dimensional vector using Google Gemini gemini-embedding-001.

Request Body

Parameter	Type	Description
text required	string	Text to embed

200 OK 400 Missing text

POST /api/query Raw Pinecone vector query

Queries the Pinecone vector index directly with a vector and optional metadata filter.

Request Body

Parameter	Type	Description
vector required	number[]	768-dim embedding
host required	string	Pinecone host (from /api/resolve-host)
topK	integer	Max results (default 100)
filter	object	Pinecone metadata filter

200 OK 400 Missing vector/host

GET /api/resolve-host Get Pinecone index host URL

Returns the Pinecone index host URL. Required for /api/query.

Response

{ "host": "corpus-v1-abc1234.svc.us-east1-gcp.pinecone.io" }

200 OK

Geo

Geocoding

GET /api/geocode?q={place} Place name → coordinates

Looks up coordinates for a place name via OpenCage. Returns up to 5 results.

Query Parameters

Parameter	Type	Description
q required	string	Place name to geocode

Example

GET /api/geocode?q=Tel%20Aviv

200 OK 400 Missing q

Reference

Performance

Step	Duration	Notes
AI extraction	1–2s	Claude call. Parallel with expansion.
AI expansion	1–2s	Claude call. Parallel with extraction.
Embedding	200–400ms	Gemini API
Pinecone query	300–800ms	Depends on topK and filter
Firestore fetch	300–600ms	Only if rerank=true
LLM rerank	2–5s	Only if rerank=true

Total without rerank: ~2–4s. With rerank: ~5–9s. Set expand: false and extractMeta: false for ~1s latency.

Priority Order

When multiple sources provide the same parameter:

Parameters

Manual (request body) › AI extraction › Default

Time resolution

startMs/endMs › timePreset (manual) › timePreset (AI) › "all"

Timezone

AI-detected location tz › timezone (request) › "UTC"

Error Handling

Status	Cause
`400`	Missing required parameter
`405`	Wrong HTTP method
`500`	Internal error (Pinecone, Claude, Gemini, or Firestore)

AI steps fail gracefully — a failed extraction uses defaults, a failed expansion embeds the raw query, a failed rerank returns null. The search still returns results.

Coming Soon

Memories API

Persistent memory endpoints for storing and retrieving contextual information across sessions. These endpoints are planned and not yet available.

Planned User Memories

Store and retrieve per-user memory context — preferences, past queries, behavioral patterns. Enables personalized search results and AI responses that improve over time.

POST /api/memories/user · GET /api/memories/user/:id

Planned City Memories

Aggregate knowledge about specific cities — trending topics, recurring events, notable locations, local context. Powers location-aware search enrichment and city-specific AI behavior.

POST /api/memories/city · GET /api/memories/city/:name

Planned Location Memories

Fine-grained coordinate-based memories — what has happened at specific GPS coordinates over time. Enables hyper-local search context and spatial pattern recognition.

POST /api/memories/location · GET /api/memories/location?lat=&lng=&radius=

Planned Event Memories

Temporal event tracking — significant events detected across the corpus with time, location, and topic clustering. Supports event-aware search and timeline queries.

POST /api/memories/event · GET /api/memories/events?from=&to=