API Documentation

Welcome to the Calenzy API documentation. This guide will help you integrate with our APIs to access currency data, exchange rates, and more.

Base URL: All API requests should be made to https://api.calenzy.app

Getting Started

To use the Calenzy API, you'll need an API key. You can obtain one by signing up at calenzy.app.

Sign up at calenzy.app to get your API key
Include your API key in the Authorization header
Make requests to the API endpoints
Handle responses and errors appropriately

Authentication

All API requests must include your API key in the Authorization header using the Bearer token format.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Keep your API key secure! Never share your API key in public repositories or client-side code.

Rate Limiting

The Calenzy API implements rate limiting to ensure fair usage. Each API key has a monthly quota.

Currencies API: 10,000 requests per month
Content API: 10,000 requests per month

Rate Limit Headers

Every API response includes headers with information about your current rate limit status:

Header	Description
`X-RateLimit-Limit`	The maximum number of requests allowed per month
`X-RateLimit-Remaining`	The number of requests remaining in the current month
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

Need higher limits? Contact us to discuss custom plans.

Error Handling

The Calenzy API uses conventional HTTP response codes to indicate the success or failure of requests. Errors include detailed messages in multiple languages.

Error Response Format

Error Response

{
  "status": "error",
  "error_code": "unauthorised_key",
  "error_message": {
    "en": "Incorrect API key.",
    "fr": "Clé API incorrecte.",
    "es": "Clave API incorrecta."
  }
}

HTTP Status Codes

Code	Error Code	Description
`200`	-	Success - Request completed successfully
`400`	`bad_request`	Bad Request - The request was malformed or missing required parameters
`401`	`unauthorised_key`	Unauthorized - Invalid or missing API key
`404`	`wrong_path`	Not Found - The requested endpoint doesn't exist
`404`	`no_data`	Not Found - No data found for your request
`405`	`unauthorised_method`	Method Not Allowed - HTTP method not supported for this endpoint
`429`	`quota_exceeded`	Too Many Requests - Monthly quota exceeded
`400`	`invalid_currency`	Bad Request - The provided currency code does not exist
`400`	`invalid_period`	Bad Request - The provided period is not valid (accepted: 1d, 7d, 1m, 3m, 6m, 1y, 5y)
`400`	`same_currency`	Bad Request - Base and target currencies must be different

Currencies API

The Currencies API provides access to comprehensive currency data including multilingual names, symbols, and real-time exchange rates.

GET /v1/currencies

Retrieve a list of all available currencies with names in multiple languages.

Response

Returns an array of currency objects with the following properties:

Field	Type	Description
`code`	string	ISO 4217 currency code (e.g., "USD", "EUR")
`en`	string	Currency name in English
`fr`	string	Currency name in French
`es`	string	Currency name in Spanish
`de`	string	Currency name in German
`zh`	string	Currency name in Chinese (Simplified)
`tw`	string	Currency name in Chinese (Traditional)
`kr`	string	Currency name in Korean
`jp`	string	Currency name in Japanese
`symbol`	string	Currency symbol (e.g., "$", "€")
`is_crypto`	integer	0 or 1 indicating if it's a cryptocurrency
`is_metal`	integer	0 or 1 indicating if it's a precious metal

Example Request

cURL

curl -X GET "https://api.calenzy.app/v1/currencies" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch)

fetch('https://api.calenzy.app/v1/currencies', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data);
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php
$api_key = 'YOUR_API_KEY';
$url = 'https://api.calenzy.app/v1/currencies';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: " . $response;
}
?>

Example Response

200 OK

[
  {
    "code": "USD",
    "en": "United States Dollar",
    "fr": "Dollar américain",
    "es": "Dólar estadounidense",
    "de": "US-Dollar",
    "zh": "美元",
    "tw": "美元",
    "kr": "미국 달러",
    "jp": "米ドル",
    "symbol": "$",
    "is_crypto": 0,
    "is_metal": 0
  },
  {
    "code": "EUR",
    "en": "Euro",
    "fr": "Euro",
    "es": "Euro",
    "de": "Euro",
    "zh": "欧元",
    "tw": "歐元",
    "kr": "유로",
    "jp": "ユーロ",
    "symbol": "€",
    "is_crypto": 0,
    "is_metal": 0
  }
]

