# REST API

## URL pattern
`https://zieapi.vercel.app/v1/{category}:{scraper}/{endpoint}[/{path-params}]`

The project key `{category}:{scraper}` identifies the source (e.g. `finance:binance`). Each endpoint documents its verb. Most are `GET` with query parameters; `POST` endpoints take a JSON body. Calling with the wrong verb returns `405` with `content.expected` and an `Allow` header.

## Path parameters
Endpoints such as `profile/:username` take the value in the path: `/v1/social-media:github-user/profile/torvalds`. You can also pass it as a query parameter.

## Success envelope
jsonCopy
```
{ "project": "finance:binance", "data": { … }, "timestamp": "2026-10-26T03:00:00.000Z" }
```

## Response headers
| `X-RateLimit-Remaining` | Requests left this minute |
| `X-RateLimit-Remaining-Month` | Requests left this month |
| `X-Cache` | `HIT`, `MISS`, `BYPASS` or `NONE` |
| `x-request-id` | Include it when reporting an issue |

## Caching
Each endpoint has a default cache TTL. Pro accounts may lower it to 30 s with `?ttl=30`; Ultra and Max may bypass it with `?ttl=0`.