API overview

Updated 23 Sep 2026

The API manages zones, hostnames, certificates, purges and signing keys, reads a zone's statistics and lists the locations, with one key per account. It is JSON over HTTPS at https://api.cachegenie.com/v1.

Your key#

The key is issued by Enable API under Account then Settings; New Key replaces it at once and the old one stops working, and Disable API deletes it, so enabling again issues a new one. It is 64 letters and digits and grants full control of every zone on the account, so keep it on your server. Full Access and Developer users can see it; a Billing user cannot.

A first call#

curl https://api.cachegenie.com/v1/cdn \
  -H "Authorization: Bearer YOUR_API_KEY"

Every response is the same envelope: the HTTP status repeated as CODE, a short message in MESSAGE, and the payload in DATA.

{
  "CODE": 200,
  "MESSAGE": "Data returned for all CDN Zones for this account.",
  "DATA": {
    "CDN_ZONES": [
      { "ID": "AB12CD34E", "ZONE_NAME": "video", "...": "..." }
    ]
  }
}

The zone object is shown in full in Zones.

Authentication#

Send the key as a bearer token on every request. The one exception is the Status API, which is public.

Authorization: Bearer YOUR_API_KEY

403 Authentication credentials not provided.: the request carried no Authorization header.
401 Authentication credentials provided, but were invalid.: the header carried something that is not a valid key (a wrong key, an empty one, another scheme), API access is switched off for the account, or the account is suspended.
401 Additional account setup is required via the CacheGenie NOC.: the key is right but the account is not ready: its billing details are incomplete, its agreement has not been entered by our team, or it has no payment card. The NOC says which. See Billing and invoices.
503 The service is temporarily unavailable, please try again in a moment., with Retry-After: 5: the key could not be checked at all. A 401 is a refusal; a 503 is not, and never means the key is wrong.

The key is checked before an endpoint is looked up, so an unknown endpoint under /v1/ called without a key is a 403 rather than a 404. A path outside /v1/, or one that is not a valid path at all, is a 404 whatever the key, and /v1 on its own is 400 API endpoint not specified.

Requests#

The base URL is https://api.cachegenie.com/v1. Plain HTTP is answered with a 301 to HTTPS, which most clients turn a POST into a GET on, so always call it over HTTPS. A path outside /v1/ is a 404.
Send a JSON body with Content-Type: application/json on a POST. The statistics endpoint reads its filters from a JSON body on a GET, which curl and every HTTP library send; a browser's fetch() cannot, so read statistics from a server rather than from a page.
Updates are POST, never PUT or PATCH. They are partial: a field you leave out keeps its value, and where a field can be cleared, an empty string clears it.
Switches are the integers 1 and 0. Timestamps are Unix seconds in UTC. Lists are strings, separated as each field says, never JSON arrays: an array or an object as a field's value is refused with 400 The value of {FIELD} must be a single value, not a list or an object.
Identifiers come from the API itself and are stable: a zone id is nine upper-case letters and digits, a hostname id and a purge id are integers, a location id is a short lower-case code.
A trailing slash on a path is ignored.

Responses#

CODEIntegerthe HTTP status of the response, repeated in the body.
MESSAGEStringa short message saying what happened. Show it to a person; do not parse it.
DATAObjectthe payload. An object for one item, an object holding a named list for a listing (CDN_ZONES, CDN_HOSTNAMES, CDN_NODES, CDN_DAILY_STATS), and an empty list, [], on an error and after a delete.

Every JSON response carries Cache-Control: no-store and permissive CORS headers, and an OPTIONS request is answered 204 before anything else, so a page can call the public Status API directly.

Errors#

Code	Meaning	What to do
400	The request was understood and refused: a missing or invalid field, a name already in use, or a body that is not JSON where one is needed. `MESSAGE` says what.	Fix the request.
401	The key was checked and refused, or the account is not ready. A 401 always means the key really was checked.	Check the key, then the account in the NOC.
403	No key was sent.	Add the Authorization header.
404	`API endpoint is invalid / not found.` (with `All endpoints live under /v1/.` added for a path outside it), or no such zone, hostname, purge or certificate on your account.	Check the path and the id.
405	`API Endpoint - Incorrect HTTP Method.`	Use the method shown for the endpoint.
429	Over a rate limit; see below.	Wait the seconds in `Retry-After` and send it again.
500	A write did not go through. `MESSAGE` says which.	Retry once; if it persists, write to the team with the request and the time.
503	Something could not be checked, so nothing was assumed. It can come from any endpoint, the Status API included.	Retry after the seconds in `Retry-After`. Never treat it as a bad key.

{
  "CODE": 400,
  "MESSAGE": "Invalid Origin URL.",
  "DATA": []
}

Rate limits#

Each client address may make 600 requests a minute, and each API key 300 requests a minute, counted in fixed windows that start on the minute. Over either, the answer is 429 with a Retry-After header holding the seconds left in the window and a message that names the limit: Too many requests for this API key. Try again in 37 seconds. or Too many requests from this address. Try again in 37 seconds.. Nothing is queued on our side. There are no X-RateLimit headers. A request that is refused for a bad path still counts; an OPTIONS request does not.