Search API

Web search with optional AI-powered enhancements for query interpretation, reranking, and follow-up suggestions. Search powers agent patrols and on-demand queries alike.

Credits: 1 (basic) | 2 (advanced with AI features)

POST /v1/searches

Create a new search job.

Parameter	Type	Default	Description
`query`	String	required	Search query (max 1000 chars)
`max_results`	Int	10	Results to return (1-20)
`interpret_query`	Bool	false	AI query rewriting (~3-4s, triggers advanced)
`extract_metadata`	Bool	false	Deep content classification (async, triggers advanced)
`rerank_results`	Bool	false	Semantic reranking (triggers advanced)
`generate_suggestions`	Bool	false	"People Also Ask" queries (triggers advanced)
`generate_summary`	Bool	false	AI summary of results (FREE, async)
`query_decomposition`	Bool	false	Comprehensive search via sub-queries
`max_sub_queries`	Int	5	Sub-queries when decomposition enabled (1-20)
`max_results_per_sub_query`	Int	10	Results per sub-query (1-50)
`source_type`	String	mixed	`academic`, `commercial`, `news`, `community`, `mixed`
`processing_mode`	String	async	`sync` or `async`
`session_id`	UUID	-	Link to existing session
`dry_run`	Bool	false	Estimate cost without executing

Response: search_id, status, results[], count, credits, optional query_interpretation, suggested_queries, decomposition

Two-Stage Query Enhancement

Stage 1: Query Rewriting (Synchronous)

interpret_query: true - Rewrites query with better terms, executes variations in parallel, merges/dedupes results. ~3-4s latency.

Stage 2: Metadata Extraction (Async)

extract_metadata: true - Classifies document/content types (17+25 taxonomies), suggests recency/authority/diversity settings, extracts entities/keywords. Poll GET /v1/searches/{search_id} for metadata_status: completed.

Query Decomposition Mode

Comprehensive research via AI-powered query decomposition. Agents use this to patrol broadly:

Claude decomposes query into targeted sub-queries
All sub-queries execute in parallel
Results deduplicated and aggregated
Optional reranking for diversity

Credits: 1 + (cost_per_query x num_sub_queries)

Strategies: facet-exploration, temporal-layering, source-based, depth-based, hybrid, hierarchical-entity

Compositional Queries: For queries like "Find PhD students from CMU with NeurIPS publications", the system detects hierarchical relationships and uses staged execution with entity extraction.

GET /v1/searches

List search jobs with pagination.

Query Parameters:

limit (Int) - Results per page (1-100)
offset (Int) - Pagination offset
status (String) - Filter by status

GET /v1/searches/{search_id}

Get detailed search job status, results, summary, and suggestions.

Response includes: access_level (owner, org_viewer, public) indicating your access permissions.

DELETE /v1/searches/{search_id}

Delete a search job. Job must not be running.

POST /v1/searches/{search_id}/abort

Cancel a running search job and release reserved credits.

POST /v1/searches/{search_id}/share

Toggle public or organization sharing for a search job.

Body: {"public_share": true/false} or {"shared_with_org": true, "organization_id": "..."}

Note: Search jobs within sessions inherit org sharing from their parent session.

POST /v1/searches/estimate

Estimate the cost of a search without executing it.

Parameters: Same as POST /v1/searches.

Response: cost_estimate, would_succeed, credits_balance

GET /v1/public/searches/{search_id}

Access a publicly shared search job (no authentication required).

POST /v1/sessions/{session_id}/search

Search within a session context. Same parameters as POST /v1/searches plus:

filter_seen_urls (Bool, default: false) - Exclude URLs already in session

See Sessions API for details.

Example

# Basic search (1 credit)
curl -X POST https://api.zipf.ai/v1/searches \
  -H "Authorization: Bearer $ZIPF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI infrastructure startups", "max_results": 20}'

Taxonomies

Document types (17): news_editorial, academic_research, code_software, social_forum, etc.
Content types (25): academic_writing, news_article, tutorial, qa_forum, etc.
Recency: any, day, week, month, year, recent
Authority: any, low, medium, high, mixed
Diversity: low, medium, high