Developer API introduction
The Paradarum CDN exposes the same REST API the dashboard uses, so anything you can do in the panel you can automate from your own scripts, CI pipelines, or CMS plugins. This page orients you to the basics: where the API lives, how to authenticate, and how every response is shaped.
Base URL and conventions
| Item | Value |
|---|---|
| Production base URL | https://api.paradarum.com |
| Development base URL | http://localhost:5252 |
| Path prefix | /api/{resource} (for example /api/property/123/purge) |
| Casing | Routes are case-insensitive — /api/Property and /api/property hit the same endpoint |
| Versioning | A single v1; there is no version segment in the URL |
| Content type | JSON in, JSON out (Content-Type: application/json) |
There is exactly one API version. The string v1 only appears in the OpenAPI document name (/swagger/v1/swagger.json), never in a request URL. You do not need to send an Accept-Version header or a /v1/ prefix.
Authentication at a glance
Every business endpoint requires authentication. Two interchangeable schemes both satisfy the default authorization policy — pick one per request.
| Mode | Header | Best for |
|---|---|---|
| API key | X-API-Key: pdm_... (raw key, no scheme word) | Automation, scripts, CMS purge plugins |
| Bearer JWT | Authorization: Bearer YOUR_JWT | The Paradarum panel / interactive sessions |
For automation, the API key is the right choice — it is account-scoped, long-lived, and never expires on its own. See Authentication for the exact rules and Manage API keys to create one.
You never send an account ID. The authenticated principal's account is injected server-side from your credential, so an API key can only ever touch properties belonging to its own account. Requests for a property in another account return 404 Property not found.
The response envelope
Every endpoint — success or error — wraps its payload in the same envelope.
{
"succeeded": true,
"message": "",
"pageNumber": 1,
"pageSize": 10,
"totalPages": 1,
"totalRecords": 1,
"data": {}
}
| Field | Meaning |
|---|---|
succeeded | true for HTTP status below 400, false otherwise |
message | Human-readable text; carries the error description on failures |
data | The actual payload (an object, an array, or null) |
pageNumber, pageSize, totalPages, totalRecords | Paging metadata — meaningful only for paged list endpoints |
pageNumber, pageSize, totalPages, and totalRecords all default to 1 even on single-object and non-list responses. Ignore them unless you called a paged list endpoint.
Reading errors
There is no machine-readable error code field. Branch on the HTTP status code, then read the human message string for detail.
{
"succeeded": false,
"message": "Property not found.",
"data": null
}
| Status | Typical meaning |
|---|---|
200 / 201 | Success |
400 | Validation failure or bad credentials |
401 | Missing, invalid, or revoked credential |
403 | Action not allowed in the property's current state (for example disabled or suspended) |
404 | Resource not found, or it belongs to another account |
500 | Server-side error |
Pagination, sorting, and filtering
List endpoints accept a shared set of query-string parameters.
| Parameter | Default | Notes |
|---|---|---|
PageNumber | 1 | 1-based page index |
PageSize | 10 | Silently clamped to a maximum of 9999 |
OrderBy | Id asc | Comma-separated, for example title asc,createdAt desc |
Filter | — | URL-encoded SQL-LIKE expression |
GET /api/property?PageNumber=2&PageSize=25&OrderBy=createdAt%20desc&Filter=name.Contains(%22cdn%22)
Authorization: Bearer YOUR_JWT
Read totalRecords and totalPages from the envelope to drive your pagination loop.
Rate limiting
There is no request rate limiting in the API today. Do not build retry logic around a 429 response — none is returned. Be a good neighbor and batch where you can; the batch purge endpoint lets you combine many instructions into one round-trip.
Where to go next
- Authentication — exact headers, key format, and the JWT login flow.
- Manage API keys — create, list, and revoke keys in the dashboard.
- Purging cache — the most common automation task, with ready-to-paste examples.
- API reference — the interactive endpoint catalog.
The full, browsable endpoint contract lives at the API reference. Keep it open while you build.