# Lowtato API

> Social media automation API for AI agents. Schedule, publish, and analyze posts across 9 platforms (Twitter, Instagram, LinkedIn, TikTok, Facebook, Threads, Bluesky, YouTube, Pinterest). One API key, zero browser required.

## Base URL

https://www.lowtato.com

## Authentication

Header: `x-api-key: lt_live_xxx`
Alternative: `Authorization: Bearer lt_live_xxx`
Get your key from: https://www.lowtato.com/settings

API access requires a paid plan (Starter+). A Free-tier key returns HTTP 402 with error.code "api_access_not_in_plan".
Keys may carry scopes (posts:read, posts:write, accounts:read, accounts:write, analytics:read, ai:generate, webhooks:write); a key with NO scopes has full access. A request with a key that lacks the required scope returns HTTP 403 with error.code "missing_scope".

## Errors

All errors use one envelope: { "error": { "code": "<machine_code>", "message": "<human readable>", "details?": <any> } }.
Common codes: unauthorized (401), payment_required / api_access_not_in_plan / insufficient_credits (402), forbidden / missing_scope (403), not_found (404), validation_error / invalid_json (400), rate_limited (429), internal_error (500).
Rate limits: read 60/min, write 30/min (per key owner). 429 responses include Retry-After and X-RateLimit-Limit/Remaining/Reset headers; successful list/read responses also carry the X-RateLimit-* headers.

## Field naming

POST /api/v1/posts accepts BOTH shapes: the nested camelCase shape { post: { accountId, content: { text, mediaUrls }, target: { targetType } }, scheduledTime } AND the flat snake_case shape used by /posts/bulk ({ content, platform, account_id, media_urls, scheduled_at }). Use whichever is convenient; nested fields win when both are present. Omit platform/targetType to publish to the account's own platform.

## Quick Start (New Account)

1. POST /api/v1/onboarding -> complete onboarding in one call (brand, platforms, schedule)
2. GET /api/v1/accounts -> get your account IDs
3. POST /api/v1/ai/generate -> generate a post with AI
4. POST /api/v1/posts -> create the post (set scheduledTime or useNextFreeSlot:true)
5. GET /api/v1/posts/{postId} -> poll until status is "published" or "failed"

## Quick Start (Existing Account)

1. GET /api/v1/accounts -> get your account IDs
2. POST /api/v1/posts -> create a post (set scheduledTime or useNextFreeSlot:true)
3. GET /api/v1/posts/{postId} -> poll until status is "published" or "failed"

## Endpoints

### System
- GET /api/health — Health check (no auth required). Returns { status: "healthy"|"degraded"|"unhealthy", timestamp, checks: { db, redis, r2, stripe } }. Add ?live for a dependency-free liveness probe. Returns HTTP 503 only when the database is down.

### Accounts
- GET /api/v1/accounts — List all connected social media accounts. Returns { accounts: [{ id, platform, username, fullname, profile_image_url, is_active }] }.
- GET /api/v1/accounts/{accountId}/subaccounts — List subaccounts (Facebook Pages, LinkedIn company pages). Returns { subaccounts: [{ id, external_id, name, type }] }.
- POST /api/v1/accounts/connect — Connect a social account via OAuth tokens. Body: { platform, access_token, platform_user_id, refresh_token?, platform_username? }. Returns { id, platform, username, connected }.

### Posts
- POST /api/v1/posts — Create a post. Body (nested): { post: { accountId, content: { text, mediaUrls?, platform? }, target?: { targetType } }, scheduledTime?, useNextFreeSlot? }. Also accepts the flat shape { content, platform?, account_id, media_urls?, scheduled_at? }. Omit target/platform to use the account's own platform. Returns { id, status }. Pass an `Idempotency-Key` header to make retries safe — a repeat within 5 minutes returns the original post (HTTP 200) instead of creating a duplicate.
- GET /api/v1/posts/{postId} — Get post details. Returns { id, status, content_text, target_type, social_account_id, media_urls, public_url, error_message, scheduled_time, published_at }.
- POST /api/v1/posts/{postId}/publish — Immediately publish a draft or scheduled post. Returns { status: "published", public_url }.

