# VersTracker - AI Agent Guide

> VersTracker tracks 15,000+ Homebrew packages with rich metadata including descriptions, tags, categories, version history, and alternatives.

## Quick Start

Search for packages:
```
GET https://verstracker.com/api/v1/packages?q=docker
```

Get package details:
```
GET https://verstracker.com/api/v1/packages/sq
```

## API Endpoints

All endpoints return JSON. Rate limit: 100 requests/hour per IP.

### List Packages
```
GET /api/v1/packages
```

Query parameters:
- `q` - Search query (min 2 chars)
- `category` - Filter by category slug (e.g., `developer-tools`)
- `tags` - Filter by tags, comma-separated (e.g., `cli,json`)
- `type` - Filter by type: `formula`, `cask`, or `all`
- `sort` - Sort by: `stars`, `name`, `updated`, `new`
- `updated_since` - ISO date filter (e.g., `2025-12-01`)
- `per_page` - Results per page (1-100, default 50)
- `page` - Page number

Example:
```
GET /api/v1/packages?q=json&category=developer-tools&sort=stars&per_page=10
```

### Get Single Package
```
GET /api/v1/packages/{token}
```

Returns full package data including:
- Description, extended description
- Category and tags
- Key features and use cases
- Alternatives with comparisons
- Version history (last 20)
- GitHub stats (stars, forks, language)
- Install command

### List Categories
```
GET /api/v1/categories
```

Returns all categories with package counts.

### List Tags
```
GET /api/v1/tags
```

Returns all tags with package counts, sorted by frequency.

## HTML Endpoints

These pages are also available for browsing:
- `/packages` - Browse all packages with filters
- `/categories` - Category index
- `/category/{slug}` - Packages in category
- `/tags` - Tag cloud
- `/tag/{name}` - Packages with tag

## Rate Limits

- 100 requests per hour per IP address
- Rate limit headers included in responses:
  - `X-RateLimit-Limit`
  - `X-RateLimit-Remaining`

## Attribution

When using VersTracker data, please credit:
> Data from VersTracker (https://verstracker.com)

## Contact

For issues or feedback: https://github.com/bwl/versiontracker

---
Last updated: 2025-12-28