GET /v1/currencies/rates

Get the latest exchange rates for all currencies.

Response

Returns an array of exchange rate objects with the following properties:

Field	Type	Description
`code`	string	ISO 4217 currency code
`rate`	number	Exchange rate relative to the base currency

Exchange rates are updated regularly and reflect the latest market data.

Example Request

cURL

curl -X GET "https://api.calenzy.app/v1/currencies/rates" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch)

fetch('https://api.calenzy.app/v1/currencies/rates', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data);
  // Access rate limit headers
  console.log('Rate Limit:', response.headers.get('X-RateLimit-Limit'));
  console.log('Remaining:', response.headers.get('X-RateLimit-Remaining'));
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php
$api_key = 'YOUR_API_KEY';
$url = 'https://api.calenzy.app/v1/currencies/rates';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key
]);

$response = curl_exec($ch);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
curl_close($ch);

// Parse rate limit headers
preg_match('/X-RateLimit-Remaining: (\d+)/', $header, $matches);
$remaining = $matches[1] ?? 'N/A';

$data = json_decode($body, true);
echo "Remaining requests: " . $remaining . "\n";
print_r($data);
?>

Example Response

200 OK

[
  {
    "code": "USD",
    "rate": 1.0
  },
  {
    "code": "EUR",
    "rate": 0.85
  },
  {
    "code": "GBP",
    "rate": 0.73
  },
  {
    "code": "JPY",
    "rate": 110.5
  },
  {
    "code": "CAD",
    "rate": 1.25
  }
]

Response Headers

Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1704067199
Content-Type: application/json; charset=utf-8

GET /v1/currencies/rate

Get the latest exchange rate for a single pair: how many units of target equal one unit of base. Uses the same EUR-pivot logic as historical data (latest snapshot). If base and target are the same currency, the response returns rate 1.

Query Parameters

Parameter	Type	Required	Description
`base`	string	Yes	Base currency code (ISO 4217)
`target`	string	Yes	Target currency code (ISO 4217)

Response

Field	Type	Description
`base`	string	Base currency code (echoed from request)
`target`	string	Target currency code (echoed from request)
`rate`	number	1 unit of `base` in `target` (up to 10 decimal places); always 1 when `base` and `target` are identical
`date_collected`	string	Snapshot timestamp for the rate (ISO 8601)

Example Request

cURL

curl -X GET "https://api.calenzy.app/v1/currencies/rate?base=USD&target=JPY" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch)

fetch('https://api.calenzy.app/v1/currencies/rate?base=USD&target=JPY', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data.base, data.target, data.rate, data.date_collected);
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php
$api_key = 'YOUR_API_KEY';
$url = 'https://api.calenzy.app/v1/currencies/rate?base=USD&target=JPY';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key
]);

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
?>

Example Response

200 OK

{
  "base": "USD",
  "target": "JPY",
  "rate": 149.2738491625,
  "date_collected": "2026-04-09T12:00:00+00:00"
}

GET /v1/currencies/historical

Retrieve historical exchange rates for a currency pair over a given time period. Ideal for powering charts and trend analysis.

Query Parameters

Parameter	Type	Required	Description
`base`	string	Yes	Base currency code (ISO 4217, uppercase, 3 chars) — e.g. `EUR`
`target`	string	Yes	Target currency code (ISO 4217, uppercase, 3 chars) — e.g. `USD`
`period`	string	Yes	Time period identifier (see table below)

Period Values

Value	Meaning	Data points	Interval	Time span
`1d`	1 Day	~72	Every 20 minutes	24 hours
`7d`	7 Days	~84	Every 2 hours	7 days
`1m`	1 Month	~120	Every 6 hours	30 days
`3m`	3 Months	~90	Every 1 day	~90 days
`6m`	6 Months	~90	Every 2 days	~180 days
`1y`	1 Year	~52	Every 1 week	~52 weeks
`5y`	5 Years	~60	Every 1 month	60 months

