Making Requests
Base URL, headers, naming conventions, and the standard error format.
2 min read
Base URL#
All v1 endpoints live under:
https://api.chamelingo.com/api/v1
Required Headers#
Every request needs:
| Header | Value |
|---|---|
Authorization | Bearer ck_live_... |
Content-Type | application/json (for POST/PATCH) |
Naming Convention#
The API uses snake_case for all request and response fields:
JSON
{
"card_count": 42,
"cover_emoji": "📚",
"is_public": false,
"created_at": "2026-03-20T12:00:00.000Z"
}
This differs from the internal camelCase — the conversion happens at the API boundary.
Pagination#
List endpoints support limit and offset (or cursor for conversations):
bash
# Offset pagination
curl "https://api.chamelingo.com/api/v1/decks?limit=10&offset=20" \
-H "Authorization: Bearer ck_live_YOUR_KEY_HERE"
# Cursor pagination
curl "https://api.chamelingo.com/api/v1/conversations?limit=20&cursor=clxyz456" \
-H "Authorization: Bearer ck_live_YOUR_KEY_HERE"
Paginated responses include a total count:
JSON
{
"items": [...],
"total": 42,
"limit": 10,
"offset": 20
}
Error Response Format#
All non-streaming errors return a standard JSON envelope:
JSON
{
"success": false,
"error": {
"title": "Not found",
"message": "Deck not found.",
"retryable": false,
"statusCode": 404,
"code": "NOT_FOUND"
}
}
Status Codes#
| Code | Meaning | When |
|---|---|---|
| 400 | Bad Request | Invalid request body or query params |
| 401 | Unauthorized | Missing, invalid, revoked, or expired API key |
| 402 | Payment Required | Quota exhausted (upgrade to Pro) |
| 403 | Forbidden | Account suspended or key lacks required scope |
| 404 | Not Found | Resource not found or not owned by user |
| 409 | Conflict | Concurrent stream on same conversation |
| 429 | Too Many Requests | Rate limit exceeded (check Retry-After) |
| 500 | Internal Error | Server error (retryable) |
Tip
Always check the retryable field. If true, back off and retry. If false, fix your request.
Dates#
All dates are ISO 8601 strings in UTC:
2026-03-20T12:00:00.000Z