API reference

Base URL https://public-api.athenous.io. Times are ISO-8601 UTC. IDs on posts, campaigns, ad sets, and ads are UUIDs. Account ids are numbers. Channel ids are on Platforms. Walkthroughs are in the guides.

Account

These routes identify the signed-in person. Send the session cookie or Authorization: Bearer. The CLI gets that bearer token from POST /api/v1/auth/cli/token when the key includes cli. Product routes use X-Api-Key instead.

Profile

GET /api/v1/account/me returns:

API keys

Pro, Agency, and Enterprise. The raw key is returned once, on create.

List items use id, name, scope, createdAt, and lastUsedAt.

Sessions and MFA

Integration interest

Authentication

curl -sS -X POST "https://public-api.athenous.io/api/v1/auth/cli/token" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -d "{\"apiKey\": \"$ATHENOUS_API_KEY\"}"

The response field is access_token (some clients also accept token). Use it as Authorization: Bearer. A key without cli is rejected. Scheduling a draft before approve returns a 4xx whose detail is Approve this draft before it can be scheduled.

Default rate limit is 100 requests per minute per key. batch raises that to 500.

Connectors

Connections are created in the app. The API lists them so you can copy connectorId.

Posts

Requires api. A key that includes athenous_ad and omits athenous_post receives 403. Field tables are in Post fields.

Post status values: DRAFT, SCHEDULED, PUBLISHING, PUBLISHED, PARTIAL, FAILED, CANCELLED. Publication status values: PENDING, PUBLISHING, PUBLISHED, FAILED.

Post fields

Times are ISO-8601 UTC, for example 2026-03-20T14:00:00Z. On update, a field you omit keeps its current value.

Request body

POST /api/v1/posts and PUT /api/v1/posts/{id}. PUT also accepts ?status=.

Response body

Returned by create, get, update, approve, and publish. List returns these objects inside content.

List response

Publication

Delete response

DELETE /api/v1/posts/{id} removes the post in Athenous and reports networks that did not remove the live item.

Channels and channelSettings

Use these ids in channels and as keys inside channelSettings: facebook, instagram, threads, linkedin, tiktok, twitter, youtube, snap, reddit, pinterest, discord, bluesky, mastodon, telegram, whatsapp.

Shared fields inside every channel object:

{
  "linkedin": {
    "contentType": "post",
    "connectorId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "tiktok": {
    "connectorId": "660e8400-e29b-41d4-a716-446655440001",
    "tiktok_privacy_level": "SELF_ONLY",
    "tiktok_title": "March update",
    "tiktok_allow_comment": true
  }
}

Ads

Hierarchy is campaign, then ad set, then ad. Publish in that order. A key limited to athenous_post receives 403. Paths below … continue from /api/v1/campaigns/{campaignId}.

Campaign and ad set status: DRAFT, SCHEDULED, ACTIVE, PAUSED, COMPLETED, ARCHIVED. Ad status: DRAFT, ACTIVE, PAUSED, ARCHIVED.

Ad fields

On update, a field you omit keeps its current value. name is required when you create.

Campaign request body

Campaign response body

GET /api/v1/campaigns adds totalConversions (sum of synced conversions for the account), totalActiveCampaigns, and statusCounts (map of each status to a count). Those three are independent of the current page.

Ad set request body

The ad set response adds id, campaignId, userId, createdAt, and updatedAt.

Ad request body

The ad response adds id, adSetId, campaignId, userId, createdAt, updatedAt, and publications when includePublications=true.

Ad publication

Publish and sync bodies

Every platform value, and what each network expects, is on the Ads platforms page. Worked requests are on Posts and Ads.

Sync uses only platform and connectorId, both required.

Errors