> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aguasto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Public research API

> Search Aguasto research, retrieve public page metadata and run educational calculations over HTTPS.

Use `https://www.aguasto.com` as the base URL. The public research endpoints accept anonymous requests. They read published information and calculate estimates. Use the [Console](https://console.aguasto.com/login) for customer GPU requests.

## Operations

| Method and path | What it does |
| - | - |
| `GET /api/v1/catalog` | List published page descriptions, canonical links and modification dates. |
| `POST /api/v1/pages/batch` | Look up metadata and source links for up to 20 unique published paths. |
| `POST /ask` | Find published references with NLWeb 0.55 list-mode search. |
| `POST /api/v1/calculate` | Estimate model weight memory, facility energy or cost per million completed tokens. |
| `GET /api/v1/sandbox` | Inspect the available synthetic fixtures and operations. |
| `POST /api/v1/sandbox` | Exercise the synthetic search or calculator. |

The [live OpenAPI document](https://www.aguasto.com/openapi.json) defines request fields and response schemas. You can also use the [public website playground](https://www.aguasto.com/developers).

## Search for references

```bash theme={null}
curl --fail-with-body 'https://www.aguasto.com/ask' \
  -H 'Content-Type: application/json' \
  -d '{"query":{"text":"GPU rack cooling"},"prefer":{"mode":"list"}}'
```

Search matches published titles and descriptions. Follow each result’s canonical URL to read the full evidence. For streamed results, include `"streaming":true` inside `prefer`.

## Read catalog pages

```bash theme={null}
curl --fail-with-body 'https://www.aguasto.com/api/v1/catalog?limit=20&offset=0'
```

Use `pagination.next_offset` until it is `null`. For a batch request, send paths such as `/gpus` and `/models`. Results preserve your input order. An unknown path gets a per-item 404 while valid items still return.

```bash theme={null}
curl --fail-with-body 'https://www.aguasto.com/api/v1/pages/batch' \
  -H 'Content-Type: application/json' \
  -d '{"paths":["/gpus","/models"]}'
```

## Run a calculation

```bash theme={null}
curl --fail-with-body 'https://www.aguasto.com/api/v1/calculate' \
  -H 'Content-Type: application/json' \
  -d '{"calculation":"weight_memory","parameters":{"parameters_billions":70,"bits":4}}'
```

The example estimates weight memory from the parameter count and bit width. Plan separately for the runtime, activations, and cache. Calculation outputs are educational estimates.

## Handle errors and limits

REST failures return `error.code` and `error.message`. Check the request on a 400 or 422. On 429, wait for `Retry-After` before retrying. The API also returns rate-limit headers. Instance-level limits are best effort. NLWeb and MCP use their respective error formats. Use [testing and versioning](https://docs.aguasto.com/sandbox-and-versioning.md) for CI fixtures and retry guidance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.