Search API

Web search with optional AI-powered enhancements for query interpretation, reranking, and follow-up suggestions.

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

GET /api/v1/search

Returns API capabilities, available parameters, and current user stats.

POST /api/v1/search

Create a new search job.

Response: search_job_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 /api/v1/search/jobs/{id} for metadata_status: completed.

Query Decomposition Mode

Comprehensive research via AI-powered query decomposition:

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

Credits: 1 + (cost_per_query × 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 /api/v1/search/jobs

List search jobs with pagination.

Query Parameters:

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

GET /api/v1/search/jobs/{id}

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

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

DELETE /api/v1/search/jobs/{id}

Delete a search job. Job must not be running.

GET /api/v1/search/jobs/{id}/abort

Check if a search job can be aborted.

POST /api/v1/search/jobs/{id}/abort

Cancel a running search job and release reserved credits.

POST /api/v1/search/jobs/{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 /api/v1/search/jobs/{id}/score

Submit relevance feedback to score search results.

POST /api/v1/search/jobs/{id}/crawl-all

Create crawl jobs for all result URLs from this search.

GET /api/v1/search/jobs/{id}/crawls

Get all crawl jobs created from this search job's URLs.

POST /api/v1/search/execute

Execute a search with specified configuration. Alternative to creating a job.

GET /api/v1/search/stream

Get information about the search streaming endpoint.

POST /api/v1/search/stream

Stream decomposition search via SSE. Same parameters as POST /api/v1/search.

Events: started, decomposition_complete, sub_query_started, sub_query_complete, sub_query_error, aggregating, complete, error

curl -N -X POST https://www.zipf.ai/api/v1/search/stream \
  -H "Authorization: Bearer wvr_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI safety research", "max_sub_queries": 5}'

GET /api/v1/public/search/{id}

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

POST /api/v1/sessions/{id}/search

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

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

See Sessions API for details.

Examples

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

# Advanced search with AI features (2 credits)
curl -X POST https://www.zipf.ai/api/v1/search \
  -H "Authorization: Bearer wvr_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI infrastructure", "interpret_query": true, "rerank_results": true, "generate_summary": true}'

# Query decomposition (1 + 5 credits = 6 credits basic)
curl -X POST https://www.zipf.ai/api/v1/search \
  -H "Authorization: Bearer wvr_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "comprehensive AI safety research", "query_decomposition": true, "max_sub_queries": 5, "source_type": "academic"}'

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

See Also

• Sessions API | Common Topics