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.

Prefer a machine-readable spec? Load the OpenAPI 3.1 spec into Swagger UI, Postman, or an SDK generator — it includes the full per-platform platformOptions schemas.

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). The workspace owner’s monthly post quota still applies.
  • •A key is bound to one workspace: reads return that workspace’s data, and a viewer-role key cannot write. Use GET /workspaces to see which one.
  • •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 in the key’s workspace)
429Rate limit exceeded
5xxServer error

Resources

Accounts

The connected accounts in the key’s workspace, plus the workspaces you belong to. Call accounts 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.

Platform options

Per-network settings for POST /posts — YouTube title & description, TikTok privacy, Instagram Reel settings — plus a full multi-platform video example.

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"
  }'