Documentation Index
Fetch the complete documentation index at: https://docs.monaco.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Monaco’s public API is hosted on api.monaco.com
The Monaco Public API uses API key authentication. Every request must include a valid API key in the Authorization header as a bearer token.
Obtaining an API Key
API keys are created through the Monaco application (Settings > API Keys). When you create a key you will receive a plaintext key with the prefix mks_ — this is the only time the plaintext value is shown. Monaco stores a hash of the key value; the original value cannot be retrieved later.
mks_<48-char-url-safe-token>
Authenticating Requests
Include the key in the Authorization header on every request as a bearer token:
curl -X POST https://api.monaco.com/v1/contacts/list \
-H "Authorization: Bearer mks_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"page": 1, "page_size": 10}'
| Header | Required | Description |
|---|
Authorization | Yes | Your API key as a bearer token |
Content-Type | Yes (POST) | Must be application/json for request bodies |
Error Responses
| Status | Meaning |
|---|
401 | Missing or invalid API key |
403 | API key is valid but lacks required access |
429 | Rate limit exceeded |
401 — No Key / Invalid Key
Returned when the Authorization header is missing or the key does not match any active key.
{
"detail": "No key found"
}
429 — Rate Limited
All endpoints enforce per-org rate limiting. Every org has a limit of 1000 requests per hour. When you exceed the limit, the response includes headers to help you back off:
| Response Header | Description |
|---|
X-RateLimit-Limit | Maximum requests allowed per window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the current window resets |
Retry-After | Seconds to wait before retrying |
Key Management
- Deactivation — Keys can be deactivated from Settings. Deactivated keys are immediately rejected.
- Rotation — Create a new key, migrate your integration, then deactivate the old key. There is no in-place rotation.
Best Practices
- Never expose your key in client-side code or version control. Use environment variables or a secrets manager.
- Respect rate limits. Read the
Retry-After header and implement exponential backoff.
- Rotate keys periodically and immediately if you suspect a leak.
