APIs/Start here

The basics

What every Calenzy API has in common. Read it once, then go straight to the API you need.

Authentication

Send your API key in the Authorization header of every call.

Your key is in your Calenzy dashboard, under Settings, in the API key card. One key opens every API.

Keep the key on your server. Anyone who has it can read your data and use your quota, so it never belongs in a web page or a public repository.

Header

Authorization: Bearer YOUR_API_KEY

Errors

Every error has the same shape and an HTTP status that matches it.

Test against error_code: it never changes. error_message carries a message in nine languages, to show or to log. These codes can come from any API; each API page lists its own on top.

Common errors

Code	HTTP	When
`bad_request`	400	The request is malformed or misses a required parameter
`unauthorised_key`	401	The API key is missing or unknown
`subscription_inactive`	403	The Calenzy subscription behind the key has lapsed. Renew it from the dashboard
`wrong_path`	404	No endpoint at this path
`no_data`	404	Nothing found for your request
`unauthorised_method`	405	This endpoint does not accept this method
`quota_exceeded`	429	This API's monthly quota is used up. It starts again on the day your plan renews each month (X-RateLimit-Reset)

Response · 401

{
  "status": "error",
  "error_code": "unauthorised_key",
  "error_message": {
    "fr": "Clé API incorrecte.",
    "en": "Incorrect API key.",
    "es": "Clave API incorrecta.",
    "de": "Falscher API-Schlüssel.",
    "zh": "API密钥不正确。",
    "tw": "API密鑰不正確。",
    "kr": "잘못된 API 키입니다.",
    "jp": "APIキーが正しくありません。",
    "bg": "Неверен API ключ."
  }
}

Quotas

Each API allows what your plan includes, every month.

Each API is counted on its own: on Essential, your website can make 250,000 IP lookups and 250,000 exchange rate calls in the same month. Your month runs from the day your plan renews to the same day the next month (a plan that started on the 31st renews on the last day of shorter months), and the count starts again on that day. Once an API reaches its quota it answers quota_exceeded (HTTP 429) until then, with the same three headers and Retry-After.

Calls a month, per API

Plan	Calls a month
Free (no plan)	1,000
Essential	250,000
Pro	1,000,000
Premium	5,000,000

Counted: Files, IP, Currencies, Smoky, Weather. Never counted: Bookings, Clients, SMS, Captcha, Metals, Alerts, and Let a visitor through. Need more than your plan includes? Contact us: we can lift the quota on your key.

Headers

X-RateLimit-Limitinteger	Calls this API allows you this month
X-RateLimit-Remaininginteger	Calls left this month
X-RateLimit-Resetinteger	The last second of your month, as a Unix timestamp: the count starts again just after

Counted APIs send these three headers with every answer. A key without a quota gets none.

Response headers

X-RateLimit-Limit: 250000
X-RateLimit-Remaining: 248650
X-RateLimit-Reset: 1796083199

Requests and answers

JSON in, JSON out, over HTTPS.

Every address starts with https://api.calenzy.app/v1/.
Answers are JSON in UTF-8. Send a body as JSON, with Content-Type: application/json.
Every endpoint shows a request and its answer. Copy as cURL turns any example into a command you can paste into a terminal.
Dates and times follow each API's own rules, given on its page.