Response

Returns an object with the following fields:

Field	Type	Description
`base`	string	Base currency code (echoed from request)
`target`	string	Target currency code (echoed from request)
`history`	array	Array of data points sorted chronologically ascending (oldest first)
`history[].date`	string	Timestamp in `yyyy-MM-ddTHH:mm:ss` format (UTC, no timezone suffix)
`history[].rate`	number	Exchange rate: 1 unit of `base` expressed in `target` (minimum 4 decimal places)

Example Request

cURL

curl -X GET "https://api.calenzy.app/v1/currencies/historical?base=EUR&target=USD&period=3m" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch)

fetch('https://api.calenzy.app/v1/currencies/historical?base=EUR&target=USD&period=3m', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Base:', data.base);
  console.log('Target:', data.target);
  data.history.forEach(point => {
    console.log(point.date, point.rate);
  });
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php
$api_key = 'YOUR_API_KEY';
$url = 'https://api.calenzy.app/v1/currencies/historical?base=EUR&target=USD&period=3m';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    $data = json_decode($response, true);
    echo "Base: " . $data['base'] . "\n";
    echo "Target: " . $data['target'] . "\n";
    foreach ($data['history'] as $point) {
        echo $point['date'] . " => " . $point['rate'] . "\n";
    }
} else {
    echo "Error: " . $response;
}
?>

Example Response

200 OK

{
  "base": "EUR",
  "target": "USD",
  "history": [
    { "date": "2026-01-03T00:00:00", "rate": 1.0842 },
    { "date": "2026-01-04T00:00:00", "rate": 1.0856 },
    { "date": "2026-01-05T00:00:00", "rate": 1.0831 }
  ]
}

Date format: All timestamps use yyyy-MM-ddTHH:mm:ss (UTC). No timezone offset or Z suffix is included.

Content API

The Content API provides access to Calenzy's content management system (CMS). This API is available through your company dashboard and allows your website to access content that you manage and edit through the CMS interface. Perfect for headless CMS implementations.

GET /v1/content

Retrieve structured content for your project, including pages, sections, and multilingual content items.

Parameters

Parameter	Type	Required	Description
`project`	query	Yes	Your project ID from the CMS dashboard
`page`	query	No	Filter results by specific page ID
`section`	query	No	Filter results by specific section ID
`Accept-Language`	header	No	Language code for content filtering (e.g., "en", "fr", "es")

Response Structure

The API returns a hierarchical structure organized as:

Pages - Top-level content containers with names and links
Sections - Organized content areas within pages
Items - Individual content fields with various types
Content - Multilingual content values for each item

Content Types: The API supports multiple item types including text, textarea, html, upload_image, upload_file, url, date, datetime, country, country_code, day, month, code, block, list, and tags.

Response Fields

Page Object:

Field	Type	Description
`page`	integer	Unique page identifier
`name`	string	Page name or title
`link`	string	Associated URL or link for the page
`sections`	array	Array of section objects

Section Object:

Field	Type	Description
`section`	integer	Unique section identifier
`title`	string	Section title or name
`is_gallery`	integer	0 or 1 indicating if section is a gallery
`items`	array	Array of item objects (or content objects for galleries)

Item Object:

Field	Type	Description
`item`	integer	Unique item identifier
`title`	string	Item label or title
`description`	string	Optional description or helper text
`type`	string	Content type (text, textarea, upload_image, block, etc.)
`settings`	array	Configuration settings (for block types, defines schema)
`content`	array	Array of content objects with multilingual values

Content Object:

Field	Type	Description
`id`	integer	Unique content identifier
`language`	string	Language code (e.g., "en", "fr", "es")
`content`	mixed	Content value (string for simple types, array for blocks)

Example Request

cURL

curl -X GET "https://api.calenzy.app/v1/content?project=123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept-Language: en"

JavaScript (Fetch)

