ZADS ESSENTIAL - DEMO Public REST API

Overview

The public API lives under https://demo-ng.zads.fr/api/v1 and is completely separate from the internal endpoints the website's own front-end uses. It never relies on login sessions or cookies — every call is authenticated with an App ID + App Secret pair ("App identification"), so it can safely be called from a server, a script, or an MCP server without a human logging in first.

• Read-only in v1: search and fetch listings, categories, and static pages.
• Every call is versioned, authenticated, and logged.
• A machine-readable OpenAPI 3.0 spec describes every endpoint — a natural starting point for generating an MCP server's tool definitions.

Authentication procedure

1. An administrator creates an application from Admin → API Apps (name, description, scopes, rate limit).
2. The panel issues an App ID (public identifier) and an App Secret (shown exactly once — store it in your own secrets manager, it cannot be retrieved again, only regenerated).
3. Every request to /api/v1/* (except /status et /openapi.json) must include both credentials as request headers:

X-App-Id: app_5f3e9c2a1b7d4e6f9a8c7d6e
X-App-Secret: sk_7c1a9e4f6b2d8e0a3c5f7b9d1e3a5c7f9b1d3e5f7a9c1e3b5d7f9a1c3e5b7d9

Alternatively, a single bearer token in the form app_id.secret is also accepted, for clients that only support one Authorization header:

Authorization: Bearer app_5f3e9c2a1b7d4e6f9a8c7d6e.sk_7c1a9e4f6b2d8e0a3c5f7b9d1e3a5c7f9b1d3e5f7a9c1e3b5d7f9a1c3e5b7d9

Versioning

The API is versioned in the URL path: https://demo-ng.zads.fr/api/v1/.... The current version is v1. A future v2 will be introduced as a new path prefix (https://demo-ng.zads.fr/api/v2/...) alongside v1, which will keep working for a documented deprecation period — existing integrations are never broken silently by a version bump.

Making a request

curl "https://demo-ng.zads.fr/api/v1/ads?q=iphone&per_page=5" \
  -H "X-App-Id: app_5f3e9c2a1b7d4e6f9a8c7d6e" \
  -H "X-App-Secret: sk_7c1a9e4f6b2d8e0a3c5f7b9d1e3a5c7f9b1d3e5f7a9c1e3b5d7f9a1c3e5b7d9"

Response format

Every endpoint returns the same JSON envelope:

{
  "success": true,
  "message": "OK",
  "data": { ... }
}

Errors

{
  "success": false,
  "message": "Invalid App ID or App Secret."
}

Rate limits

Each application has a configurable requests-per-minute limit (default 60/min), set from Admin → API Apps. Every call is recorded in Admin → API Logs, where administrators can see per-application volume and error rates.

Reusing this API for an MCP server

This API was designed to be the backend for an MCP (Model Context Protocol) server:

• Stable, versioned URLs and a uniform JSON envelope are easy to wrap as MCP tools.
• The openapi.json spec at this base URL can be fed directly to an OpenAPI-to-MCP-tools generator, or used as the contract when hand-writing tool definitions.
• Create a dedicated application (e.g. "MCP Server") from Admin → API Apps so its usage is tracked separately in API Logs.

API changelog

• v1 — Initial release: App ID/Secret authentication, read-only Ads / Categories / Pages endpoints, OpenAPI spec, call logging.