Getting Started

export ZIPF_API_KEY="wvr_your_token_here"

curl https://api.zipf.ai/v1 \
  -H "Authorization: Bearer $ZIPF_API_KEY"

# Run a search
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 2026",
    "max_results": 10
  }'

# List your searches
curl https://api.zipf.ai/v1/searches \
  -H "Authorization: Bearer $ZIPF_API_KEY"

# Get a specific search with full results
curl https://api.zipf.ai/v1/searches/{search_id} \
  -H "Authorization: Bearer $ZIPF_API_KEY"

curl -X POST https://api.zipf.ai/v1/searches \
  -H "Authorization: Bearer $ZIPF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best practices for fine-tuning LLMs in 2026",
    "max_results": 20,
    "interpret_query": true,
    "rerank_results": true,
    "generate_suggestions": true
  }'

curl -X POST https://api.zipf.ai/v1/asks \
  -H "Authorization: Bearer $ZIPF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Who is the CEO of NVIDIA?",
    "depth": "quick"
  }'

# Create a comprehensive search with query decomposition
curl -X POST https://api.zipf.ai/v1/searches \
  -H "Authorization: Bearer $ZIPF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "comprehensive analysis of quantum computing progress in 2026",
    "query_decomposition": true,
    "max_sub_queries": 5
  }'

# List your searches (includes comprehensive searches)
curl https://api.zipf.ai/v1/searches \
  -H "Authorization: Bearer $ZIPF_API_KEY"

# Get search with decomposition and results
curl https://api.zipf.ai/v1/searches/{search_id} \
  -H "Authorization: Bearer $ZIPF_API_KEY"

# Sync crawl - returns full results in one request (no polling!)
curl -X POST https://api.zipf.ai/v1/crawls \
  -H "Authorization: Bearer $ZIPF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://www.zipf.ai/about"],
    "max_pages": 1,
    "processing_mode": "sync",
    "extraction_schema": {
      "founder": "Extract the name of the founder or CEO",
      "angels": "Extract the names of angel investors or advisors",
      "company_description": "Extract the company description or mission"
    }
  }'

# Create session
curl -X POST https://api.zipf.ai/v1/sessions \
  -H "Authorization: Bearer $ZIPF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Safety Research Project 2026",
    "session_config": { "auto_deduplicate": true }
  }'

# List all your sessions
curl https://api.zipf.ai/v1/sessions \
  -H "Authorization: Bearer $ZIPF_API_KEY"

# Get session details
curl https://api.zipf.ai/v1/sessions/{session_id} \
  -H "Authorization: Bearer $ZIPF_API_KEY"

# Run search in session (filter_seen_urls removes duplicates)
curl -X POST https://api.zipf.ai/v1/sessions/{session_id}/search \
  -H "Authorization: Bearer $ZIPF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI alignment techniques 2026",
    "max_results": 20,
    "filter_seen_urls": true
  }'

# Get session timeline (all operations)
curl https://api.zipf.ai/v1/sessions/{session_id}/timeline \
  -H "Authorization: Bearer $ZIPF_API_KEY"

Base URL:  https://api.zipf.ai/v1
Header:    Authorization: Bearer $ZIPF_API_KEY

import requests
import os

API_KEY = os.environ["ZIPF_API_KEY"]
BASE_URL = "https://api.zipf.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Basic search
response = requests.post(
    f"{BASE_URL}/searches",
    headers=headers,
    json={
        "query": "AI infrastructure startups 2026",
        "max_results": 10
    }
)

results = response.json()
print(f"Found {results['results']['total_found']} results")

for url in results['results']['urls'][:5]:
    print(f"  - {url['title']}: {url['url']}")

# Sync crawl - get results in one request
crawl = requests.post(
    f"{BASE_URL}/crawls",
    headers=headers,
    json={
        "urls": ["https://example.com"],
        "max_pages": 3,
        "processing_mode": "sync"  # No polling needed!
    }
).json()

print(f"Crawled {crawl['stats']['pages_crawled']} pages")

const API_KEY = process.env.ZIPF_API_KEY;
const BASE_URL = "https://api.zipf.ai/v1";

async function search(query: string) {
  const response = await fetch(`${BASE_URL}/searches`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ query, max_results: 10 })
  });
  return response.json();
}

async function crawl(urls: string[]) {
  const response = await fetch(`${BASE_URL}/crawls`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      urls,
      max_pages: 5,
      processing_mode: "sync"  // Returns full results, no polling!
    })
  });
  return response.json();
}

// Usage
const results = await search("AI infrastructure startups 2026");
console.log(`Found ${results.results.total_found} results`);

const crawlResults = await crawl(["https://example.com"]);
console.log(`Crawled ${crawlResults.stats.pages_crawled} pages`);