Quickstart

Make your first authenticated request and get clean JSON back in under five minutes. Every hosted API speaks the same REST conventions, so what you learn here works everywhere.

Create a key from the Dashboard → API Keys page. Keys are scoped to your account and carry your plan's rate limits. Treat them like passwords, never commit them to source control or expose them in client-side code.

Send your key in the Authorization header as a bearer token on every request. There are no separate signing steps, if the header is valid, the request is authorized.

# export your key once
export MAVI_KEY="mavi_sk_live_8f2c…"

curl https://api.maviapi.com/v1/sites/hacker-news/stories/top \
  -H "Authorization: Bearer $MAVI_KEY"

Call any endpoint listed on an API's detail page. Responses are JSON with a predictable shape: a top-level data array or object, plus meta for pagination and timing. Below is a typical response from the Hacker News API.

{
  "data": [
    {
      "id": 41284922,
      "title": "Show HN: I built an API for any website",
      "score": 412,
      "by": "musab",
      "comments": 128
    }
  ],
  "meta": { "count": 30, "took_ms": 182 }
}

Endpoints & parameters

Each hosted API exposes a small, documented set of endpoints. Path parameters are written in :colon form; query parameters are appended as usual. A few of the Hacker News endpoints:

Pagination

List endpoints accept limit (default 30, max 100) and cursor. When more results exist, meta.next_cursor is returned, pass it back as cursor to fetch the next page. When it's null, you've reached the end.

Datasets & exports

Need the data once, as a file, rather than an API in your code? Open any API page, pick an endpoint, and choose Get all the data. We follow the site's pages until there are none left and store every row in a dataset you can download as CSV, JSON, or JSONL. One credit per page fetched; the download is free. Turn on auto-refresh (hourly, daily, weekly) if you want it kept current.

Exports can be scripted too. The items endpoint accepts your API key and streams every row:

# every row, as CSV, named after the dataset
curl -H "Authorization: Bearer $MAVI_KEY" \
  "https://api.maviapi.com/v1/me/datasets/DATASET_ID/items?format=csv" -o hotels.csv

• format: csv, json (one array) or jsonl (one document per line). No row cap; add limit to cut it off, desc=1 for newest first.
• X-Maviapi-Row-Count: how many rows the download carries, so a script can check it landed whole.
• A run that reaches a plan cap (pages or rows per run, rows per dataset) finishes as partial with a reason. Nothing is silently truncated.

Rate limits

Limits depend on your plan and are returned on every response so you never have to guess:

• X-RateLimit-Limit: requests allowed in the current window
• X-RateLimit-Remaining: requests left in this window
• X-RateLimit-Reset: unix time when the window resets

Exceeding the limit returns 429 Too Many Requests. Back off until the reset time, then retry.

Errors

Errors use standard HTTP status codes and a consistent JSON body with a machine-readable code and a human message. Build against the code; show the message.

{
  "error": {
    "code": "rate_limited",
    "message": "You've hit your plan's request limit. Retry after the reset."     ,
    "status": 429
  }
}