Connect a website in 5 minutes (API)

The whole publisher flow through the API: website, ownership proof, zones, integration code, test. Your AI agent can do the same.

API reference Postman collection OpenAPI (JSON)

1. Create a token

In the dashboard, “API access” → a new token with sites:write and zones:write. The token is shown only once.

export ADS_TOKEN="…"
export ADS_API="https://ads-laravel.codex.md/api/v1"

2. Add the website

The response contains the website id (data.id) used in the next steps. Categories are IAB codes from GET /taxonomies/iab.

curl -X POST "$ADS_API/sites" \
  -H "Authorization: Bearer $ADS_TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"domain":"exemplu.md","name":"Exemplu","language":"ro","categories":["596"],"audience":["b2c"]}'

3. Prove the website is yours and submit it

The response says exactly which meta tag to put in the home page <head>. After publishing, check it and submit the website to the team (usually one working day).

curl -X POST "$ADS_API/sites/SITE_ID/verification" -H "Authorization: Bearer $ADS_TOKEN" \
  -H "Accept: application/json" -H "Content-Type: application/json" -d '{"method":"meta"}'

# once the meta tag is on the website:
curl -X POST "$ADS_API/sites/SITE_ID/verification/check" -H "Authorization: Bearer $ADS_TOKEN" -H "Accept: application/json"
curl -X POST "$ADS_API/sites/SITE_ID/submit" -H "Authorization: Bearer $ADS_TOKEN" -H "Accept: application/json"

4. Create a zone and get the code

After approval (the site.approved webhook), create zones. The code: the site script once per page plus one element per zone; platform can be html, wordpress, react, nextjs, vue or blade.

curl -X POST "$ADS_API/sites/SITE_ID/zones" -H "Authorization: Bearer $ADS_TOKEN" \
  -H "Accept: application/json" -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Sidebar","size":"300x250"}'

curl "$ADS_API/zones/ZONE_ID/code?platform=html" -H "Authorization: Bearer $ADS_TOKEN" -H "Accept: application/json"

5. Check the integration

After publishing, open a page with the code, then ask whether the zone was seen and is serving.

curl -X POST "$ADS_API/zones/ZONE_ID/integration/check" -H "Authorization: Bearer $ADS_TOKEN" -H "Accept: application/json"

PHP

$http = new \GuzzleHttp\Client(['base_uri' => 'https://ads-laravel.codex.md/api/v1/', 'headers' => [
    'Authorization' => 'Bearer '.getenv('ADS_TOKEN'), 'Accept' => 'application/json',
]]);

$site = json_decode((string) $http->post('sites', [
    'headers' => ['Idempotency-Key' => bin2hex(random_bytes(16))],
    'json' => ['domain' => 'exemplu.md', 'name' => 'Exemplu', 'language' => 'ro', 'categories' => ['596'], 'audience' => ['b2c']],
])->getBody(), true)['data'];

$meta = json_decode((string) $http->post("sites/{$site['id']}/verification", ['json' => ['method' => 'meta']])->getBody(), true);

JavaScript

const api = (path, init = {}) => fetch(`https://ads-laravel.codex.md/api/v1${path}`, {
  ...init,
  headers: { Authorization: `Bearer ${process.env.ADS_TOKEN}`, Accept: 'application/json', 'Content-Type': 'application/json', ...init.headers },
}).then((r) => r.json());

const { data: site } = await api('/sites', {
  method: 'POST',
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({ domain: 'exemplu.md', name: 'Exemplu', language: 'ro', categories: ['596'], audience: ['b2c'] }),
});
const verification = await api(`/sites/${site.id}/verification`, { method: 'POST', body: JSON.stringify({ method: 'meta' }) });

Good to know