fetch('https://api.calenzy.app/v1/content?project=123', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept-Language': 'en'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data);
  // Access pages
  data.forEach(page => {
    console.log(`Page: ${page.name}`);
    page.sections.forEach(section => {
      console.log(`  Section: ${section.title}`);
    });
  });
})
.catch(error => {
  console.error('Error:', error);
});

PHP

<?php
$api_key = 'YOUR_API_KEY';
$project_id = 123;
$url = "https://api.calenzy.app/v1/content?project={$project_id}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key,
    'Accept-Language: en'
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    $data = json_decode($response, true);
    foreach ($data as $page) {
        echo "Page: " . $page['name'] . "\n";
    }
} else {
    echo "Error: " . $response;
}
?>

Example Response

200 OK

[
  {
    "page": 1,
    "name": "Home",
    "link": "https://example.com",
    "sections": [
      {
        "section": 1,
        "title": "Hero Section",
        "is_gallery": 0,
        "items": [
          {
            "item": 1,
            "title": "Hero Title",
            "description": "Main heading",
            "type": "text",
            "settings": [],
            "content": [
              {
                "id": 1,
                "language": "en",
                "content": "Welcome to Our Website"
              },
              {
                "id": 2,
                "language": "fr",
                "content": "Bienvenue sur notre site"
              }
            ]
          },
          {
            "item": 2,
            "title": "Hero Image",
            "description": "Background image",
            "type": "upload_image",
            "settings": [],
            "content": [
              {
                "id": 3,
                "language": "en",
                "content": "https://files.calenzy.com/content/hero-bg.jpg"
              }
            ]
          },
          {
            "item": 3,
            "title": "Features",
            "description": "Feature cards",
            "type": "block",
            "settings": [
              {
                "id": "icon",
                "type": "upload_image",
                "title": "Icon",
                "settings": "[]"
              },
              {
                "id": "title",
                "type": "text",
                "title": "Feature Title",
                "settings": "[]"
              },
              {
                "id": "description",
                "type": "textarea",
                "title": "Description",
                "settings": "[]"
              }
            ],
            "content": [
              {
                "id": 4,
                "language": "en",
                "content": [
                  {
                    "icon": "https://files.calenzy.com/content/icon-1.svg",
                    "title": "Fast Performance",
                    "description": "Lightning-fast loading times"
                  },
                  {
                    "icon": "https://files.calenzy.com/content/icon-2.svg",
                    "title": "Secure",
                    "description": "Enterprise-grade security"
                  }
                ]
              },
              {
                "id": 5,
                "language": "fr",
                "content": [
                  {
                    "icon": "https://files.calenzy.com/content/icon-1.svg",
                    "title": "Performance rapide",
                    "description": "Temps de chargement ultra-rapides"
                  },
                  {
                    "icon": "https://files.calenzy.com/content/icon-2.svg",
                    "title": "Sécurisé",
                    "description": "Sécurité de niveau entreprise"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "section": 2,
        "title": "Gallery",
        "is_gallery": 1,
        "items": [
          {
            "id": 6,
            "language": "en",
            "content": "https://files.calenzy.com/content/gallery-1.jpg"
          },
          {
            "id": 7,
            "language": "en",
            "content": "https://files.calenzy.com/content/gallery-2.jpg"
          },
          {
            "id": 8,
            "language": "en",
            "content": "https://files.calenzy.com/content/gallery-3.jpg"
          }
        ]
      }
    ]
  },
  {
    "page": 2,
    "name": "About",
    "link": "https://example.com/about",
    "sections": [
      {
        "section": 3,
        "title": "Team",
        "is_gallery": 0,
        "items": [
          {
            "item": 4,
            "title": "Team Members",
            "description": null,
            "type": "list",
            "settings": [],
            "content": [
              {
                "id": 9,
                "language": "en",
                "content": "John Doe, Jane Smith, Bob Johnson"
              }
            ]
          }
        ]
      }
    ]
  }
]

Block Type Items: Items with type "block" have a settings array that defines the schema for repeatable content structures. Each content entry is an array of objects matching the schema.

Need help? Visit calenzy.com or contact our support team.