Back to FastBrew

FastBrew developer documentation

Build package-discovery tools and Mac setup workflows using FastBrew's public HTTP API. The API requires no account or API key. Catalog requests are read-only, and the Brewfile utilities return text and package data without installing software or changing your computer.

Start with the examples below, download the OpenAPI 3.1 specification, or use the FastBrew CLI. Agents can read llms.txt for tool-selection guidance. The canonical API origin is https://fastbrew.app.

Quickstart

Search the live catalog for Firefox casks. Use the returned package ID to retrieve details or build a selection.

curl --fail-with-body 'https://fastbrew.app/api/apps?search=firefox&type=cask' -H 'API-Version: 1'

Parse a Brewfile into package entries. This uploads the supplied text to FastBrew; remove secrets and private entries first.

curl --fail-with-body 'https://fastbrew.app/api/brewfile/parse' -H 'API-Version: 1' -H 'Content-Type: application/json' --data '{"content":"brew \"git\"\n"}'

API reference

  • GET /api/apps — search and filter formulas and casks. Supports search, type, category, popular, limit, page, and generation.
  • GET /api/apps/{type}/{slug} — retrieve one package and related packages.
  • GET /api/categories — list catalog categories.
  • GET /api/stats — retrieve catalog counts and statistics.
  • POST /api/brewfile/parse — submit a JSON object with a content string; inspect the returned errors and warnings before using the result.
  • POST /api/brewfile/generate — submit an apps array with each package's id and type to generate a Brewfile. At most 500 packages per request.
  • GET /api/health — retrieve public service health.

The OpenAPI specification defines the complete request and response schemas and operation IDs for function calling. For pagination, begin at page zero and pass its returned generation to later pages. An HTTP 410 means that generation has expired: restart from page zero without a generation. The maximum page size is 200.

Authentication and testing

These seven endpoints are public. No authentication setup or key provisioning is needed. You can test catalog reads and Brewfile transformations directly against the public API; there is no separate sandbox. Administrative, synchronization, and internal reporting endpoints are outside this public integration surface.

Versions and deprecation

Send API-Version: 1 explicitly. Requests without it also select version 1; unsupported versions return HTTP 400 with unsupported_api_version. A new major version is required for breaking changes. Version 1 is active and has no scheduled retirement.

FastBrew promises no minimum notice period before retiring a version. Monitor the Deprecation and Sunset response headers and the versioning and deprecation policy for migration instructions. These headers are absent for active versions.

Rate limits and retries

Catalog searches allow 30 requests per 60 seconds per client IP address. Brewfile parsing and generation each allow 10 requests per 60 seconds per client IP address. Limits apply within each Cloudflare location and are approximate. Browser catalog searches share the search allowance. Clients behind the same public IP share limits.

Catalog and Brewfile responses advertise RateLimit-Policy. Catalog reads advertise the search allowance in advance, but only requests with a search term consume it. Rejected requests return HTTP 429, Retry-After, and a RateLimit field indicating exhausted quota. Successful responses omit remaining quota because the limiter does not supply an accurate count. Wait at least the Retry-After interval, then retry with backoff. Caching can avoid some origin requests; the advertised limit is not a promise of capacity.

Errors are JSON objects containing error, code, and hint. Read the hint before retrying a 4xx response. Keep the X-Request-ID header when reporting a persistent failure to info@fastbrew.app.

When agents should use FastBrew

Use FastBrew to find a Homebrew package by purpose, distinguish formulas from casks, inspect current catalog details, or prepare a Mac setup list. Search first, confirm the exact IDs, then parse or generate a Brewfile. Ask the user to review installation commands before running them. For authoritative package licensing, security advisories, or build instructions, follow the upstream project and Homebrew documentation linked from the package.