Base URL, headers, error format, rate limits, caching, and OpenAPI spec
Conventions
Base URL
| Environment | Example Base URL |
|---|---|
| Local dev | https://www.web3base.ai/ |
| Production | Deployed origin, e.g. https://example.com |
All paths below are relative to the site root URL (Base URL); full URL = site root + path.
Protocol and encoding
- Protocol: HTTPS in production; HTTP allowed locally.
- Encoding: UTF-8.
- Request body: All public endpoints described here are GET; no request body.
- Response type: JSON endpoints use
Content-Type: application/jsonunless noted.
Common response headers (public content)
Most list and Open endpoints include:
| Header | Meaning |
|---|---|
Cache-Control | Typically public, s-maxage=120, stale-while-revalidate=240 for CDN/browser caching |
Rate limiting
Paths under /api/open/* are rate-limited by middleware:
| Scenario | Default quota |
|---|---|
| By client IP | 60 requests / minute |
With valid X-API-Key header | 300 requests / minute |
Optional environment variables:
| Variable | Description |
|---|---|
OPEN_API_RATE_LIMIT | Per-IP limit per minute; default 60 |
OPEN_API_RATE_LIMIT_KEYED | Limit when key is present; default 300 |
OPEN_API_KEYS | Comma-separated API keys; matched against X-API-Key header |
Example response when over limit:
HTTP 429 Too Many Requests
Retry-After: 60{
"error": "Too Many Requests",
"retryAfter": 60
}Other paths (e.g.
/api/twitter/all) are not currently under this Open rate limit; for high traffic prefer/api/open/*and caching.
Error format
On business or server errors, the JSON body is typically:
{
"error": "Short English or human-readable message"
}| HTTP status | Meaning |
|---|---|
200 | Success |
404 | Resource not found (e.g. nav group slug) |
429 | Open API rate limit |
500 | Server error |
Machine-readable spec (OpenAPI)
- URL:
GET /api/open/spec - Format: OpenAPI 3.0.x JSON
- Use: Import into Postman/Insomnia, code generation, or contract checks.
This complements the human docs; treat the deployed /api/open/spec as authoritative.
Locale
Use the locale query parameter with a supported locale code, e.g. en, zh-hans, zh-hant. Invalid or unknown values fall back to the site default (usually en).