# Gyrence

> Web data infrastructure API for AI agents. Five primitives — Search, Fetch, Gyre, Extract, Map — over a single JSON+Bearer interface. Every response uses the same `{ ok, data | error, code }` envelope.

## Getting Started

- [Quickstart](https://www.gyrence.com/docs/quickstart.md): Make your first Gyrence API call in five minutes: create a workspace, generate an API key, and run a /fetch request.
- [Authentication](https://www.gyrence.com/docs/authentication.md): How to authenticate Gyrence API requests: bearer tokens, the mc_ key prefix, verifying keys with /health, and handling secrets safely.
- [Errors](https://www.gyrence.com/docs/errors.md): The Gyrence error envelope, full code reference, billing rules, and how to branch retryable vs. permanent failures.
- [Rate limits](https://www.gyrence.com/docs/rate-limits.md): Per-workspace rate limits, the 25-second hard deadline, exponential backoff with jitter, and idempotency guarantees.

## Concepts

- [Workspaces](https://www.gyrence.com/docs/concepts/workspaces.md): Workspaces are the unit of ownership in Gyrence: API keys, credits, usage events, and members all belong to one workspace.
- [API keys](https://www.gyrence.com/docs/concepts/api-keys.md): How Gyrence API keys work: anatomy, minting, rotation, revocation, and the one-key-per-use pattern.
- [Credits](https://www.gyrence.com/docs/concepts/credits.md): Gyrence's credit schedule: per-endpoint costs, HTTP vs. browser tier, what's never charged, and how to estimate spend.
- [Gyring](https://www.gyrence.com/docs/concepts/gyring.md): Gyring is Gyrence's multi-page traversal primitive: walk a site from a seed URL, capture markdown per page, within a budget.
- [MCP integration](https://www.gyrence.com/docs/concepts/mcp.md): How Gyrence exposes its primitives over the Model Context Protocol: hosted endpoint, per-request server model, billing parity with HTTP, and client configuration.

## API Reference

- [Search](https://www.gyrence.com/docs/api/search.md): POST /api/v1/search — web search via Brave with optional inline fetch of each result as markdown. Recency control and per-result credit attribution.
- [Fetch](https://www.gyrence.com/docs/api/fetch.md): POST /api/v1/fetch — retrieve a single URL as cleaned markdown plus links. Automatic browser-tier escalation on bot blocks.
- [Gyre](https://www.gyrence.com/docs/api/gyre.md): POST /api/v1/gyre — walk a site within a page budget, returning markdown for every page visited. Same-domain by default.
- [Extract](https://www.gyrence.com/docs/api/extract.md): POST /api/v1/extract — pull structured JSON from a page using google/gemini-2.5-flash. 5 credits, 7 with browser.
- [Map](https://www.gyrence.com/docs/api/map.md): POST /api/v1/map — enumerate URLs for a site via sitemap, with depth-1 homepage fallback.
- [Health](https://www.gyrence.com/docs/api/health.md): GET /api/v1/health — authenticated liveness probe. Returns workspace ID and plan. Free to call.
- [MCP](https://www.gyrence.com/docs/api/mcp.md): POST /api/mcp — JSON-RPC Model Context Protocol endpoint exposing all five Gyrence primitives as MCP tools. Bearer auth, identical billing path to HTTP.

## Optional

- [llms-full.txt](https://www.gyrence.com/llms-full.txt): Every docs page concatenated into a single plaintext file.
- [OpenAPI spec](https://www.gyrence.com/openapi.json): Machine-readable OpenAPI 3.1 description of /api/v1/*.