### Schedules
- GET /api/v1/schedules — List scheduled posts. Query: ?limit=20 (max 100) &offset=0. Returns { scheduledPosts: [{ id, content_text, target_type, scheduled_time, status }], meta: { limit, offset, count, has_more } }.
- GET /api/v1/schedules/{scheduleId} — Get scheduled post details. Returns full post object.
- PATCH /api/v1/schedules/{scheduleId} — Update scheduled post. Body: { content_text?, scheduled_time? }.
- DELETE /api/v1/schedules/{scheduleId} — Delete a scheduled post. Returns { deleted: true }.

### Schedule Slots
- GET /api/v1/schedule/slots — List recurring time slots. Returns { slots: [{ id, day, hour, minute, selected_targets }] }. Day: 0=Sunday, 6=Saturday.
- POST /api/v1/schedule/slots — Create slots. Body: { slots: [{ day, hour, minute, selectedTargets? }] }. Returns { created: N }.
- POST /api/v1/schedule/auto-configure — Auto-generate optimal posting schedule. Body: { platforms: ["twitter", "linkedin"], posts_per_day: 2, timezone: "America/New_York", include_weekends?: false }. Replaces existing slots. Returns { configured, slots_created, slots }.

### Sources (AI Content Extraction)
- POST /api/v1/sources — Submit a URL or text for AI extraction. Body: { sourceType: "article"|"youtube"|"tiktok"|"twitter"|"pdf"|"text"|"audio"|"perplexity-query", url? (required for article/youtube/tiktok/twitter/pdf), text? (required for text/audio/perplexity-query), customInstructions? }. Returns { id, status: "queued" }.
- GET /api/v1/sources/{sourceId} — Poll extraction status. Status: queued -> processing -> ready | failed. When ready: { extracted_title, extracted_content }.

### Media
- POST /api/v1/media/upload — Upload image/video with your API key via multipart/form-data (field: "file") or JSON with base64 (fields: data, mime_type). Returns { id, url, mime_type, size }. Supported: JPEG, PNG, GIF, WebP, MP4, WebM. Use the returned `url` in a post's mediaUrls/media_urls. (This is the API-key media endpoint; /api/upload is a dashboard-session-only endpoint and is NOT usable with an API key.)

### Marketplace
- GET /api/v1/marketplace — Browse available pre-configured social accounts. Query: ?platform=twitter. Returns { accounts: [{ id, platform, username_masked, price_cents, price_display }], count }.
- POST /api/v1/marketplace/purchase — Purchase a social account. Body: { account_id, auto_connect? }. Pays with credits or card. Returns { account: { id, platform, username, email, password, totp_secret }, paid_with, connected, social_account_id? }.

### Profile
- GET /api/v1/profile — Get current user profile. Returns { id, email, display_name, plan, credits_balance, credits_monthly_allocation, timezone, language, onboarding_completed, account_count, created_at }.
- PATCH /api/v1/profile — Update profile. Body: { display_name?, timezone?, notification_preferences?: { email_post_published?, email_post_failed?, email_credits_low?, email_weekly_report? } }. Returns { updated: true }.

### Brand Kit
- GET /api/v1/brand-kit — Get brand settings. Returns { brand_name, brand_color, tone, topics, logo_url, website, what_do_you_do, who_do_you_help, language }.
- PUT /api/v1/brand-kit — Update brand settings. Body: { brand_name?, brand_color?: "#8FE000", tone?: "professional", topics?: ["e-commerce"], logo_url?, website?, what_do_you_do?, who_do_you_help?, language? }. Returns { updated: true }.

### Onboarding
- POST /api/v1/onboarding — Complete onboarding in one call (replaces 5-step wizard). Body: { brand_name, platforms: ["twitter", "linkedin"], timezone?: "America/New_York", posting_frequency?: "daily", topics?: [...], what_do_you_do?, who_do_you_help?, user_type?: "solo_creator"|"marketing_team"|"agency" }. Returns { completed, brand_name, platforms, timezone, schedule_slots_created }.

