TimedPost API

Programmatically create, schedule, and manage posts across all your connected social platforms.

v1https://app.timedpost.com/api/v1

Quick Start

Create an API key from your Settings page or via POST /v1/keys
Add the key to your requests as a Bearer token
Start creating posts!

Example: Create a post

curl -X POST https://app.timedpost.com/api/v1/posts \
  -H "Authorization: Bearer tp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["x", "tiktok"],
    "content": {
      "text": "Hello from the API!",
      "media_urls": ["https://example.com/video.mp4"],
      "hashtags": ["#automation", "#api"]
    }
  }'

Authentication

All API requests require authentication via a Bearer token in the Authorization header.

Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keep your keys safe. API keys grant full access to your account. Never expose them in client-side code, public repos, or logs. If a key is compromised, revoke it immediately.

Key types:

tp_live_ — Production keys. Actions are real.
tp_test_ — Test keys. Posts are validated but not published.

Rate Limits

API requests are rate limited per key at 100 requests per hour (default). Rate limit info is returned in response headers:

Header	Description
X-RateLimit-Limit	Max requests per hour
X-RateLimit-Remaining	Requests remaining in window
X-RateLimit-Reset	ISO timestamp when window resets

When rate limited, you'll receive a 429 response with a Retry-After header (in seconds).

Errors

All errors follow a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

Status	Code	Meaning
400	validation_error	Invalid request body or parameters
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks required permission
404	not_found	Resource not found
409	invalid_state	Action not allowed for current state
429	rate_limited	Too many requests
500	server_error	Internal server error

Posts

Create, list, check status, and cancel posts.

Use Idempotency-Key on POST requests from agents. Reusing the same key with the same body returns the original post; reusing it with a different body returns 409 idempotency_conflict.

Post Lifecycle

queued→publishing→published

scheduled→queued→publishing→published

queued — Immediate publish, waiting for cron pickup
scheduled — Scheduled for future publish_at time
publishing — Currently being published to platforms
published — Successfully published to all platforms
partial — Published to some platforms, failed on others
failed — Failed on all platforms
cancelled — Cancelled before publishing

Accounts

List your connected social media accounts.

Platforms

Get available platforms and their supported features.

Webhooks

Receive real-time notifications when posts are published or fail. Webhook payloads are signed with HMAC-SHA256 using your webhook secret.

Verifying Signatures

Every webhook request includes an X-TimedPost-Signature header. Verify it to ensure the request came from TimedPost:

Node.js verification

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Events

Event	Fired when
post.published	Post successfully published to platforms
post.failed	Post failed on all platforms
post.cancelled	Post was cancelled before publishing

Example payload

{
  "event": "post.published",
  "data": {
    "post_id": "550e8400-...",
    "platforms": ["x", "tiktok"],
    "status": "published",
    "published_at": "2026-03-08T12:01:00Z"
  },
  "timestamp": "2026-03-08T12:01:01Z"
}

Auto-disable: Webhooks are automatically disabled after 10 consecutive delivery failures. Re-enable via PATCH with {"active": true}.

API Keys

Manage API keys. These endpoints require session authentication (logged in via the app), not API key auth.

Need help? Contact us at [email protected]