Quickstart

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. 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.

What's a workspace?

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.

2. Generate an API key

Open 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.

export GYRENCE_API_KEY="mc_..."

3. Make your first request

Fetch any public URL as clean markdown:

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:

{
  "ok": true,
  "data": {
    "url": "https://example.com/",
    "title": "Example Domain",
    "description": "",
    "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...",
    "html": "<!doctype 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.

4. Use it from 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.

What's next

The other four primitives compose on top of /fetch:

Search — natural-language query → ranked URLs (optionally fetched in the same call)
Gyre — walk a site within a page budget, returning markdown for every page
Extract — fetch a URL and use an LLM to pull structured fields
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 — 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 — header format, key scopes, rotation
Errors — full error envelope and code reference
Rate limits — per-plan limits and backoff strategy
Credits — exactly what each endpoint costs

For coding agents

Point your agent at /llms-full.txt for a single-file plaintext copy of this entire documentation site, or /llms.txt for just the index.