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.

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