# Zipf AI — API Documentation (Scoped Context)
# https://zipf.ai/docs/llms.txt
# For complete context: https://zipf.ai/llms.txt

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

## API Overview

Base URL: `https://api.zipf.ai/v1`
Auth: `Authorization: Bearer $ZIPF_API_KEY`
Format: JSON request/response

## Endpoints

### Search
- `POST /v1/searches` — Web search (1-2 credits). Supports query decomposition, reranking, metadata extraction.
- `GET /v1/searches/{id}` — Get search results and status.
- `DELETE /v1/searches/{id}` — Delete a search job.
- `POST /v1/searches/{id}/abort` — Cancel a running search.
- `POST /v1/searches/{id}/share` — Toggle sharing for a search job.

### Crawl
- `POST /v1/crawls` — Create crawl job (1-2 credits/page). Supports structured extraction, intent-driven crawling, Smart Crawl.
- `GET /v1/crawls/{id}` — Get crawl results with extracted data.
- `DELETE /v1/crawls/{id}` — Cancel a crawl.
- `POST /v1/crawls/{id}/abort` — Abort a running crawl.

### Sessions
- `POST /v1/sessions` — Create research session with URL deduplication.
- `POST /v1/sessions/{id}/search` — Search within session (deduplicates URLs).
- `POST /v1/sessions/{id}/crawl` — Crawl within session.
- `GET /v1/sessions/{id}/timeline` — Chronological operation timeline.
- `POST /v1/sessions/{id}/complete` — Mark session completed.

### Workflows (Monitors)
- `POST /v1/workflows` — Create scheduled monitoring workflow.
- `POST /v1/workflows/assess-intent` — Assess intent specificity (FREE).
- `POST /v1/workflows/plan` — Preview AI-planned workflow.
- `POST /v1/workflows/{id}/execute` — Execute patrol immediately.
- `GET /v1/workflows/{id}` — Get workflow details and recent executions.

### Ask
- `POST /v1/asks` — Get direct answers (2-5 credits). Modes: quick, standard, deep.

### Tokens
- `GET /v1/tokens` — List API tokens.
- `POST /v1/tokens` — Create new token with optional permission scoping.
- `DELETE /v1/tokens/{id}` — Revoke a token.

## Credit Costs

| Operation | Basic | Advanced |
|-----------|-------|----------|
| Search | 1 | 2 |
| Crawl (per page) | 1 | 2 |
| Ask | 2-5 | - |
| Workflow execution | 1 | 2 |

## Error Codes

| Code | Status | Description |
|------|--------|-------------|
| `AUTH_MISSING_TOKEN` | 401 | No Bearer token |
| `AUTH_INVALID_TOKEN` | 401 | Invalid token |
| `CREDITS_INSUFFICIENT` | 402 | Not enough credits |
| `RATE_LIMIT_HOURLY_EXCEEDED` | 429 | Rate limited |
| `VALIDATION_FAILED` | 400 | Bad parameters |

## Full Documentation

- OpenAPI spec: https://zipf.ai/openapi.json
- Complete LLM reference: https://zipf.ai/llms-full.txt
- Human-readable docs: https://zipf.ai/docs