### Analytics
- GET /api/v1/analytics/summary — Aggregated stats across all accounts. Query: ?period=7d|30d|90d. Returns { total_posts, total_engagement, posts_this_week, top_platform, best_posting_time, engagement_trend, period, platform_breakdown }.

### AI Content Generation
- POST /api/v1/ai/generate — Generate post content via AI. Body: { topic, platform, tone?, include_hashtags?: true, custom_instructions? }. Returns { content, hashtags, character_count, platform, credits_used }. Costs 3 credits.

### Bulk Operations
- POST /api/v1/posts/bulk — Create multiple posts at once (max 50). Body: { posts: [{ content, platforms: ["twitter"], account_id?, scheduled_at?, media_urls? }] }. Returns { created, failed, posts: [{ id, platform, status }], errors? }.

### Credits
- GET /api/v1/credits — Check balance and usage. Returns { balance, used_this_month, plan_limit, plan, resets_at }.

### Webhooks
- POST /api/v1/webhooks — Register a webhook. Body: { url (HTTPS), events: ["post.published", "post.failed", "post.scheduled", "account.connected", "account.disconnected", "credits.low", "schedule.published"] }. Returns { id, url, events, active, secret, created_at }.
- GET /api/v1/webhooks — List all registered webhooks. Returns { webhooks: [{ id, url, events, is_active, created_at }] }.
- GET /api/v1/webhooks/{webhookId} — Get a single webhook by ID.
- PUT /api/v1/webhooks/{webhookId} — Update webhook. Body: { url?, events?, is_active? }. Returns updated webhook.
- DELETE /api/v1/webhooks — Delete a webhook. Body: { id }. Returns { deleted: true }.

## Post Status Lifecycle

draft -> scheduled -> publishing -> published (check public_url)
                                 -> failed (check error_message)

## Rate Limits

- GET: 60 req / 60s
- POST/PATCH/DELETE: 30 req / 60s
- Upload: 10 req / 60s
- 429 response includes retryAfter (seconds)

## Error Format

All errors: { "error": "description" }
Rate limits: { "error": "Rate limit exceeded", "retryAfter": 12 }

## Supported Platforms

twitter, instagram, linkedin, tiktok, facebook, threads, bluesky, youtube, pinterest

## OpenAPI Spec

https://www.lowtato.com/openapi.json

## Agent Discovery

- Agent Card: https://www.lowtato.com/.well-known/agents.json
- OpenAPI (well-known): https://www.lowtato.com/.well-known/openapi.json
- Pricing (machine-readable): https://www.lowtato.com/pricing.json
- Sitemap: https://www.lowtato.com/sitemap.xml

## MCP Server

An MCP server is available at @lowtato/mcp-server (npm). Tools: list_accounts, create_post, publish_post, browse_marketplace, purchase_account.

Configuration:
```json
{
  "mcpServers": {
    "lowtato": {
      "command": "npx",
      "args": ["@lowtato/mcp-server"],
      "env": { "LOWTATO_API_KEY": "lt_live_xxx" }
    }
  }
}
```

## Marketplace

Buy pre-configured social accounts (Twitter, LinkedIn, Instagram, etc.) with instant delivery. Prices range $3-$10 per account, paid with credits.

- Browse: GET /api/v1/marketplace?platform=twitter
- Purchase: POST /api/v1/marketplace/purchase { account_id, auto_connect }

## Pricing

- Free: 3 accounts, 30 AI credits
- Starter ($13/mo): 20 accounts, 200 credits, API access
- Creator ($26/mo): 50 accounts, 500 credits
- Agency ($49/mo): unlimited accounts, 1500 credits

## Credit Costs

- Publish post: 0 credits
- AI generate post: 0.5 credits
- AI generate image: 2.0 credits
- Analytics fetch: 0 credits
- Purchase account: varies by platform