API Integration Guide

For advanced advertisers and agencies, the GaiaAds Management API offers programmatic control over campaigns, reporting, and assets. This guide complements the full API Reference.

1. Prerequisites

Before writing code, ensure you have:

• API Access Enabled: Contact your account manager to enable API access. This is restricted to accounts with >$5k monthly spend.
• API Key: Generate a Permanent Token in Settings > API Keys. Store this securely; it will not be shown again.
• Environment: We provide a Sandbox environment at https://sandbox-api.gaiaads.com for testing without spending real money.

2. Authentication

All requests must include the Authorization header with your Bearer token.

Headers:
Authorization: Bearer YOUR_ACCOUNT_TOKEN
Content-Type: application/json
Accept: application/json

3. Python Implementation Example

This Python example prepares an illustrative request offline. It sends a POST only when you explicitly set GAIA_SEND_REQUEST=1 in an account-approved environment. It does not verify campaign status or publish a campaign. Confirm currency, units and response schema before use.

import json
import os
import requests

# Illustrative micros: USD 50 daily cap and USD 15 target CPA.
payload = {
    "name": "Reviewed API Campaign",
    "objective": "CONVERSIONS",
    "budget_daily": 50_000_000,
    "bid_strategy": {"type": "TARGET_CPA", "value": 15_000_000},
}

if os.environ.get("GAIA_SEND_REQUEST") != "1":
    print(json.dumps(payload, indent=2))  # Offline preview; no API call.
else:
    base_url = os.environ["GAIA_APPROVED_BASE_URL"].rstrip("/")
    if not base_url.startswith("https://"):
        raise ValueError("Use the approved HTTPS environment")
    headers = {"Authorization": f"Bearer {os.environ['GAIA_API_TOKEN']}"}
    response = requests.post(
        f"{base_url}/campaigns", json=payload, headers=headers, timeout=15
    )
    response.raise_for_status()
    data = response.json()
    print("Request accepted; review the campaign in your approved account.")

The request timeout and HTTP error check follow the Requests documentation. Do not blindly retry a campaign-creation POST after an uncertain response; reconcile it with your account first.

4. Rate Limiting

To ensure stability, we enforce rate limits on a per-account basis.

• Read Requests (GET): 10 requests per second.
• Write Requests (POST, PUT, DELETE): 2 requests per second.
• Reporting API: 5 concurrent report jobs.

Handling 429s: If you receive a 429 Too Many Requests response, your application must respect the `Retry-After` header and back off exponentially.

5. Error Handling

We follow standard HTTP status codes.

• 400 Bad Request: Your JSON payload is malformed or missing required fields. Check the `errors` array in the response body for specific field validation messages.
• 401 Unauthorized: Your token is invalid, expired, or missing.
• 403 Forbidden: Your token is valid, but you do not have permission to access the requested resource (e.g., trying to access another account's campaign).
• 500 Internal Server Error: Something went wrong on our end. Please contact support with the X-Request-ID header value.

6. Webhooks

Instead of polling for status updates, register a webhook endpoint to receive real-time notifications for:

• campaign.approved
• creative.rejected
• budget.exhausted

The company guide describes HMAC-SHA256 signatures. Obtain the exact signed payload, header names, timestamp/replay rules and key-rotation process for your assigned integration before accepting events.