Ads

A campaign contains ad sets. An ad set contains ads. Create each one in Athenous, then publish in that order. A key limited to athenous_post receives 403. Field limits are in the ad field tables.

Order

1. Connect the network in the app with purpose Ads. Copy connectorId. List ad accounts with GET /api/v1/connectors/ad-accounts?platform=META (use the platform id you will publish).
2. POST /api/v1/campaigns, then POST /api/v1/campaigns/{id}/publish.
3. POST /api/v1/campaigns/{campaignId}/ad-sets, then publish that ad set.
4. POST …/ad-sets/{adSetId}/ads, then publish that ad.
5. Pull numbers with POST …/sync on the campaign, ad set, or ad. The body is platform and connectorId.

Campaign and ad set status: DRAFT, SCHEDULED, ACTIVE, PAUSED, COMPLETED, ARCHIVED. Ad status: DRAFT, ACTIVE, PAUSED, ARCHIVED. Push local edits with POST /api/v1/campaigns/{id}/push and the same platform and connectorId. Some networks do not apply a remote update. Read publications for the network’s ids and metrics.

Delete one campaign with DELETE /api/v1/campaigns/{id} (204). Delete many with POST /api/v1/campaigns/bulk-delete and {"ids":["…"]}. The response is requested and deleted.

Meta example

CID=$(curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"API campaign","platform":"META","objectiveType":"AWARENESS","budgetAllocation":{"META":5000}}' \
  | jq -r '.id')

curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns/$CID/publish" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform":"META","connectorId":"CONNECTOR_UUID","adAccountId":"act_123","facebookPageId":"123456"}'

ASID=$(curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns/$CID/ad-sets" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Prospecting","dailyBudget":50,"objectiveType":"AWARENESS"}' \
  | jq -r '.id')

curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns/$CID/ad-sets/$ASID/publish" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform":"META","connectorId":"CONNECTOR_UUID","adAccountId":"act_123","facebookPageId":"123456"}'

ADID=$(curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns/$CID/ad-sets/$ASID/ads" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Hero","headline":"March update","bodyText":"Hello","imageUrl":"https://storage.googleapis.com/your-bucket/hero.jpg","ctaLabel":"Learn More","ctaLink":"https://example.com"}' \
  | jq -r '.id')

curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns/$CID/ad-sets/$ASID/ads/$ADID/publish" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform":"META","connectorId":"CONNECTOR_UUID","adAccountId":"act_123","facebookPageId":"123456"}'

curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns/$CID/sync" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform":"META","connectorId":"CONNECTOR_UUID"}'

GET /api/v1/campaigns?includeCounts=true adds adSetCount and adCount on each campaign, plus account-wide totalConversions, totalActiveCampaigns, and statusCounts. List ads with includePublications=true to include publication rows.

Platform ids

Send platform on publish and sync. Connect an Ads account for that network first. Quora, programmatic display, connected TV, and linear TV are planning labels. Publish does not create a campaign on those networks.

Publish body

The same body is used for campaign, ad set, and ad publish. Sync and push send only platform and connectorId.

targetingJson on the ad set is a JSON string of audience and placement options, up to 10000 characters. platformCreativeId on the ad stores a network creative. Snapchat fills it when publish builds the creative. Spotify publish uses a READY audio or video asset id.

Import, export, and OpenAI bulk

Paid plans. GET /api/v1/campaigns/export and GET /api/v1/campaigns/export/csv download the account’s campaigns. POST /api/v1/campaigns/import accepts that JSON and runs asynchronously. CSV import uses Content-Type: text/csv on POST /api/v1/campaigns/import/csv. The header row is GET /api/v1/campaigns/import/template. Limits are GET /api/v1/campaigns/import/limits.

curl -sS -X POST "https://public-api.athenous.io/api/v1/campaigns/openai-bulk-publish" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"connectorId":"CONNECTOR_UUID","adAccountId":"AD_ACCOUNT","campaignIds":["CAMPAIGN_1","CAMPAIGN_2"]}'

That call needs at least two campaign ids. One campaign uses POST /api/v1/campaigns/{id}/openai-bulk-publish with the usual publish fields and platform OPENAI_ADS.