Remote API

Keys

The site owner makes keys in the directory's admin: Settings › API keys › Create key. A key is shown once and looks like this:

wds_live_k7f2m9qa_Qm4xT9vR2pLw8ZcN5jHyB3uE6sKd1aFg

wds_live_ (or wds_test_ on test copies), then the key ID, which is not secret, then the secret. Each key has an access level made of permissions (shown with every endpoint below), and may be limited to IP addresses or given an end date. The owner can switch any key off, rotate it or delete it at any time; everything a key changes is in the site's activity log.

Some things are never possible with a key: making or changing keys, the admin password, payment and API-key settings, templates' files and anything that runs code.

Requests

Send the key in a header, never in the address, and use https:

curl https://example-directory.com/api/v1/site \
  -H "Authorization: Bearer wds_live_k7f2m9qa_Qm4x..."

Bodies are JSON (Content-Type: application/json), except picture uploads, which may be multipart. If a server drops the Authorization header, send X-Api-Key instead. Where address rewriting is not available, the same requests work as /api/index.php?r=/v1/site. Hosts that block PATCH and DELETE accept POST with X-HTTP-Method-Override.

Answers and errors

{"ok": true, "data": { ... }, "meta": {"total": 120, "page": 1, "per": 25, "pages": 5}}
{"ok": false, "error": {"code": "invalid", "message": "Some fields need fixing.", "fields": {"url": "must be a full address"}}}

Limits and safe retries

• 600 requests an hour per key. Twenty wrong keys from one address block it for an hour.
• Send an Idempotency-Key header with a POST, PATCH or DELETE: repeating the request with the same key within a day returns the first answer (with Idempotent-Replayed: true) instead of doing it twice.
• Lists return 25 items a page by default, at most 100 (per, page).

Endpoints

All paths start with /api/v1. The permission each needs is shown under it.

Site

Listings

Categories

Business pages

Articles

Other

Event notices

Event notices

Instead of asking every few minutes, a program can be told when something happens. The site sends a POST with a JSON body to the subscribed address:

{"event": "listing.submitted", "site": "https://example-directory.com/", "time": "2026-10-08T09:30:00+00:00",
 "data": {"id": 1204, "title": "Joe the Plumber", "url": "https://joe.example.com/", "category_id": 17, "premium": false}}

Events: listing.submitted, listing.approved, payment.received, payment.refunded, bizpage.submitted, article.review, article.published, article.deleted, newsdesk.finished, key.rotated, site.updated. Answer with any 2xx status; otherwise the notice is sent again, waiting longer each time, for 24 hours.

Each notice is signed. Check it before trusting it:

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_WDS_TIMESTAMP'];
$want = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret); // secret from the subscription
if (! hash_equals($want, $_SERVER['HTTP_X_WDS_SIGNATURE']) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

Headers: X-WDS-Event, X-WDS-Delivery (a number, the same on every retry), X-WDS-Timestamp, X-WDS-Signature.

Versions

/api/v1/ stays as it is. Changes that would break programs get a new version; GET /site tells which version and features a site has.

Questions: contact us.