Athenous API

Open a guide for the order of calls. Open the API reference for one path, its fields, and a form that sends the request.

Base URL https://public-api.athenous.io Auth X-Api-Key Workspace X-Athenous-Workspace-Id

Authentication

Every public call sends X-Api-Key: ath_…. The key needs api and a Pro, Agency, or Enterprise plan. Keep it in an environment variable. Do not put it in client-side code or a repository.

Create an API key

1. Open Settings → API keys.
2. Enable REST API (api). Add CLI (cli) only if you will use the terminal.
3. Copy the key once. Athenous stores only a hash.

export ATHENOUS_API_KEY=ath_xxxx

A key that lists neither athenous_post nor athenous_ad can call both products. A key that lists one of them is limited to that product. Inbox and post analytics follow Posts. Automation analytics stays available either way. Rate limits and status codes are on Errors.

Workspace

Posts, Ads, Connectors, Inbox, post analytics, and automation need X-Athenous-Workspace-Id. The value is the workspace id from GET /api/v1/collaborate/workspaces. Lists, creates, and updates then stay in that workspace. Without the header, those calls use rows that have no workspace.

The value is a UUID. Anything else returns 400 and detail Invalid workspace id. A workspace you do not belong to returns 403 and detail Not a member of this workspace. Quota, billing, and webhooks stay on the account. Collaborate puts the workspace id in the path.

export ATHENOUS_WORKSPACE_ID=$(curl -sS "https://public-api.athenous.io/api/v1/collaborate/workspaces" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" | jq -r '.[0].id')

Quick start

Schedule one post. Use the key from Authentication and the workspace id from Workspace on every request.

Add the Athenous API to this project. Read https://developers.athenous.io/ first and follow it.

1. Read the API key from the ATHENOUS_API_KEY environment variable. Never hardcode it or commit it.
2. Call https://public-api.athenous.io and send X-Api-Key on every Posts, Inbox, Ads, Analytics, Collaborate, and Connectors request.
3. Read ATHENOUS_WORKSPACE_ID and send X-Athenous-Workspace-Id on Posts, Ads, Connectors, and post analytics. List workspaces with GET /api/v1/collaborate/workspaces and use the id field.
4. List connections with GET /api/v1/connectors and keep the id of the account I connected.
5. Create a draft with POST /api/v1/posts. Send channels as an array. Send channelSettings as a JSON string; each channel object needs connectorId.
6. Approve with POST /api/v1/posts/{id}/approve.
7. Schedule with PUT /api/v1/posts/{id}?status=SCHEDULED and body {"scheduledAt":"..."} in ISO-8601 UTC.
8. Confirm with GET /api/v1/posts/{id} and show me status.

Ask me which channel to use before you start. Stop if any call returns an error. Do not call publish unless I ask: publish sends the post immediately.

curl -sS "https://public-api.athenous.io/api/v1/connectors" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -H "X-Athenous-Workspace-Id: $ATHENOUS_WORKSPACE_ID"

POST_ID=$(curl -sS -X POST "https://public-api.athenous.io/api/v1/posts" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -H "X-Athenous-Workspace-Id: $ATHENOUS_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "March update",
    "body": "Hello from the API",
    "channels": ["linkedin"],
    "channelSettings": "{\"linkedin\":{\"contentType\":\"post\",\"connectorId\":\"CONNECTOR_UUID\"}}"
  }' | jq -r '.id')

curl -sS -X POST "https://public-api.athenous.io/api/v1/posts/$POST_ID/approve" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -H "X-Athenous-Workspace-Id: $ATHENOUS_WORKSPACE_ID"

curl -sS -X PUT "https://public-api.athenous.io/api/v1/posts/$POST_ID?status=SCHEDULED" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -H "X-Athenous-Workspace-Id: $ATHENOUS_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt":"2026-03-20T14:00:00Z"}'

Athenous publishes SCHEDULED posts at scheduledAt. A per-channel scheduledAt inside channelSettings overrides the post time for that channel. Publish now, retry a failed channel, and upload media on Posts. Status rules are on How-to.

Glossary

Short definitions for the words these docs use. The field each one maps to is in the API reference.