# Gomry Cloud for agents

> When an AI agent should call Gomry Cloud and when it should not — the jobs each API is right for, the ones it is wrong for, and how to call it safely under a budget.

Source: https://cloud.gomry.com/agents

Gomry Cloud is a set of metered HTTP APIs an autonomous caller can use as tools. This page says **when to reach for them**, which is the one thing the machine-readable descriptions cannot say for themselves.

## When to use this platform

Reach for Gomry Cloud when a task needs something from the open web that you cannot get from your own context, and you want one credential and one invoice rather than an account with each provider. Every operation below is a single JSON POST with a bearer token.

| If the task is… | Call | Notes |
| --- | --- | --- |
| **I have a URL and I need specific fields out of it** | `POST /v1/scrape` | Renders JavaScript first, so single-page apps work. Give it a JSON schema and it returns that shape. Billed per page, and only when a page came back. |
| **I have a URL and I want the raw HTML or its metadata** | `POST /v1/fetch` | No extraction, a quarter the price. The right call when you intend to parse og:image, JSON-LD or the HTML yourself. |
| **I need a capability nobody here has integrated** | `POST /v1/toolsapi/discover` then `/run` | Describe the task in words, get ranked tools with prices, run one. You never hold the vendor's key. |
| **I need an answer that takes many sources, not one page** | `POST /v1/superagent` | Plans, searches, reads, notices what is missing and searches again. Returns a task id immediately; poll it. Every field cites the URL and the sentence behind it. |

## When not to use it

- **You want to find a URL rather than read one.** There is no search endpoint on Scrape. It answers questions about a URL you already have. Superagent searches, but it is the wrong tool when you only wanted a link.
- **You want to crawl a site.** One Scrape call is one page. Following links is yours to orchestrate, and a naive crawl is the fastest way to spend a budget cap.
- **You need the answer inside one HTTP request.** Superagent is asynchronous; `wait: true` is a 60-second convenience, not a guarantee. If a synchronous answer is required, that is `/v1/scrape`.
- **The page is behind a login.** Nothing here authenticates to a third-party site on your behalf.
- **You are retrying a `402` or a `403`.** Neither resolves without a person. A retry loop on a billing refusal is the single most expensive mistake an unattended caller makes here — it cannot succeed and it will not stop.
- **You already have the content.** These are metered calls. Re-fetching a page you fetched a minute ago is billed again.

## Calling safely under a budget

- Start with a `gck_test_` key. Same URL, same body, same response shape, real upstream call, metered at zero.
- Set the project's monthly budget cap before handing a key to an unattended process. It is checked before the work runs, not after.
- Grant the narrowest scopes. `toolsapi:read` browses the catalogue; `toolsapi:run` spends. `tasks:read` supervises work; `tasks:run` starts it.
- Read the metered field in each response — `pages`, `fetches`, `meteredMicroUsd`, `cost.units`. It is exactly what went on the invoice.
- Honour `x-ratelimit-reset` and back off with jitter. Limits are per key.
- Send an `Idempotency-Key` when starting a research task, so a retried request returns the existing task instead of starting a second one.

## Machine-readable entry points

- `https://cloud.gomry.com/openapi.json` — Every endpoint, verb, required scope and example body. Start here to call rather than to read.
- `https://cloud.gomry.com/llms.txt` — This site as an index, linking the Markdown twin of every page.
- `https://cloud.gomry.com/llms-full.txt` — The whole corpus in one fetch.
- `https://cloud.gomry.com/auth.md` — How to obtain, use, rotate and revoke a credential.
- `https://cloud.gomry.com/.well-known/api-catalog` — RFC 9727 linkset pointing at the description and the docs.
- `https://cloud.gomry.com/.well-known/oauth-protected-resource` — RFC 9728 metadata: the resource, its scopes and the bearer methods accepted.
- `https://cloud.gomry.com/.well-known/agent-skills/index.json` — The same capabilities as a skills index.
- `https://cloud.gomry.com/.well-known/ard.json` — Agentic Resource Discovery catalog of everything on this list.
- `https://cloud.gomry.com/mcp` — Documentation MCP server (Streamable HTTP, no credential) — search and read these docs as tools.
- `https://api.cloud.gomry.com/mcp` — Product MCP server (Streamable HTTP, bearer key) — call the APIs as tools.

Any page on this site can be fetched as Markdown by appending `.md` to its URL, or by sending `Accept: text/markdown`.

If you are driving a browser rather than calling HTTP yourself, every public page declares those same documentation tools on `document.modelContext` (WebMCP), so they can be invoked as tools instead of read back off the rendered page. They are the tools of the documentation server above: anonymous, read-only and unbilled. Calling an API still requires a key and still goes to the data plane.