One key. Fifteen networks. Posts and ads.

Authentication

Base URL

https://public-api.athenous.io

Header

X-Api-Key: ath_…

Scope

Enable REST API (api). Add athenous_post for posts, athenous_ad for ads, or both. A key with neither product scope can call both. CLI-only keys are rejected.

Rate limit

100/min per key. 500/min with Batch. Posts, campaigns, and connectors each have their own window.

curl -sS "https://public-api.athenous.io/api/v1/posts?includePublications=true" \
  -H "X-Api-Key: $ATHENOUS_API_KEY"

Connectors API (prerequisite)

List connections to obtain connectorId values used in posts and ads.

Posts API — full reference

Base path /api/v1/posts.

Supported channels

Use these ids in channels[] and as keys inside channelSettings.

channelSettings reference

channelSettings in the request body is a JSON string (stringify before send). Keys are channel ids. Each value is an object. These fields apply inside every channel object.

{
  "facebook": {
    "contentType": "feed",
    "connectorId": "660e8400-e29b-41d4-a716-446655440001",
    "page_id": "123456789012345",
    "privacy": "public",
    "tags": ["product", "launch"],
    "media_urls": [
      "https://storage.example/img1.jpg",
      "https://storage.example/img2.jpg"
    ]
  },
  "linkedin": {
    "contentType": "post",
    "connectorId": "550e8400-e29b-41d4-a716-446655440000",
    "author_urn": "urn:li:organization:12345",
    "privacy": "public"
  },
  "bluesky": {
    "connectorId": "770e8400-e29b-41d4-a716-446655440002"
  },
  "reddit": {
    "contentType": "text",
    "connectorId": "...",
    "subreddit": "test"
  }
}

Post fields

Every field on a post. Times are ISO-8601 in UTC, for example 2026-03-20T14:00:00Z.

Request body

Sent to POST /api/v1/posts and PUT /api/v1/posts/{id}. On update, a field you omit keeps its current value. PUT also accepts ?status= with one post status.

Response body

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

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "connectorId": null,
  "userId": "user-uuid",
  "title": "March update",
  "body": "Hello world",
  "mediaUrl": "https://storage.googleapis.com/your-bucket/media.jpg",
  "status": "DRAFT",
  "scheduledAt": "2026-03-20T14:00:00Z",
  "publishedAt": null,
  "createdAt": "2026-03-18T10:00:00Z",
  "updatedAt": "2026-03-18T10:00:00Z",
  "approvedAt": null,
  "channels": ["linkedin", "facebook"],
  "channelSettings": "{\"linkedin\":{\"contentType\":\"post\",\"connectorId\":\"...\"},\"facebook\":{\"contentType\":\"feed\",\"connectorId\":\"...\",\"page_id\":\"123\"}}",
  "publications": null,
  "remoteUpdateWarnings": null
}

List response

GET /api/v1/posts returns a page, not a single post.

Publication

One object for each channel the post was sent to. Also returned by GET /api/v1/posts/{id}/publications and POST /api/v1/posts/{id}/sync.

{
  "id": "pub-uuid",
  "postId": "post-uuid",
  "connectorId": "connector-uuid",
  "channel": "linkedin",
  "externalId": "urn:li:share:123",
  "status": "PUBLISHED",
  "errorMessage": null,
  "publishedAt": "2026-03-20T14:01:00Z",
  "syncedAt": "2026-03-21T09:00:00Z",
  "likes": 42,
  "comments": 5,
  "shares": 3,
  "impressions": 1200,
  "views": 0,
  "clicks": 18
}

Delete response

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

Ads API — full reference

Hierarchy: Campaign → Ad set → Ad. Publish top-down.

Ad platforms

Campaigns

Ad sets

Ads

Ad fields

Every field on a campaign, ad set, and ad. Times are ISO-8601 in UTC. On update, a field you omit keeps its current value. name is required when you create.

Campaign request body

POST /api/v1/campaigns and PUT /api/v1/campaigns/{id}. Update also accepts ?status= with a campaign status.

Campaign response body

GET /api/v1/campaigns wraps campaigns in a page. page starts at 0. size is 1 to 1000, default 20.

Ad set request body

POST /api/v1/campaigns/{campaignId}/ad-sets and PUT …/ad-sets/{adSetId}.

Ad set response body

Ad request body

POST …/ad-sets/{adSetId}/ads and PUT …/ads/{adId}.

Ad response body

Ad publication

One object for each network the ad, ad set, or campaign was sent to.

Bulk delete response

POST /api/v1/campaigns/bulk-delete with {"ids": ["…"]}. ids is a required UUID array.

Publish request body

Fields for POST …/publish on a campaign, ad set, or ad.

Sync request body

Fields for POST …/sync on a campaign, ad set, or ad.

Status enums

HTTP errors

Code examples

Start with curl, then switch to Python or Node. Replace connector IDs and your API key.

curl -sS -X POST "https://public-api.athenous.io/api/v1/posts" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API launch",
    "body": "We shipped today.",
    "mediaUrl": "https://storage.example/hero.jpg",
    "channels": ["linkedin"],
    "channelSettings": "{\"linkedin\":{\"contentType\":\"post\",\"connectorId\":\"CONNECTOR_UUID\"}}"
  }'

MEDIA_URL=$(curl -sS -X POST "https://public-api.athenous.io/api/v1/posts/media" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -F "file=@./hero.jpg" | jq -r '.mediaUrl')

# 1) Campaign
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"}' | 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_xxx","facebookPageId":"page_id"}'

# 2) Ad set → 3) Ad (same pattern under /ad-sets/.../ads/...)

import json, os, requests

API = os.environ.get("ATHENOUS_API_URL", "https://public-api.athenous.io").rstrip("/")
KEY = os.environ["ATHENOUS_API_KEY"]
HEADERS = {"X-Api-Key": KEY}

settings = {
    "linkedin": {"contentType": "post", "connectorId": os.environ["LINKEDIN_CONNECTOR_ID"]},
}
post = requests.post(
    f"{API}/api/v1/posts",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "title": "From Python",
        "body": "Hello API",
        "channels": list(settings.keys()),
        "channelSettings": json.dumps(settings),
    },
).json()

const API = (process.env.ATHENOUS_API_URL || "https://public-api.athenous.io").replace(/\/+$/,"");
const headers = { "X-Api-Key": process.env.ATHENOUS_API_KEY };

async function listPosts() {
  const res = await fetch(`${API}/api/v1/posts?size=20&includePublications=true`, { headers });
  return res.json();
}

FAQ

MCP (Claude, Cursor, ChatGPT)