# Zipf AI — Developer Integration Guide (Scoped Context)
# https://zipf.ai/developers/llms.txt
# For complete context: https://zipf.ai/llms.txt

> This is a scoped llms.txt for developers integrating with Zipf AI.
> For the full product reference, see [https://zipf.ai/llms.txt](https://zipf.ai/llms.txt).

## Quick Start

1. Sign up at https://zipf.ai/pricing (Free: 100 credits/month)
2. Create an API token at https://zipf.ai/dashboard/tokens
3. Make your first API call:

```bash
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": 10}'
```

## Authentication

- **REST API**: Bearer token in `Authorization` header. Tokens prefixed `wvr_`.
- **MCP Server**: OAuth 2.0 via agent platform (Claude Desktop, Cursor, Windsurf).
- Create tokens: `POST /v1/tokens` or https://zipf.ai/dashboard/tokens
- Scope tokens: `["search", "crawl", "workflow", "sessions"]`
- Rotate every 90 days. Different tokens per environment.

## MCP Integration

```bash
# Add Zipf AI MCP server to Claude Desktop / Cursor
npx @anthropic-ai/claude-code mcp add zipf-ai https://api.zipf.ai/mcp
```

Server URL: https://api.zipf.ai/mcp
Transport: Streamable HTTP
Tools: monitors_create, monitors_list, monitors_get, monitors_update, monitors_delete, monitors_list_reports, monitors_chronicle, monitors_share, monitors_digest, monitors_expansion_recommendations, credits_balance, user_me, brand_design_system

## SDKs

- **TypeScript/JavaScript**: `npm install @zipf-ai/sdk`
- **Python**: Coming soon
- **OpenAPI spec**: https://zipf.ai/openapi.json (generate clients with openapi-generator)

## Common Patterns

### Search + Crawl + Extract
```
POST /v1/searches → get URLs → POST /v1/crawls with extraction_schema
```

### Session-based Research
```
POST /v1/sessions → POST /sessions/{id}/search → POST /sessions/{id}/crawl
```

### Scheduled Monitoring
```
POST /v1/workflows with interval + stop_condition
```

## Rate Limits

| Plan | Hourly | Daily |
|------|--------|-------|
| Free | 100 | 1,000 |
| Developer | 2,500 | 25,000 |
| Pro | 10,000 | 100,000 |

Watch headers: `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` (on 429).

## Resources

- API docs: https://zipf.ai/docs
- OpenAPI spec: https://zipf.ai/openapi.json
- Agent guide: https://zipf.ai/agents.md
- Pricing: https://zipf.ai/pricing.md
- MCP discovery: https://zipf.ai/.well-known/mcp.json
- Support: support@zipf.ai