API reference

A key-authenticated REST gateway over the same publishing pipeline as the app. It powers the MCP server, the CLI, and any integration you build.

Base URL

base url
https://api.posteahora.com/functions/v1/api

The /functions/v1/ segment is part of the stable URL — don’t strip it. This is the frozen v1 contract: additive changes only, never breaking ones in place.

Authentication

Every request carries a PosteAhora API key as a bearer token. Keys are created under API and shown once. See Authentication for keys, scopes and plan requirements.

header
Authorization: Bearer pah_live_xxxxxxxxxxxxxxxx
ideas:readList ideas
ideas:writeCreate / update / delete ideas
posts:readList and read posts
posts:writeCreate / update / delete / publish posts
analytics:readRead post analytics
accounts:readList connected social accounts
media:writeRequest presigned media upload URLs

Conventions

  • •JSON request and response bodies. Send Content-Type: application/json.
  • •Timestamps are ISO 8601 (UTC), e.g. 2026-07-20T14:30:00Z.
  • •Rate limiting is per key (429 when exceeded). Your monthly post quota still applies.
  • •Errors have the shape { "error": "message" }.

Errors

400Invalid request (bad body, bad scheduledAt, unknown status, …)
401Missing or invalid API key
403Key lacks the required scope
404Resource not found (or not owned by the key’s user)
429Rate limit exceeded
5xxServer error

Resources

Accounts

Your connected social accounts. Call this first — publishing needs each account’s id, and tokens are never returned.

Ideas

Lightweight backlog items — brainstorming only. They never publish.

Posts

Create drafts, schedule, publish now, edit, and read posts.

Analytics

Read-only metrics, refreshed hourly by the analytics sync crons.

Media

Get a presigned URL, PUT your file to it, then use the returned publicUrl in mediaUrls.

Quick start

Replace ACCOUNT_ID with an id from GET /accounts. See the full Quickstart for a step-by-step.

curlbash
BASE="https://api.posteahora.com/functions/v1/api"
KEY="pah_live_xxxxxxxxxxxxxxxx"

# 1. List accounts
curl -s "$BASE/accounts" -H "Authorization: Bearer $KEY"

# 2. Publish a post now
curl -s -X POST "$BASE/posts" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Hello from the PosteAhora API 👋",
    "accountMappings": [{ "platform": "twitter", "accountId": "ACCOUNT_ID" }],
    "status": "published"
  }'