# Gyrence — full documentation > Concatenation of every page at https://www.gyrence.com/docs. Generated on request from the .mdx sources. --- # Quickstart Source: https://www.gyrence.com/docs/quickstart.md Make your first Gyrence API call in under five minutes. By the end of this page you'll have a workspace, an API key, and a working `/fetch` request returning clean markdown. ## 1. Create a workspace Sign in at [gyrence.com](/login). Your first workspace is created automatically — a workspace is the unit that owns API keys, usage, and billing. You can create more later (one per project, customer, or environment) from the [console](/app/dashboard). > **What** — A workspace isolates a set of API keys, request history, and credit balance. Most teams start with one and add more only when they need separate billing or hard usage walls between projects. See [Concepts → Workspaces](/docs/concepts/workspaces). ## 2. Generate an API key Open [API Keys](/app/api-keys) in the console and click **Create key**. Copy the value immediately — Gyrence shows it once, then stores only a hash. If you lose a key, revoke it and create a new one. Keys start with `mc_` and authenticate every request via the `Authorization: Bearer` header. ```bash ``` ## 3. Make your first request Fetch any public URL as clean markdown: ```bash curl -X POST https://www.gyrence.com/api/v1/fetch \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com"}' ``` Response: ```json { "ok": true, "data": { "url": "https://example.com/", "title": "Example Domain", "description": "", "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...", "html": "...", "links": ["https://www.iana.org/domains/example"], "statusCode": 200, "fetchedAt": "2026-05-29T18:42:00.000Z", "via": "http" } } ``` The `via` field tells you which tier handled the request: `"http"` (1 credit) or `"browser"` (3 credits). Gyrence picks automatically based on what the origin returns. ## Python ```python GYRENCE_API_KEY = "your_api_key" BASE = "https://www.gyrence.com/api/v1" def gyre(seed_url: str, max_pages: int = 20) -> list[dict]: """Walk a site and return markdown for every page visited.""" r = requests.post( f"{BASE}/gyre", headers={"Authorization": f"Bearer {GYRENCE_API_KEY}"}, json={"url": seed_url, "maxPages": max_pages, "sameDomain": True}, ) r.raise_for_status() return r.json()["data"]["pages"] pages = gyre("https://example.com") for page in pages: print(page["url"], "—", len(page["markdown"]), "chars") ``` No external dependencies beyond `requests`. Install with `pip install requests`. For agents that need structured extraction, combine with Extract: ```python def extract(url: str, prompt: str) -> dict: """Extract structured JSON from a URL using a natural-language prompt.""" r = requests.post( f"{BASE}/extract", headers={"Authorization": f"Bearer {GYRENCE_API_KEY}"}, json={"url": url, "prompt": prompt}, ) r.raise_for_status() return r.json()["data"]["json"] result = extract( "https://example.com/about", "Extract the company name, founding year, and headquarters city.", ) print(result) # {"company": "...", "founded": ..., "hq": "..."} ``` ## 4. Use it from JavaScript ```javascript const res = await fetch("https://www.gyrence.com/api/v1/fetch", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GYRENCE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://example.com" }), }); const { ok, data, error } = await res.json(); if (!ok) throw new Error(error); console.log(data.markdown); ``` Every Gyrence response uses the same envelope: `{ ok: true, data }` on success, `{ ok: false, error, code }` on failure. One shape of error handling covers every endpoint. ## Extract from audio or video For a timestamped transcript, add `transcript: true` to Fetch: ```bash curl -X POST https://www.gyrence.com/api/v1/fetch \ -H "Authorization: Bearer $GYRENCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","transcript":true}' ``` Use [Extract](/docs/api/extract) when you want structured facts or a summary instead of raw transcript segments. The console can also upload an audio/video file up to 95 MB. See the complete [Audio & video extraction guide](/docs/concepts/audio-video). ## What's next The other four primitives compose on top of `/fetch`: - **[Search](/docs/api/search)** — natural-language query → ranked URLs (optionally fetched in the same call) - **[Gyre](/docs/api/gyre)** — walk a site within a page budget, returning markdown for every page - **[Extract](/docs/api/extract)** — fetch a URL and use an LLM to pull structured fields - **[Map](/docs/api/map)** — enumerate every URL on a site via its sitemaps Want the same five primitives inside Claude Desktop, Cursor, or your own MCP-aware agent? Skip the HTTP wiring entirely: - **[MCP integration](/docs/concepts/mcp)** — point your MCP client at `https://www.gyrence.com/api/mcp` with the same `Authorization: Bearer mc_…` header. All five primitives appear as `gyrence_*` tools, billed identically to HTTP. Before going to production, read: - **[Authentication](/docs/authentication)** — header format, key scopes, rotation - **[Errors](/docs/errors)** — full error envelope and code reference - **[Rate limits](/docs/rate-limits)** — per-plan limits and backoff strategy - **[Credits](/docs/concepts/credits)** — exactly what each endpoint costs > **For coding agents** — Point your agent at [`/llms-full.txt`](/llms-full.txt) for a single-file plaintext copy of this entire documentation site, or [`/llms.txt`](/llms.txt) for just the index. --- # Authentication Source: https://www.gyrence.com/docs/authentication.md Every Gyrence API call is authenticated with a workspace **API key** sent as a bearer token. There is no OAuth, no session cookie, no signed-request scheme — one header, one secret, one workspace. ```bash Authorization: Bearer mc_VHJ5dGhpc2lzbm90YXJlYWxrZXk ``` The key tells Gyrence which [workspace](/docs/concepts/workspaces) the call belongs to, which credit pool to draw from, and which Usage and Activity logs to write. The caller's human identity is not part of the request. ## The header All endpoints under `/api/v1/*` expect the same header: ``` Authorization: Bearer ``` - The scheme is `Bearer` (case-sensitive in spirit, case-insensitive in practice). - The key must start with `mc_`. Anything else is rejected before hash lookup. - The header is the only place credentials are read. Query-string keys, request-body keys, and basic auth are not supported. A missing header, malformed key, or revoked key returns: ```json { "ok": false, "error": "invalid api key", "code": "unauthorized" } ``` with HTTP `401`. Failed auth is **never billed** — the request is rejected before any primitive runs. ## Getting a key Keys are minted in the console at **API keys**, scoped to the currently-selected workspace. 1. Pick the workspace from the switcher in the top-right of the console. 2. Open **API keys → New key**. 3. Give it a human name (`prod-backend`, `ci-runner`, `dev-laptop-alice`). 4. Copy the plaintext value from the one-time reveal — Gyrence stores only a SHA-256 hash, so the full value can never be recovered. See [Concepts → API keys](/docs/concepts/api-keys) for the full lifecycle (rotation, revocation, prefixes). ## Always call `www.gyrence.com` The canonical host is **`www.gyrence.com`**. The apex (`gyrence.com`) issues a 307 redirect to `www`, and most HTTP clients (curl, `fetch`, the majority of SDKs) **drop the `Authorization` header on cross-host redirects** — so calls to the apex will surface as `401 unauthorized`. Always hard-code `https://www.gyrence.com` in your client, SDK config, and webhook destinations. ## A canonical request ```bash curl https://www.gyrence.com/api/v1/fetch \ -H "Authorization: Bearer $GYRENCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com" }' ``` ```ts const res = await fetch("https://www.gyrence.com/api/v1/fetch", { method: "POST", headers: { Authorization: `Bearer ${process.env.GYRENCE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://example.com" }), }); const json = await res.json(); if (!json.ok) throw new Error(`${json.code}: ${json.error}`); ``` The same key authenticates the [MCP endpoint](/docs/concepts/mcp) at `POST https://www.gyrence.com/api/mcp` — header-only, never in the URL path. ## Verifying a key without spending credits `GET /api/v1/health` is authenticated, costs **0 credits**, and never returns `402`. Use it as a liveness probe and as a cheap way to confirm a key is valid before promoting it to production. ```bash curl https://www.gyrence.com/api/v1/health \ -H "Authorization: Bearer $GYRENCE_API_KEY" ``` ```json { "ok": true, "data": { "status": "ok" } } ``` ## Handling secrets Keys grant full API access to a workspace and draw down its credit balance — treat them like a database password. - **Server-side only.** Never ship a key to a browser, mobile app, or any client your users control. - **Environment variables or a secret manager.** Not source code, not config files committed to git. - **One key per deployed surface.** Separate keys for `prod`, `staging`, CI, and each developer's laptop make revocation surgical. - **Rotate after exposure.** A key in a log, screenshot, or shared terminal is compromised. Mint a new one, roll it out, revoke the old one. > **If a key leaks** — Revoke it immediately in the console. Revocation takes effect on the next request — there is no propagation delay. Then audit **Usage** filtered by the revoked key's prefix to see what was called before you caught it. ## What auth does **not** do - **Endpoint scoping.** Any valid key can call any `/api/v1/*` endpoint on its workspace today. Per-key scopes are on the roadmap. - **Cross-workspace access.** A key is bound to exactly one workspace and cannot be promoted, transferred, or pooled. Mint a new key on the target workspace instead. - **Console sign-in.** Keys don't authenticate humans into the dashboard — that's a separate account-level login. --- # Errors Source: https://www.gyrence.com/docs/errors.md Gyrence uses a single, predictable error envelope across every `/api/v1/*` endpoint. One shape of error handling covers the whole API surface. ## The envelope Every response — success or failure — is JSON with an `ok` boolean. **Success:** ```json { "ok": true, "data": { /* endpoint-specific payload */ } } ``` **Failure:** ```json { "ok": false, "error": "human-readable message", "code": "machine_code" } ``` - `ok` is the only field guaranteed on every response. Always branch on it first. - `error` is meant for humans — log it, surface it in dashboards. The wording is not stable across releases. - `code` is meant for machines — branch on it. Codes are stable within `/api/v1`; renames require `/api/v2`. ```ts const res = await fetch(url, opts); const json = await res.json(); if (!json.ok) { // Branch on json.code, not on res.status — they match, but code is the source of truth. throw new Error(`${json.code}: ${json.error}`); } return json.data; ``` ## Code reference | HTTP | `code` | What it means | Billed? | | --- | --- | --- | --- | | `200` | — | Success. `ok: true`, `data` populated. | yes (per the [credit schedule](/docs/concepts/credits)) | | `400` | `bad_request` | Malformed JSON, missing required field, or input failed schema validation. | no | | `401` | `unauthorized` | Missing, malformed, or revoked API key. | no | | `402` | `credits_exhausted` | Workspace has zero credits remaining. Top up or wait for plan renewal. Never returned for internal-plan workspaces. | no | | `403` | `forbidden_url` | Target URL is blocked by SSRF rules (private IPs, link-local, localhost, non-HTTP schemes). | no | | `404` | `not_found` | The origin returned 404 for the requested URL. The request itself succeeded — the page just isn't there. | no | | `408` | `timeout` | The 25-second hard deadline tripped before useful work completed. | no | | `429` | `rate_limited` | You exceeded the per-workspace request rate. Back off and retry. | no | | `502` | `upstream_error` | The origin returned a 5xx, or the headless-browser worker failed. Gyrence didn't get the content you asked for. | no | | `502` | `provider_quota_exceeded` | A Gyrence-side provider subscription (e.g. Brave Search) returned a billing/quota signal (HTTP 402). Platform-side condition — not caller fault, not a per-workspace credit issue. Do not retry; surface to status. `details.provider` names the upstream. | no | | `503` | `unavailable` | Gyrence itself is degraded — the platform is having a bad minute. Retry with backoff. | no | The rule is consistent: **if the response doesn't include the data you asked for, you weren't billed**. The one exception is `/gyre`, which has a 1-credit floor so even a zero-page success records as a metered call. ## Branching by category In practice, error handling collapses to four cases: ```ts const { ok, data, error, code } = await res.json(); if (ok) return data; switch (code) { case "unauthorized": case "forbidden_url": case "bad_request": // Caller error — do not retry. Fix the code or the input. throw new PermanentError(code, error); case "credits_exhausted": // Operational — alert a human, stop sending traffic on this workspace. throw new BillingError(error); case "rate_limited": case "timeout": case "upstream_error": case "unavailable": // Transient — retry with exponential backoff (see /docs/rate-limits). throw new RetryableError(code, error); case "provider_quota_exceeded": // Platform-side: a Gyrence upstream provider is out of quota. // Not your fault, not your credits. Don't retry — alert and wait. throw new PermanentError(code, error); case "not_found": // Logical — the URL doesn't exist. Often you want to record and move on. return null; default: throw new Error(`unknown code: ${code}`); } ``` ## Per-primitive notes Most error codes are universal. A few have endpoint-specific nuances: - **`/fetch`, `/extract`.** A `404` from the origin surfaces as `404 not_found`. A `403` from the origin (bot block) is escalated to the browser tier first; if the block persists, you get `502 upstream_error`, not `403`. - **`/gyre`.** Per-page failures are **not** top-level errors — they land in the response's `errors[]` array while the overall call returns `200`. A `200` gyre with zero successful pages still bills 1 credit (the floor). - **`/search`.** If `fetch: true` is set, individual result fetches that fail land in each result's `fetchError` field. The search call itself returns `200` as long as Brave returned results. - **`/map`.** A site with no discoverable sitemap returns `200` with an empty `urls[]`, not a `404`. Use the result, don't catch. ## Partial success vs. hard failure The pattern across the API is: - **Hard failure** (`ok: false`) means the request as a whole produced nothing usable. - **Partial success** (`ok: true` with errors *inside* `data`) means some sub-units failed but the overall call returned something. Gyre `errors[]`, search per-result `fetchError`, and extract field-level confidence are all in this category. Both are normal. Code defensively on the inside-data errors, but don't conflate them with envelope-level failures. ## Stability guarantees - HTTP status codes and `code` values are **frozen for `/api/v1`**. New codes may be added; existing codes will not be renamed or repurposed. - `error` message wording **is not stable** — it's tuned for human readability and may change without notice. Never branch on the string. - New endpoints may add endpoint-specific codes; the universal codes in the table above will continue to mean the same thing everywhere. ## MCP error shape Calls to the [`/api/mcp`](/docs/api/mcp) endpoint use the same code set, but wrapped in JSON-RPC instead of the HTTP envelope. Transport-level failures (bad auth, wrong method) come back as `{ jsonrpc, error: { code, message }, id }` with codes `-32001` (unauthorized) or `-32000` (method not allowed). Primitive failures (`credits_exhausted`, `upstream_error`, etc.) surface inside the `tools/call` result with `isError: true` and a `text` content payload of the form `": "` — same code, different envelope. See [MCP](/docs/api/mcp#errors) for examples. > **Status page** — Persistent `503 unavailable` or `502 upstream_error` across many requests usually means a platform-side incident. Check status before adding retry logic for what's actually an outage. --- # Rate limits Source: https://www.gyrence.com/docs/rate-limits.md Gyrence rate-limits per **workspace**, not per key or per IP. Every key on a workspace draws from the same bucket, the same way they draw from the same [credit pool](/docs/concepts/credits). The goals are: - Keep one workspace's traffic from degrading another's. - Surface runaway loops early (a misconfigured agent making thousands of calls per minute). - Stay out of the way of normal application traffic. ## The hard deadline Independent of any rate limit, **every request has a 25-second hard deadline**. If the work doesn't complete in 25 seconds — slow origin, stuck headless browser, a gyre fanning out further than expected — the request returns: ```json { "ok": false, "error": "request exceeded 25s deadline", "code": "timeout" } ``` with HTTP `408`. Timeouts are **not billed**. The deadline applies end-to-end across all tiers and retries Gyrence does internally. For gyres, the deadline is the most common reason a call returns fewer pages than `maxPages` — the budget was generous, but the clock ran out first. ## When you're rate-limited Exceeding the per-workspace rate returns: ```json { "ok": false, "error": "rate limit exceeded", "code": "rate_limited" } ``` with HTTP `429`. Rate-limited requests are **not billed**. The current production limits are deliberately quiet — the platform is built around credit metering, not request-count throttling — but they exist as a circuit breaker. If you're seeing `429` in normal operation, you're almost certainly in a runaway loop; check **Console → Activity** to see what's firing. ## Backoff strategy When you see `429`, `502 upstream_error`, `503 unavailable`, or `408 timeout`, back off and retry. The right shape is **exponential backoff with full jitter**: ```ts async function withRetry(fn: () => Promise, max = 4): Promise { for (let attempt = 0; attempt < max; attempt++) { try { return await fn(); } catch (err) { if (!isRetryable(err) || attempt === max - 1) throw err; const base = Math.min(1000 * 2 ** attempt, 8000); // 1s, 2s, 4s, 8s cap const delay = Math.random() * base; // full jitter await new Promise((r) => setTimeout(r, delay)); } } throw new Error("unreachable"); } function isRetryable(err: unknown): boolean { const code = (err as { code?: string }).code; return code === "rate_limited" || code === "upstream_error" || code === "unavailable" || code === "timeout"; } ``` Three guidelines: - **Cap the base.** Don't let the delay grow unboundedly — 8 seconds is plenty for a 25-second-deadline API. - **Jitter, always.** Without jitter, a fleet of clients backing off in lockstep will pile back on the platform together and trigger the same `429`. - **Limit total attempts.** Three to four retries is the sweet spot. Beyond that you're typically masking a real problem. Do **not** retry `400 bad_request`, `401 unauthorized`, `402 credits_exhausted`, `403 forbidden_url`, or `404 not_found`. These are caller-side or logical errors — retrying changes nothing and just delays the failure surface. ## Concurrency, not just throughput A 25-second deadline means that a workspace running 10 concurrent fetches can sustain ~24 requests/minute per concurrency slot. The throughput ceiling is usually concurrency × turnaround, not the rate-limit number. For high-volume workloads: - **Bound your own concurrency.** A worker pool with a hard cap (e.g. 20 in-flight requests) is more predictable than firing everything at once and reacting to `429`. - **Prefer batching primitives.** A single `/gyre` with `maxPages: 50` is one HTTP connection and one billed call (per the gyre schedule); 50 individual `/fetch` calls is 50 round-trips and 50 chances to hit the deadline. - **Use `/map` when you only need URLs.** It's a single 1-credit call and almost never times out. ## Idempotency All `/api/v1/*` endpoints are **idempotent** — retrying the same request produces the same effect on Gyrence's side (no state change beyond the usage event). Safe to retry on transient failures without extra deduplication. The one thing retries don't reverse is **what was billed**. If a request succeeded on attempt 1 but the response was lost in the network, the retry on attempt 2 will succeed (and bill) again. In practice this is rare — server-side timeouts are very different from client-side connection failures — but worth knowing. MCP traffic at [`/api/mcp`](/docs/api/mcp) shares the same per-workspace rate-limit bucket and the same 25-second deadline as HTTP. Picking MCP doesn't relax (or tighten) any limit. ## Raising your limits If your workload genuinely needs more than the default rate (and the credit pool to back it), contact us. Limit increases are tied to plan, not pay-as-you-go. > **Rate limit vs. credits** — Running out of credits returns `402 credits_exhausted` — your workspace can't make any billable call, regardless of rate. Running into the rate limit returns `429 rate_limited` — your workspace is making calls faster than allowed, even if the credit balance is healthy. Different problems, different remedies. --- # Workspaces Source: https://www.gyrence.com/docs/concepts/workspaces.md A **workspace** is the unit of ownership in Gyrence. Every API key, every credit balance, and every usage event belongs to exactly one workspace. When you call the API, the key you present is what tells us which workspace to bill and which activity log to write to. Workspaces are how teams share access without sharing credentials, and how a single person separates unrelated projects — staging vs. production, client A vs. client B — into clean, independently-metered ledgers. ## What a workspace owns - **API keys.** Minted in the console, scoped to the workspace, revocable at any time. A key never moves between workspaces. - **Credit balance.** Fetches, searches, gyres, maps, and extracts draw down the workspace's credits. Top-ups apply to one workspace. - **Usage events.** Every billable call is recorded against the workspace, viewable on the Activity and Usage pages. - **Members.** Humans who can sign in to the console and see the workspace's keys, usage, and settings. What a workspace does **not** own: the data you fetch. Gyrence does not retain fetched page content beyond the response. ## Members and roles Roles control what a member can do **inside the console**. API keys are not role-scoped — any valid key gives full API access to the workspace it belongs to. | Role | Can do | | --- | --- | | `owner` | Everything `admin` can, plus delete the workspace and transfer ownership. Exactly one per workspace. | | `admin` | Mint and revoke keys, invite members, change settings, view usage. | | `member` | View usage and activity. Cannot mint keys or invite. | ## Switching workspaces The workspace switcher in the top-right of the console scopes everything below it — keys, usage, activity, settings — to the selected workspace. The switcher is the only place workspace context is set; there is no per-page override. A signed-in user always has at least one workspace. Personal workspaces are created on first sign-in; team workspaces are created from **Settings → Workspaces → New**. ## Lifecycle | State | Meaning | | --- | --- | | Active | Keys work, usage accrues, members can sign in. | | Decommissioned | All keys revoked. History (usage events, member list) is retained. The workspace cannot be re-activated — create a new one. | Workspaces are **never deleted** in production. To wind one down, revoke every key and rename it (e.g. `acme-prod` → `acme-prod-decommissioned-2026-05`). The historical ledger stays intact for audit and reconciliation. > **Why no delete?** — Usage events are financial records. Deleting a workspace would orphan the events tied to it and break reconciliation against invoices. Revoke-and-rename gives you the same operational outcome without breaking the ledger. ## Common patterns - **One workspace per environment.** `acme-dev`, `acme-staging`, `acme-prod` — separate keys, separate credit pools, separate dashboards. The cleanest way to keep staging traffic out of production billing. - **One workspace per client.** Agencies and consultancies give each client their own workspace so usage and costs map 1:1 to invoices. - **A shared "ops" workspace.** For internal monitoring, scraping, or research that isn't tied to a customer-facing product. --- # API keys Source: https://www.gyrence.com/docs/concepts/api-keys.md An **API key** is what tells Gyrence which [workspace](/docs/concepts/workspaces) a request belongs to. Every call to `/api/v1/*` carries a key in the `Authorization` header, and that key — not the caller's identity — is what we bill, log, and rate-limit against. Keys are minted in the console, scoped to one workspace, and revocable at any time. ## Anatomy of a key ``` mc_VHJ5dGhpc2lzbm90YXJlYWxrZXk └┬┘ └─────────────┬─────────────┘ │ │ │ └── 32 chars of url-safe random (24 bytes, base64url) └─── fixed prefix ``` Every key starts with `mc_` followed by 32 random URL-safe characters. The plaintext is shown **exactly once**, at the moment of minting. We store only a SHA-256 hash plus the first 8 characters of the random part (the **key prefix**, e.g. `VHJ5dGhp…`) so you can identify a key in the console without ever exposing the full value. If you lose a key, you can't recover it — revoke it and mint a new one. ## Sending a key All endpoints take the key as a bearer token in the `Authorization` header: ```bash curl https://www.gyrence.com/api/v1/fetch \ -H "Authorization: Bearer mc_VHJ5dGhpc2lzbm90YXJlYWxrZXk" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com" }' ``` A missing, malformed, or revoked key returns `401 unauthorized`. The `mc_` prefix is required — keys without it are rejected before the hash lookup. The same key authenticates the [MCP endpoint](/docs/concepts/mcp) at `POST /api/mcp` — header-only, never in the URL path. No separate "MCP key" type exists; an HTTP key works over MCP and vice versa. > **Never put keys in client code** — Keys grant full API access to a workspace and draw down its credit balance. Treat them like a database password: server-side only, in environment variables or a secret manager, never shipped to a browser or mobile app. ## Minting and revoking Keys are managed at **Console → API keys**, scoped to the currently-selected workspace. - **Mint.** Give the key a human name (`prod-backend`, `ci-runner`, `intern-laptop`). The plaintext appears in a one-time reveal — copy it before closing the dialog. - **Revoke.** Revocation is immediate. Subsequent requests with that key get `401 unauthorized`. Revoked keys stay in the list (greyed out) so the historical audit trail in Usage and Activity remains intelligible. A workspace can hold as many keys as you like; there is no per-key credit cap (all keys on a workspace share the workspace's credit pool). ## Rotation There's no built-in expiry, but rotating periodically is good hygiene — especially after a teammate leaves, a deploy environment is decommissioned, or a key may have been exposed in a log or screenshot. The zero-downtime rotation pattern: 1. Mint a new key alongside the old one. 2. Roll the new value out to whatever uses the old key (deploy, CI secret update, etc.). 3. Once traffic on the old key drops to zero (check **Usage** filtered by key prefix), revoke it. ## One key per use, not one key per person Keys identify a **caller**, not a human. The clean pattern is: - One key per deployed environment (`prod`, `staging`, `dev`). - One key per automation (`ci`, `nightly-batch`, `webhook-handler`). - A short-lived key per developer laptop during local work — revoked when no longer needed. This makes the Usage page legible (you can see *which* surface is burning credits), and it limits blast radius when a single key is exposed. ## What a key does **not** grant - **Console access.** Signing in is via your account — keys don't authenticate humans into the dashboard. - **Cross-workspace access.** A key is bound to exactly one workspace and cannot be promoted, transferred, or scoped to a different one. Mint a new key on the target workspace instead. - **Selective endpoint access.** Today, any valid key can call any `/api/v1/*` endpoint on its workspace. Per-key scopes are on the roadmap, not shipped. ## Common patterns - **Per-environment keys with matching workspaces.** Pair `acme-prod` workspace + `prod-backend` key, `acme-staging` workspace + `staging-backend` key. Credits, usage, and blast radius all stay separate. - **Short-lived dev keys.** Mint a `dev-laptop-` key for local exploration; revoke it the same day. Cheaper than building a key-vault around a long-lived shared key. - **One key per integration.** If you call Gyrence from three services, give each its own key. When one starts misbehaving, you can revoke without disrupting the others. --- # Credits Source: https://www.gyrence.com/docs/concepts/credits.md **Credits** are how Gyrence meters usage. Every successful API call draws down the calling [workspace](/docs/concepts/workspaces)'s credit balance; every failure that didn't do real work is free. The schedule is flat, transparent, and tied to the actual cost of executing the call — not to which plan you're on or how recently you signed up. ## The schedule | Endpoint | Cost | | --- | --- | | `POST /api/v1/fetch` | **1** (HTTP tier or existing transcript) or **3** (browser tier); **10** when speech recognition is submitted | | `POST /api/v1/fetch/transcript` | **0** (speech-recognition status poll) | | `POST /api/v1/search` | **2** base; plus per-result fetch cost if `fetch: true` | | `POST /api/v1/gyre` | sum of per-page costs across `pages[]`, minimum **1** | | `POST /api/v1/map` | **1** flat (regardless of `limit`) | | `POST /api/v1/extract` | **5** (HTTP tier) or **7** (browser tier) | | `GET /api/v1/health` | **0** | | `POST /api/mcp` (any tool) | identical to the underlying primitive — see [MCP](/docs/concepts/mcp) | There is no per-request surcharge, no monthly minimum, and no rounding-up of partial work. ## HTTP tier vs. browser tier Fetch, gyre, and extract all use the same two-tier fetcher: - **HTTP tier** is a plain HTTP GET. Cheap and fast — works for the majority of pages on the open web. - **Browser tier** runs the page in a real headless browser with JavaScript executed. Used when the HTTP tier returns a soft block (403/429/503), when the response is suspiciously small, or when the page is a JS shell with no rendered content. The endpoint escalates automatically; you don't pick a tier per call. You can force the browser tier by passing `forceBrowser: true` on `/fetch` and `/extract` — useful when you already know the target needs JS and want to skip the cheap-tier attempt. ## What costs what, exactly **Fetch.** One credit if the HTTP tier returns a usable response; three credits if the request escalated (or was forced) to the browser tier. With `transcript: true`, existing YouTube captions or a publisher podcast transcript cost 1 credit. Speech recognition costs 10 credits when the job is submitted; polling `/fetch/transcript` is free. **Search.** Two credits for the search itself (Brave Search is our dominant variable cost at ~$0.005/call, so the base is 2 to keep unit economics intact). If you set `fetch: true`, each fetched result bills at its own tier (so a 5-result search where 2 results needed the browser is `2 + 1 + 1 + 1 + 3 + 3 = 11`). **Gyre.** Per-page billing across the response's `pages[]` array: 1 per HTTP-tier page, 3 per browser-tier page, with a 1-credit minimum even if zero pages succeed. Pages that errored or were blocked land in `errors[]` and are **free** — they don't count against the budget or the bill. **Map.** A flat 1 credit regardless of how many URLs come back. Map prefers the sitemap and doesn't fetch page content, so it stays cheap. **Extract.** Higher base cost than fetch because every successful call also runs a model pass against the source text. It is 5 credits for HTTP pages and transcript-derived extraction, or 7 when a non-media page requires browser rendering. **Health.** Free, always. Use it for liveness probes and key validation without burning credits. ## What's never charged - **Auth failures** (`401`) — the request never reached the primitive. - **SSRF blocks** (`403 forbidden_url`) — refused before any fetch. - **Bad input** (`400 bad_request`) — schema validation rejection. - **Timeouts** (`408`) — the 25-second hard deadline tripped before useful work completed. - **Upstream errors** (`502 upstream_error`) — origin returned a 5xx; we didn't get the content you asked for. - **Rate limits** (`429`) — Gyrence-side throttling; you didn't get anything, so you don't pay. The rule is: **if the response doesn't include the data you asked for, you weren't billed**. The one exception is the gyre 1-credit floor, which exists so a request that returns zero pages still records as a metered call. ## Where credits live Credits are a single pool on each workspace. Every key on the workspace draws from the same pool; there is no per-key allocation. Top-ups, plan grants, and refunds all apply at the workspace level. You can watch the balance — and the events drawing it down — at **Console → Usage** (totals and trends) and **Console → Activity** (event-by-event log with cost and tier). > **402 vs. 0 credits** — Running out of credits returns `402 credits_exhausted`. Internal-plan workspaces never return `402` — they're untill metered for visibility but not gated on balance. ## Estimating spend A few sanity-check numbers for the back-of-the-napkin: - **A docs gyre with 50 pages, all HTTP tier:** 50 credits. - **A search with 10 results and `fetch: true`, mixed tiers (~30% browser):** roughly `2 + (7×1) + (3×3) = 18` credits. - **An extract over a JS-heavy product page (browser tier):** 7 credits. - **A YouTube transcript using captions:** 1 credit. - **A direct MP3 submitted for speech recognition:** 10 credits; later status polls are free. - **A liveness check from a cron job, once a minute:** 0 credits (use `/health`). - **The same calls over MCP:** identical to the rows above. Transport doesn't change cost. ## Common patterns - **Use `/health` for warm-up and validation.** Free. Confirms the key is alive and the platform is reachable before you start spending. - **Map first, then fetch selectively.** When you only need a handful of pages from a large site, run `/map` (1 credit) to find the URLs, then `/fetch` the specific ones you want. Cheaper than a wide gyre. - **Inline `fetch: true` on search when you'll fetch every result anyway.** One round-trip, same total credits, half the latency. - **Skip `forceBrowser` until you know you need it.** The auto-escalation only charges browser-tier when it actually runs the browser. Forcing it gives up the cheap-tier savings. --- # Audio & video Source: https://www.gyrence.com/docs/concepts/audio-video.md Gyrence can turn spoken content into either a timestamped transcript or structured JSON. The right resource depends on the output you need. ## Choose the right resource - **Need the spoken words with timestamps and speakers?** Use **Fetch** with `transcript: true`. It returns `kind: "transcript"` with `segments[]`. - **Need facts, summaries, quotes, chapters, or other fields?** Use **Extract**. It returns `extractedJson` shaped by your prompt and optional schema. - **Need to upload a local audio or video file without writing code?** Use **Console → Extract** for structured JSON from the file's transcript. ## Supported inputs - **YouTube:** watch, Shorts, live, embed, `youtu.be`, and YouTube Music URLs when a caption track is available. - **Podcast RSS:** the newest feed item. Gyrence first reads a Podcasting 2.0 `` file in WebVTT, SRT, or JSON format. If none is usable, it can transcribe the item's media enclosure. - **Direct media URLs:** MP3, M4A, AAC, WAV, OGG/OGA, Opus, FLAC, MP4, M4V, MOV, WebM, and MKV URLs, or URLs whose response declares an audio/video content type. - **Local files:** audio/video files up to **95 MB** through **Console → Extract**. > **Source priority** — Existing source text always wins. Gyrence uses YouTube captions or the publisher's podcast transcript without a speech-recognition call. Speech recognition is used only for a direct media URL, a podcast enclosure without a usable transcript, or an uploaded file. ## No-code: extract from a URL or file 1. Open [Console → Extract](/app/extract). 2. Paste a YouTube, podcast-feed, or direct media URL. Alternatively, choose an audio/video file from your device. 3. In **what to extract**, describe the result you need. Examples: - `Summarize the main argument and return five supporting quotes with timestamps.` - `Return every company, product, person, and date mentioned.` - `Create chapters with a title, start time, and two-sentence summary.` 4. Optionally provide a JSON shape in **schema**. 5. Select **Run extract**. File transcription may take a few minutes. For URL inputs, Extract detects supported media automatically; there is no transcript switch to turn on. A natural-language description can also be resolved to a URL first, which adds Resolve credits. ## HTTP: get a timestamped transcript Set `transcript: true` on Fetch: ```bash curl -X POST https://www.gyrence.com/api/v1/fetch \ -H "Authorization: Bearer $GYRENCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://www.youtube.com/shorts/VIDEO_ID", "transcript": true }' ``` When captions or a publisher transcript are available, the response completes immediately: ```json { "ok": true, "data": { "kind": "transcript", "status": "completed", "url": "https://www.youtube.com/shorts/VIDEO_ID", "source": "captions", "language": "en", "segments": [ { "startMs": 0, "endMs": 2840, "speaker": null, "text": "Opening line of the video." } ], "dataClass": "public" } } ``` `source` is `captions`, `podcast_rss`, or `asr`. Speaker labels are included when the source supplies them or speech recognition can separate speakers. ## Poll speech-recognition jobs Speech recognition can outlast a single request. If it is still running after the initial wait, Fetch returns: ```json { "ok": true, "data": { "kind": "transcript", "status": "processing", "url": "https://example.com/episode.mp3", "source": "asr", "jobId": "WORKSPACE_SCOPED_JOB_ID", "pollAfterMs": 3000, "dataClass": "public" } } ``` Wait at least `pollAfterMs`, then send the `jobId` to the status endpoint using the same workspace API key: ```bash curl -X POST https://www.gyrence.com/api/v1/fetch/transcript \ -H "Authorization: Bearer $GYRENCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jobId":"WORKSPACE_SCOPED_JOB_ID"}' ``` The status endpoint returns another `processing` result or the completed transcript. Polling is free. A job ID is signed to its workspace and cannot be read with another workspace's key. A delivered speech-recognition transcript cannot be collected again. ## MCP The same workflows are available through the existing tools: - Call `gyrence_fetch` with `{ "url": "…", "transcript": true }` for transcript segments. - Call `gyrence_extract` with a media URL, a `prompt`, and optional serialized JSON `schema` for structured output. - Local file upload is available in the Gyrence console, not through these URL-based MCP tools. MCP uses the same handlers, response shapes, credits, and activity log as HTTP. ## Credits - Fetch using existing YouTube captions or a podcast transcript: **1 credit**. - Fetch using speech recognition: **10 credits** when the job is submitted. - Transcript status polls: **0 credits**. - Extract: the normal Extract price, **5 credits**, or **7** only when browser rendering is used for a non-media page. Resolve-from-description adds **4 credits**. ## Limits and failure behavior - A YouTube video with no caption track returns `not_found`; Gyrence does not download or separate YouTube audio for speech recognition. - Podcast RSS processing targets the newest `` in the feed. - Extract sends at most the first **12,000 characters** of the transcript to the model. For long recordings, the structured result may cover only the beginning. - URL-based speech recognition submits the resolved public media URL directly. Gyrence does not download, extract, or transcode its audio first. - Uploaded files must identify as audio or video and must not exceed **95 MB**. - Long speech-recognition work should use Fetch's asynchronous polling flow. The console's one-step Extract flow can time out on long files; retry with a shorter file or use transcript polling through the API/MCP. - Failed transcription returns an error or `not_found`; Gyrence never fabricates a transcript. ## Data handling Transcript inputs are treated as **public data**. Gyrence does not persist uploaded media or transcript text. Speech-recognition work is handled by AssemblyAI, and Gyrence requests deletion of the provider transcript after the completed result is delivered. See [Subprocessors](/docs/subprocessors). --- # Gyring Source: https://www.gyrence.com/docs/concepts/gyring.md **Gyre** (verb): to follow a site's link graph outward from a seed URL, capturing each page's content as you go. Named after the spiraling outward motion — you start at one point and wind through the connected web around it. In the Gyrence pipeline, gyring is the **multi-page walking primitive**, distinct from fetching a single URL or mapping a site's link surface. ## When to gyre Use a gyre when you need the **content** of multiple connected pages, in one call, without orchestrating queue + fetch yourself. Reach for gyre when: - You have a seed URL and want the surrounding cluster of pages (e.g. a documentation root, a product category page, a press-release index). - You want each visited page returned with its title, description, and markdown — not just a list of URLs. - The site doesn't expose a clean sitemap, or its sitemap is too coarse for what you need. Reach for a **different primitive** when: | You want… | Use | | --- | --- | | One specific page's content | [Fetch](/docs/api/fetch) | | The full URL surface of a site, no content | [Map](/docs/api/map) | | Pages matching a query across the web | [Search](/docs/api/search) | | Structured JSON pulled from page content | [Extract](/docs/api/extract) | ## How a gyre walks A gyre is a breadth-first walk bounded by a page budget: 1. The seed URL is fetched. 2. Its outbound links are enqueued (filtered by `sameDomain` if set). 3. The next URL in the queue is fetched; its links are enqueued. 4. Steps 2–3 repeat until `maxPages` successful fetches have happened, or the queue is exhausted. Each page goes through the same two-tier fetcher as the `/fetch` endpoint: plain HTTP first, escalating to the headless-browser worker when the page needs JS, returns a soft block, or rate-limits. ## Budget and billing `maxPages` caps **successes**, not attempts. A page that 404s or trips the block-page detector lands in `errors[]` and does not count against the budget. Billing is per-page: 1 credit for HTTP-tier pages, 3 for browser-tier. The total cost is the sum across the response's `pages[]`, with a minimum of 1. ## Scope: `sameDomain` By default a gyre stays on the seed's exact hostname. `blog.example.com` is **not** treated as same-domain as `example.com` — subdomains are out of scope. Set `sameDomain: false` to follow links anywhere on the public web (still subject to SSRF rules). If your goal is "find every URL on this site, including subdomains," gyre is the wrong tool — use [Map](/docs/api/map), which prefers sitemaps and is built for surface discovery rather than content capture. ## Common patterns - **Mirror a small docs site.** Seed the docs root, set `maxPages: 50`, `sameDomain: true`. You get a markdown corpus you can feed straight to an LLM or your own RAG index. - **Capture a press-release cluster.** Seed a `/newsroom` or `/press` page; the gyre fans out to the linked releases. - **Snapshot a product category.** Seed a category index; capture the linked product detail pages in one call. ## Limits - `maxPages` range: 1–50 per request. - 25-second hard deadline on the whole request. - No `maxDepth` parameter today — depth is bounded indirectly by `maxPages` and BFS order. - Visited URLs are tracked verbatim. `?ref=x` and `?ref=y` count as distinct pages. > **Try it** — Run a gyre from the console at [/app/gyre](/app/gyre) — pick a seed, set a budget, watch pages stream in. --- # MCP integration Source: https://www.gyrence.com/docs/concepts/mcp.md Gyrence exposes all five primitives over the **Model Context Protocol** (MCP) at a single hosted endpoint. If your agent runtime speaks MCP — Claude Desktop, Cursor, Continue, an OpenAI Responses-API client, your own SDK — you can drop Gyrence in without writing HTTP plumbing. Everything you read here is *additive* to the HTTP API. Same workspace, same API key, same credits, same activity log. Picking MCP vs. HTTP is a transport choice, not an account choice. ## What is MCP? The **Model Context Protocol** is an open spec for connecting LLM-driven agents to external tools and data sources. An MCP server advertises a set of *tools* (typed JSON-RPC methods); a *client* (your agent runtime) calls them on the agent's behalf. Gyrence's MCP server advertises five tools — one per primitive — and the client picks which to call based on the agent's reasoning. The wire protocol is JSON-RPC 2.0, transported over HTTP with optional Server-Sent Events for streaming responses. You do not need to know any of this to use Gyrence via MCP. You configure your client once with the endpoint and an API key; the rest is the agent doing what agents do. ## The endpoint ``` POST https://www.gyrence.com/api/mcp Authorization: Bearer mc_ Content-Type: application/json ``` That's the entire surface — one URL, one bearer token, JSON-RPC bodies in and JSON or SSE out. There are no per-tool subpaths, no session cookies, no separate handshake. `GET` and `DELETE` are rejected with HTTP `405`. The MCP standalone-SSE channel is **not** offered today. > **Why header auth, not URL-path auth?** — Putting the key in the path (e.g. /api/mcp/mc_…) leaks it into platform access logs, browser history, and any proxy in front of Gyrence. Header auth keeps the secret out of every URL-shaped log surface. If you're migrating from an earlier MCP integration that used path-based keys, just move the key into the Authorization header. ## The tools The MCP server exposes exactly the five primitives, named with the `gyrence_` prefix so they don't collide with other servers your client might be wired to: | MCP tool | Underlying endpoint | When the agent should pick it | | --- | --- | --- | | `gyrence_search` | `POST /api/v1/search` | The agent doesn't have a URL yet — needs to *find* pages by query. | | `gyrence_fetch` | `POST /api/v1/fetch` | The agent has one known URL and needs content, or timestamped media segments with `transcript: true`. | | `gyrence_gyre` | `POST /api/v1/gyre` | The agent wants the cluster around a seed URL — docs, releases, a category. | | `gyrence_extract` | `POST /api/v1/extract` | The agent needs structured facts, summaries, quotes, or chapters from a page or media URL. | | `gyrence_map` | `POST /api/v1/map` | The agent needs to know *what URLs exist* on a site without fetching them. | Tool descriptions (visible to the model during selection) call out credit cost and link back to the live credit schedule at [`/docs/concepts/credits`](/docs/concepts/credits). The schemas advertised over MCP are the **same Zod objects** that validate the HTTP requests — `searchHandler.schema`, `fetchHandler.schema`, and so on. There is no possibility of drift between the two transports. ### Audio and video tool selection Ask the agent to call `gyrence_fetch` with `transcript: true` when you need the spoken words as timestamped `segments[]`. Ask it to call `gyrence_extract` with the media URL and a prompt when you need a summary or structured fields. Existing captions and publisher transcripts are preferred; direct media and podcast enclosures can use speech recognition. See [Audio & video extraction](/docs/concepts/audio-video) for supported inputs, polling, credits, and limits. ## Billing parity This is the central guarantee, and it's worth stating plainly: **a call via MCP costs exactly the same as the equivalent HTTP call, and produces an identical row in your `usage_events`**. This isn't a careful audit — it's how the code is structured. Each MCP tool's `execute` synthesizes an internal `Request` and calls the **same `handle()` function** the HTTP route delegates to. That function is the only place credit metering, status mapping, and the `recordUsage` write happen. There is no separate MCP code path that could diverge. Concretely, after an MCP `tools/call` for `gyrence_gyre`, you'll see a `usage_events` row with: - `endpoint = "gyre"` (the primitive, not "mcp") - `credits_used`, `via`, `status_code`, `status`, `latency_ms` — all identical in shape to an HTTP call - `url` — the seed URL passed in the tool arguments The Activity page in the console shows MCP and HTTP traffic in the same table. There is no MCP vs. HTTP filter because, at the billing/audit layer, there's nothing to filter — it's the same event. ## Authentication and concurrency Two implementation choices worth knowing about: - **Header auth, parsed up-front.** Every request reads the bearer token (with raw Authorization and `X-API-Key` compatibility for clients that implement “header auth” differently), then calls `authenticateMcpKey(key)`. A missing or invalid key returns JSON-RPC error `-32001` ("Unauthorized") with HTTP `401`. Failed auth is never billed. - **Per-request MCP server.** Gyrence constructs a *fresh* `McpServer` instance per request, with the parsed key captured in each tool's closure. Two concurrent calls authenticated with different keys cannot share server state. This was verified end-to-end: six interleaved requests across two workspaces produced zero cross-attribution. In practice this means MCP behaves exactly like HTTP for concurrency: per-workspace rate limits and the 25-second hard deadline apply identically. ## Configuring a client The exact configuration shape varies by client, but the inputs are always the same: the URL and the bearer token. ### Claude Desktop Add an entry to `claude_desktop_config.json` under `mcpServers`: ```json { "mcpServers": { "gyrence": { "transport": { "type": "http", "url": "https://www.gyrence.com/api/mcp", "headers": { "Authorization": "Bearer mc_your_key_here" } } } } } ``` Restart Claude Desktop. The five `gyrence_*` tools appear in the tool picker; Claude will reach for them when a prompt implies web data work. ### Cursor Cursor's MCP config (`~/.cursor/mcp.json` or the in-app settings) takes the same shape: ```json { "mcpServers": { "gyrence": { "url": "https://www.gyrence.com/api/mcp", "headers": { "Authorization": "Bearer mc_your_key_here" } } } } ``` ### Anything else If your client speaks MCP over HTTP, you need exactly: - **URL:** `https://www.gyrence.com/api/mcp` - **Method:** `POST` - **Headers:** `Authorization: Bearer mc_…`, `Content-Type: application/json` The body is whatever JSON-RPC payload your client emits. The server speaks the standard MCP methods (`initialize`, `tools/list`, `tools/call`, `notifications/initialized`). For a minimal raw-curl `tools/call` example, see [API → MCP](/docs/api/mcp). ## When to pick MCP vs. HTTP Use MCP when: - The consuming surface is an agent runtime (Claude Desktop, Cursor, an MCP-aware framework). The integration is one config block instead of a custom tool wrapper per primitive. - You want the agent to pick *which* primitive to call. The tool descriptions are written to guide selection: `gyrence_search` when there's no URL, `gyrence_fetch` for one known URL, etc. - You want zero code on your side to map primitives to tools. Use HTTP when: - You're building a non-agent pipeline (a batch job, a webhook handler, a cron). Plain HTTP is simpler than wiring an MCP client. - You need to drive the call deterministically from your own code (e.g. "always fetch this URL when X happens"). MCP adds a layer of model-driven dispatch you don't want. - You're shipping an SDK — the HTTP API is the stable surface SDKs are generated from (`/openapi.json`). Most teams end up using both: HTTP for the deterministic backend pipelines, MCP for the agent surfaces. ## What MCP does not add A short list of "it's HTTP under the hood, so this is the same": - **No separate plan, no separate pricing.** MCP traffic counts against the same monthly credit pool as HTTP. - **No separate rate limits.** Per-workspace limits and the 25-second deadline are shared across transports. - **No richer auth model.** A key that works over HTTP works over MCP, and vice versa. Per-key scopes are not shipped today. - **No new primitives.** If a primitive isn't on the HTTP API, it isn't on MCP either. The two are mirror images. > **Try it without an agent** — The fastest sanity check is a single curl against tools/list with your key in the header — you'll get back the five tool definitions. See the example at [API → MCP](/docs/api/mcp). --- # Claude connector Source: https://www.gyrence.com/docs/concepts/claude-connector.md Gyrence is available as an OAuth-connected MCP server. This lets Claude (and other MCP clients) connect as your signed-in Gyrence user rather than requiring a workspace API key. Use this page when you are adding Gyrence to Claude via **Settings → Connectors → Add custom connector**. ## Required URLs | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `MCP server URL` | `URL` | | | https://www.gyrence.com/oauth-mcp | | `OAuth issuer` | `URL` | | | https://thegdtvinsunsqcmngsa.supabase.co/auth/v1 | | `OAuth protected resource` | `URL` | | | https://www.gyrence.com/.well-known/oauth-protected-resource | | `Consent URL` | `URL` | | | https://www.gyrence.com/.lovable/oauth/consent | | `Manifest` | `Path` | | | .lovable/mcp/manifest.json (auto-generated) | ## How to connect 1. In Claude, go to **Settings → Connectors** and choose **Add custom connector**. 2. Paste the MCP server URL: `https://www.gyrence.com/oauth-mcp`. 3. Claude fetches the OAuth resource metadata and opens the Gyrence consent screen. 4. Sign in with your Gyrence Google account. 5. Click **Approve** on the consent screen. 6. Claude can now call `whoami`, `list_blog_posts`, `upsert_blog_post`, and `upsert_release_note`. ## Important notes - Use `https://www.gyrence.com/oauth-mcp`, not `https://gyrence.com/oauth-mcp`. The apex redirects to `www` and some MCP clients do not follow redirects. - The OAuth server supports dynamic client registration, so no manual Client ID or Secret is required. - The OAuth server exposes identity and content tools: `whoami`, `list_blog_posts`, `upsert_blog_post` (writes Markdown to `public.blog_posts.content_md`), and `upsert_release_note` (writes Markdown to `public.release_notes.body_md`). Content writes run as the signed-in user and require the Gyrence admin role. The five Gyrence data primitives are served by the workspace-key endpoint at `/api/mcp`. - The consent screen is at `/.lovable/oauth/consent`. If you are sent to the login page first, sign in and you will be redirected back to consent automatically. ## Adding the retrieval primitives (second connector) The five primitives (`search`, `fetch`, `gyre`, `extract`, `map`) are **not** on the OAuth connector. They live on a separate MCP server that authenticates with a workspace API key. Add it as its own custom connector: 1. Create a workspace key at `https://www.gyrence.com/app/api-keys` (keys start with `mc_`). 2. In Claude, **Settings → Connectors → Add custom connector**. 3. Server URL: `https://www.gyrence.com/api/mcp` (full URL — a bare `/api/mcp` path will not resolve). 4. Auth: bearer token — paste the `mc_…` key as the credential. Claude sends `Authorization: Bearer mc_…`. A machine-readable descriptor of this endpoint (auth schemes, tool names) is served at `https://www.gyrence.com/.well-known/mcp.json`. ## Troubleshooting If Claude reports "this session can't run that flow itself", you are using the `claude_desktop_config.json` transport, which does not support OAuth. You must add Gyrence through Claude's in-app connector settings instead. > **Two MCP surfaces** — Gyrence has two separate MCP endpoints: > > - **OAuth (this page):** `https://www.gyrence.com/oauth-mcp` — signs you in as a Gyrence user. > - **Workspace key:** `https://www.gyrence.com/api/mcp` — uses a bearer API key and exposes the five primitives. See [MCP integration](/docs/concepts/mcp) for that setup. --- # Blog publish webhook Source: https://www.gyrence.com/docs/concepts/blog-webhook.md `POST /api/public/hooks/blog-publish` writes a post directly into the Gyrence blog. Use it when an external routine (for example a scheduled Claude job) needs a deterministic publish path that does not depend on the agent picking the right MCP connector. ## Endpoint ``` POST https://www.gyrence.com/api/public/hooks/blog-publish content-type: application/json ``` ## Authentication Two accepted paths — send one: 1. **Bearer token** (recommended for LLM agents): `authorization: Bearer ` 2. **HMAC signature** (recommended for CI/CD pipelines): `x-gyrence-signature: sha256=` Unauthenticated calls return `401` with `{ ok: false, code: "unauthorized" }`. ## Body | Field | Required | Notes | | --- | --- | --- | | `slug` | yes | lowercase kebab-case, unique — the upsert key | | `title` | yes | max 300 chars | | `content_md` | yes | markdown body | | `dek` | no | short lead/subtitle | | `cover_image_url` | no | absolute URL | | `published_at` | no | ISO-8601 with offset. Omit or `null` to keep it a draft | | `author_id` | no | UUID of a `profiles` row | ## Example ```bash curl -sS -X POST https://www.gyrence.com/api/public/hooks/blog-publish \ -H "content-type: application/json" \ -H "authorization: Bearer $GYRENCE_ADMIN_MCP_TOKEN" \ -d '{ "slug": "weekly-source-intelligence-2026-08-16", "title": "Weekly source intelligence", "dek": "What moved across our registry this week.", "content_md": "## Highlights\n\n- ...", "published_at": "2026-08-16T13:00:00Z" }' ``` ## Response ```json { "ok": true, "data": { "id": "…", "slug": "weekly-source-intelligence-2026-08-16", "url": "https://www.gyrence.com/blog#weekly-source-intelligence-2026-08-16", "published": true, "action": "created" } } ``` Re-posting the same `slug` updates the existing post and returns `"action": "updated"`, so retries are safe. ## Errors | Code | Status | Meaning | | --- | --- | --- | | `unauthorized` | 401 | Missing or wrong bearer token / signature | | `bad_request` | 400 | Invalid JSON or a field that failed validation | | `db_error` | 500 | Write failed — retry | | `config` | 500 | Neither credential is configured on the server | ## Which path should the weekly routine use? Prefer this webhook over the generic Supabase MCP connector. That connector authenticates as a personal Supabase account, which can never be a member of the org that owns this hosted project — so `get_project` there fails permanently. The webhook has no such dependency. --- # Content-Signals Source: https://www.gyrence.com/docs/concepts/content-signals.md Gyrence surfaces the publisher's declared **Content-Signals** ([Cloudflare's robots.txt extension](https://blog.cloudflare.com/content-signals-policy/)) on every `/fetch` response. The signals are **informational** — Gyrence does not alter retrieval based on them. Subscribers decide whether to honor the publisher's stated preference downstream. ## The three signals | Signal | Meaning | |------------|---------| | `search` | Inclusion in a search index that links back to the source. | | `ai-input` | Use as real-time input to an AI system (e.g. RAG, grounding). | | `ai-train` | Use as training data for an AI model. | Each signal carries one of three values in the response: - `"yes"` — operator explicitly granted that use. - `"no"` — operator explicitly restricted that use. - `null` — operator **did not state a preference**. Never assume a default. ## Response shape Every successful `/fetch` response includes `data.contentSignals`: ```json { "ok": true, "data": { "kind": "html", "url": "https://example.com/article", "markdown": "…", "contentSignals": { "search": "yes", "aiInput": "no", "aiTrain": "no", "scope": "wildcard", "raw": "Content-Signal: search=yes, ai-input=no, ai-train=no" } } } ``` `scope` indicates which group in `robots.txt` matched: - `"ua-specific"` — the operator declared a group naming Gyrence's user agent. - `"wildcard"` — matched the `User-agent: *` group. - `"none"` — no `Content-Signal` directive in `robots.txt`, or `robots.txt` is unreachable. All three signals are `null`. `raw` is the verbatim `Content-Signal:` line that matched (or `null`). > Robots fetch failures never fail your document fetch. A 404 on `/robots.txt`, a timeout, or a missing `Content-Signal:` line all return the same `scope:"none"` shape — the request succeeds. ## What Gyrence does with these signals In v1: **nothing.** Gyrence retrieves the document and attaches the signals to the response. The platform does not block, gate, or alter crawl behavior based on `ai-train=no` or any other value. This is deliberate. The operator's stated preference is most useful at the point of *use* — when you decide whether to index a page, ground an LLM on it, or include it in a training corpus. Gyrence surfaces the signal verbatim so your downstream policy can honor it cleanly. --- # Search Source: https://www.gyrence.com/docs/api/search.md Run a web search via Brave and optionally fetch each result page as markdown in the same call. The discovery primitive in the Gyrence pipeline — **Search** finds, Fetch reads one, Gyre walks many. ## Use this when - You need discovery → cleaned markdown in a single call (RAG, agent tool, research pipeline). - You're running site-scoped queries (`site:sec.gov 8-K`, `site:fda.gov recall`) and want the bodies, not just the SERP. - You want recency control beyond Brave's defaults (`tbs: "y2"`, `"y3"`, `"y5"`). - You need per-URL credit attribution — `results[].fetch.via` tells you which result paid HTTP vs browser tier. **Endpoint:** `POST /api/v1/search` **Auth:** Bearer **Credits:** 2 base + (1 per http sub-fetch, 3 per browser sub-fetch) when fetch: true ## Request | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `query` | `string` | yes | | Search query. Min length 1. | | `limit` | `number` | | `10` | Max results. Range 1..20. | | `fetch` | `boolean` | | `false` | Fetch each result URL inline and attach a fetch field to each result. | | `fetchFormats` | `("markdown" | "links" | "html")[]` | | `["markdown"]` | Which fields to populate on each inline fetch. html is accepted but not currently emitted. | | `tbs` | `"d" | "w" | "m" | "y" | "y2" | "y3" | "y5"` | | | Time window: past day / week / month / 1–5 years. y2/y3/y5 post-filter Brave's 1-year cap. | ### Example body ```json { "query": "site:sec.gov 8-K corporate action", "limit": 10, "fetch": true, "fetchFormats": ["markdown"], "tbs": "m" } ``` ## Response | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `query` | `string` | | | Echo of the input query. | | `totalResults` | `number` | | | Count of returned results. | | `via` | `"http" | "browser" | "n/a"` | | | Dominant sub-fetch tier across results, or the literal "n/a" when fetch: false. | | `results[]` | `SearchResult[]` | | | Ordered results, rank 1..N. | | `results[].rank` | `number` | | | 1-based rank after filtering. | | `results[].title` | `string` | | | Page title from Brave. | | `results[].url` | `string` | | | Result URL. | | `results[].snippet` | `string` | | | Brave-provided snippet. | | `results[].description` | `string` | | | Alias of snippet. | | `results[].age` | `string?` | | | Relative age (e.g. "3 months ago") when Brave provides it. | | `results[].page_age` | `string?` | | | ISO timestamp when Brave provides it. | | `results[].fetch` | `object?` | | | Present only when fetch: true. See below. | ### `results[].fetch` on success | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `ok` | `true` | | | | | `markdown` | `string` | | | Empty string when "markdown" not in fetchFormats. | | `links` | `string[]` | | | Empty array when "links" not in fetchFormats. | | `statusCode` | `number` | | | Origin HTTP status. | | `via` | `"http" | "browser"` | | | Tier that produced this sub-fetch. Drives credit cost (1 vs 3). | ### `results[].fetch` on failure | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `ok` | `false` | | | | | `error` | `string` | | | Failure reason (timeout, SSRF block, upstream error). | | `via` | `"http" | "browser"` | | | Always "http" on failure. | ### Example response ```json { "ok": true, "data": { "query": "site:sec.gov 8-K corporate action", "totalResults": 2, "via": "http", "results": [ { "rank": 1, "title": "Form 8-K — Example Corp", "url": "https://www.sec.gov/...", "snippet": "Item 8.01 Other Events...", "description": "Item 8.01 Other Events...", "page_age": "2026-05-12T14:00:00Z", "fetch": { "ok": true, "markdown": "# Form 8-K\n\n...", "links": [], "statusCode": 200, "via": "http" } } ] } } ``` ## Example ```bash curl -X POST https://www.gyrence.com/api/v1/search \ -H "Authorization: Bearer $GYRENCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"site:sec.gov 8-K","limit":10,"fetch":true,"tbs":"m"}' ``` ## Errors | Code | HTTP | Meaning | | --- | --- | --- | | `bad_request` | 400 | `query` missing/empty, or any field fails validation. | | `unauthorized` | 401 | Missing, malformed, or revoked `Authorization` header. | | `credits_exhausted` | 402 | Workspace balance below request cost. | | `timeout` | 408 | Request exceeded the 25-second hard deadline. | | `rate_limited` | 429 | Per-workspace rate limit, or Brave returned 429. | | `upstream_error` | 502 | Brave returned 5xx or unparseable response. | ```json { "ok": false, "error": "brave returned 503", "code": "upstream_error" } ``` > **Credits** — Total = **2 base + Σ sub-fetches**, where each sub-fetch is **1** (HTTP tier) or **3** (browser tier). With `fetch: false`, it's a flat **2**. Read `results[].fetch.via` to attribute cost per URL. Failed sub-fetches are not charged. > **Coverage & known limits** — - **Max 20 results per call.** For deeper coverage, paginate by refining `query` or `tbs`. > - **Sub-fetches are capped at 10s each** (independent of the 25s request deadline). Slow origins surface as `{ ok: false, error: "timeout" }` on that result; the envelope still succeeds. > - **SSRF sub-fetches** to private / loopback / link-local hosts return `{ ok: false }` per result — they don't fail the whole call. > - **`tbs ≥ y2`** uses Brave's `freshness=py` and post-filters by parsed date. Results without a parseable `page_age` / `age` are kept (not dropped). > - **`html` in `fetchFormats`** is accepted today but not emitted. Use `/fetch` directly when you need the cleaned HTML field. ## Notes - **Inline-fetch concurrency.** Up to 5 sub-fetches run in parallel; each capped at 10s independent of the 25s request deadline. - **Result ordering.** Results are returned in Brave's relevance order, then filtered (e.g. by `tbs`), then re-numbered with `rank: 1..N`. - **Per-URL fetcher.** Each sub-fetch uses the same two-tier pipeline as `/fetch` (HTTP → browser escalation, SEC.gov fast path, block-page detection). > **Try it** — Run Search from the console at [/app/search](/app/search) — toggle `fetch`, set a `tbs` window, and inspect per-result tier. --- # Fetch Source: https://www.gyrence.com/docs/api/fetch.md Retrieve a single URL and return its parsed title, description, markdown body, lightly-cleaned HTML, and outbound links. Two-tier fetcher: plain HTTP first, escalating to a headless-browser worker when the page needs JS, returns a soft block, or rate-limits. ## Fetch infrastructure - **Intelligent two-tier routing** — HTTP-first with automatic escalation to headless browser rendering on JS-shell detection, bot-protection signals (403/429/503), or post-conversion content loss. Domain health tracking fast-paths known browser-required hosts, skipping the HTTP attempt entirely. - **Per-host concurrency cap** — enforces `PER_HOST_CAP = 3` concurrent outbound connections per target host across all concurrent Gyre walks. - **On-the-fly payload trimming** — strips base64 data URIs, SVG path coordinate blobs, and embedded media data URIs before markdown conversion, eliminating binary content that carries no information value. - **Bounded by design** — per-page (8s), first-page (12s), and worker (18s) timeout constraints. Requests exceeding the 25-second hard deadline return `code: "timeout"`. - **Iframe content surfacing** — `