# LumiPath Public API > LumiPath is a multi-platform social-content tool (publish, localize/dub, moderate comments, read analytics, automate posting) for TikTok, YouTube, Instagram, Facebook, Threads, X, Reddit, and Pinterest. This file describes the public HTTP API for programmatic/agent use. Base URL: `https://app.lumipath.cn`. Public v1 HTTP endpoints live under `/api/v1/`; the MCP transport also exposes project tools backed by internal project endpoints. ## Authentication Send your per-user API key as a Bearer token on every request: ``` Authorization: Bearer lumi_xxxxxxxx ``` Keys are generated in the dashboard at **Settings → API Keys** (`/dashboard/api-keys`) and start with `lumi_`. (Note: the `X-Api-Key` header is a *separate* internal service-token mechanism — it is NOT for per-user keys.) Every call is scoped to the key's owner — you can only act on **Connections** (linked social accounts) owned by that user. A foreign or non-existent id returns `404` and does not reveal whether it exists. Browser callers may use a NextAuth session cookie instead. There is no role requirement. A `connectionId` is the MongoDB ObjectId of a linked social account. The **platform is inferred** from the `connectionId` — you never pass a `platform` param. List your connections with `GET /api/v1/connections`. ## Response & error contract Success (HTTP 200): ```json { "success": true, "data": } ``` Error (non-2xx): ```json { "error": "MACHINE_CODE", "message": "english, for debugging only" } ``` Branch on the `error` machine code + HTTP status, not on `message`. Common codes: `VALIDATION_FAILED` (400), `UNSUPPORTED_PLATFORM` (400), `Unauthorized` (401), `ACCOUNT_UNLINKED` (401, connection has no token), `TOKEN_EXPIRED` (401, re-authorize the connection), `NOT_FOUND` (404), `RATE_LIMITED` (429, with `Retry-After`), `UPSTREAM_ERROR` (502, platform API failed — retryable), `INTERNAL_ERROR` (500). Automation also uses `UPGRADE_REQUIRED`/`QUOTA_EXCEEDED` (402), `FEATURE_DISABLED`, `NOT_READY`, `ALREADY_DISCARDED`. **Supported platforms for comments:** TikTok, YouTube, Instagram, Facebook, Threads, X, and LinkedIn (company pages only). Pinterest and Reddit return `UNSUPPORTED_PLATFORM`. **Insights** cover TikTok, YouTube, Instagram, Facebook, Threads, and Pinterest; X, Reddit, and LinkedIn return `UNSUPPORTED_PLATFORM`. ## Comments - `GET /api/v1/comments` — Comment inbox for a connection (aggregated across its posts). Query: `connectionId` (required), `videoId` (optional, filter to one post; Threads = media id), `page` (default 1), `limit` (1–100, default 10); X only: `sinceId` (previous `newestId`, returns only newer replies), `untilId` (page back with `oldestId` when `hasMore`) and `startTime` (ISO, used without `sinceId`). Returns normalized `{ comments: BaseComment[], pagination: { total, page, limit, totalPages }, newestId?, hasMore?, oldestId?, skipped? }` — `skipped: "NO_RECENT_X_VIDEO"` means the account-wide X inbox was not fetched because the connection published no X video through LumiPath in the last 7 days. `BaseComment` = `{ id, platform, author, username?, authorAvatar?, content, timestamp (ISO), likes, isPinned?, videoId?, videoTitle?, videoUrl?, repliesCount?, replies?: BaseComment[], ... }`. - `POST /api/v1/comments/reply` — Reply to a comment. JSON body: `{ connectionId, commentId, text, videoId? }`. `videoId` is **required for TikTok**, ignored elsewhere. Returns `{ id, platform }` (the new reply's id). ## Insights - `GET /api/v1/insights` — Account-level insights for a connection (followers/views/likes totals). Query: `connectionId`. Per-platform free-form `data` (keys vary by platform). Covers TikTok, YouTube, Instagram, Facebook, Threads, and Pinterest. Pinterest returns profile counts plus a rolling 30-day organic summary (`impressions`, `engagements`, `saves`, `pinClicks`, `outboundClicks`). Facebook returns `page` (id, name, fans, followers, pictureUrl) plus `insights` — a rolling 28-day Page Insights block (`pageViews`, `pageFollows`, `pagePostEngagements`, `pageVideoViews`); each is `null` when the Page has no data for that window or the metric is unavailable on the token, so `null` = unavailable and `0` = a real zero. - `GET /api/v1/insights/post` — Per-post insights, normalized across all 6 platforms above. Query: `connectionId`, `postId` (native post/video/media id). Returns a `PostInsight`: `{ platform, postId, views, likes, comments, shares, saves, reach, reposts, quotes, mediaUrl }`. Every field is always present; a metric a platform doesn't supply is `null` (never `0`), so you can tell "zero" from "unsupported". Pinterest maps lifetime impressions to `views`, plus lifetime comments and saves. Facebook fields depend on the id shape (Graph exposes different metrics per node): a **video id** — what `/api/v1/posts` returns for Facebook — gives `views` (Reels plays), `reach`, `likes`, `comments`, with `shares` `null`; a **Page post id** (`_`) gives `views`, `likes`, `comments`, `shares`, with `reach` `null`. `saves` is always `null`. ## Platform read (CLI) Discovery primitives over a connection's natively-published posts and profile, normalized across **8 platforms** (TikTok, YouTube, Instagram, Facebook, Threads, X, Reddit, Pinterest). A Pinterest connection represents one Board; `/posts` is scoped to owned Pins on that Board, and detail reads reject Pins from other Boards. `/posts`, `/posts/{postId}` and `/connections/{id}` also cover LinkedIn company pages (profile gives `followers` + page description as `bio`; `postId` = post URN `urn:li:share:…`/`urn:li:ugcPost:…`; `stats` are lifetime organic counts, `null` when the page role can't read statistics; poll at most every few hours — LinkedIn's daily quota is small). Every normalized field is always present; `null` = the platform doesn't supply it (never `0`/`""`). `PostDetail.mediaUrls` is `[]` (never `null`) when empty. - `GET /api/v1/posts` — List a connection's natively-published posts. Query: `connectionId` (required), `page` (default 1, advisory), `limit` (1–50, default 20), `cursor` (opaque, from a prior `pagination.nextCursor`). Returns `{ posts: PostSummary[], pagination: { nextCursor, hasMore, page, limit } }`. `PostSummary` = `{ postId, platform, type ("video"|"image"|"text"|"carousel"|"unknown"), title, caption, url, thumbnailUrl, publishedAt (ISO), stats: { views, likes, comments, shares } }`. Paginate by echoing `pagination.nextCursor` back as `?cursor=` (forward-only; the opaque cursor is platform-guarded — never reuse one connection's cursor on another). - `GET /api/v1/posts/{postId}` — Single post detail. Path: `postId` (native id). Query: `connectionId`. Returns a `PostDetail` = `PostSummary` + `{ description, mediaUrls: string[], durationSec, visibility }`. Unknown `postId` on the account → `NOT_FOUND`. `visibility` is YouTube-only; `durationSec` is null for non-video. X/Reddit verify the post's author matches the account (never leak a foreign post). - `GET /api/v1/connections/{id}` — Connection profile (richer than the `/connections` list item). Path: `id` = connectionId. Returns a `Profile` = `{ connectionId, platform, username, displayName, avatarUrl, bio, followers, following, postsCount }`. Reddit's `followers`/`following`/`postsCount` are always null (karma is not substituted). ## Publishing & content - `POST /api/v1/social-posts` — All-in-one publish in a single request. `contentType: "VIDEO"` (→ TikTok, YouTube, Instagram, Threads, X, Pinterest, LinkedIn, Facebook; uses `mediaUrls[0]`) or `"IMAGE"` (image post / 图文 → Instagram, Threads, TikTok, X, Pinterest, LinkedIn, Facebook; `mediaUrls` = 1..35 image URLs, single-vs-carousel decided by count; YouTube rejected for IMAGE; per-platform image limits X≤4 / IG≤10 / Threads≤20 / TikTok≤35 / Pinterest≤1 / LinkedIn≤20 / Facebook≤10). Facebook publishes to a linked Page (feed video / photo post); LinkedIn publishes to a linked company page only. `contentType: "DOCUMENT"` is a LinkedIn-only PDF document (swipeable carousel) post: `platforms` must be exactly `["LINKEDIN"]`, `mediaUrls` exactly one PDF URL on an allow-listed host (`*.lumipath.cn` / `*.aliyuncs.com`; ≤100 MB, ≤300 pages), and `advanceConfig.linkedin.documentTitle` is required; it returns `processing` — poll `/social-posts/status` for the URN. Body includes `platforms[]`, `text`, `mediaUrls[]`, and per-platform `*ConnectionIds`/`*AccountNames`/`*Configs`, plus an optional top-level `advanceConfig` object (keyed by platform) for platform-native advanced settings — e.g. `youtube.categoryId`/`tags`/`thumbnailUrl`, `tiktok.isAigc`/`brandContentToggle` plus VIDEO cover via `tiktok.customThumbnailUrl` (custom cover image URL, allow-listed host) or `tiktok.videoCoverTimestampMs` (cover frame offset, default 1000), `instagram.locationId`/`userTags` plus Reels VIDEO cover via `instagram.coverUrl`, `threads.replyControl`, `x.replySettings`, `pinterest.link`, `facebook.firstComment`/`coverUrl` (each a strict per-platform allow-list; unknown keys → 400). Pinterest requires `pinterestConnectionIds` (each connection is bound to a single board server-side; there is no client-supplied `boardId`) and an optional `pinterestConfigs[]` with `{ connectionId, description? }`; API-key callers are supported for user-owned Pinterest connections, while service-token callers are rejected. Returns per-account `results` (each `success`/`processing`/`failed`), and every result item now carries a `jobId` — an internal tracking id (additive; existing `publishId`/`mediaId` fields are unchanged). Pass those `jobId`s to `POST /api/v1/social-posts/status` to query the final post status/URL. Pass optional `scheduleAt` (ISO 8601 **with** a timezone offset; 1 min–365 days out) to schedule instead of publishing now — the response becomes `{ success: true, scheduled: true, scheduleJobId, scheduledAt }` (no `results`) and a background worker fires it at that time (query with `/social-posts/schedule/status`, cancel with `/social-posts/schedule/cancel`). Optional `Idempotency-Key` header (1–200 chars `[A-Za-z0-9:_.-]`, kept 7 days): re-sending the same body with the same key returns the first response (`Idempotent-Replayed: true`) instead of publishing again; still running / ended in 5xx → `409 IDEMPOTENCY_IN_PROGRESS`; different body → `422 IDEMPOTENCY_KEY_REUSED`. Full schema: `/api/v1/social-posts` docs below. - `POST /api/v1/social-posts/schedule/status` — Status of scheduled posts. Body `{ scheduleJobIds?: string[] }` (max 100) — pass the `scheduleJobId`s from the schedule response to resolve specific posts, or omit them to list all your pending scheduled posts. Auth: session, user API key, or service token (`x-user-id`). Returns `{ items }`, each `{ scheduleJobId, status, scheduledAt?, platforms?, contentType?, publishJobIds?, error? }` with `status` ∈ `scheduled | firing | fired | failed | not_found`. A fire more than 2 h after `scheduledAt` is skipped (`failed`, `error` starts with `SCHEDULE_MISSED:`; nothing published). Once `fired`, `publishJobIds` are the per-account ids to poll on `/social-posts/status`. Foreign/unknown ids → `not_found`. - `POST /api/v1/social-posts/schedule/cancel` — Cancel a pending scheduled post by `{ scheduleJobId }`. Owner-scoped: foreign/unknown/already-fired → 404, mid-fire → 409. Returns `{ success: true, cancelled: true }`. - `POST /api/v1/social-posts/status` — Query publish status by `jobId`. Auth: session, user API key, or service token (service-token callers pass `x-user-id`). Body `{ jobIds: string[] }` (0..100 ids). Returns `{ results }` grouped by platform, each item `{ connectionId?, jobId, status, postId?, postUrl?, error?, errorCode?, stage? }` where `status` ∈ `success | processing | failed | not_found`. TikTok jobs are live-polled against the platform; other platforms report the state their background publish last wrote. `stage` ∈ `preparing | uploading | creating` — `creating` means the create call was sent and the post may exist even if the job failed. A background publish with no progress for 30–60 min is failed by a watchdog with `errorCode: "PUBLISH_STALLED"` (a timed-out platform call: `PUBLISH_TIMEOUT`); X/Pinterest-IMAGE/LinkedIn-IMAGE/Facebook-IMAGE are terminal. Unknown/foreign/malformed ids return `not_found` under an `UNKNOWN` group (never leaks another tenant's data). Always HTTP 200 for a well-formed body; one bad id never fails the batch. - `GET /api/v1/videos` — List your uploaded videos. Query: `page`, `limit`, `search`. - `POST /api/v1/videos` — Register a video by URL. Body: `{ url, filename, title }`. - `POST /api/v1/videos/upload` — Upload a video, image, **or document** and get back `{ url, vid, mediaType }` (bare, no envelope; `mediaType` is `"video"`, `"image"`, or `"document"`). Two request shapes: (a) **multipart/form-data** with a `file` field (media bytes) + optional `filename`/`title` — the bytes are stored to OSS; or (b) **application/json** `{ url, filename?, title? }` — the server downloads the remote media and re-hosts it on OSS. Video formats: `.mp4 .avi .mov .mkv .webm .flv .wmv`; image formats: `.jpg .jpeg .png .webp` (images max 8 MB); document formats: `.pdf .docx .md .markdown` (max 100 MB, content byte-checked, stored per format under OSS `documents/pdf|docx|markdown/`; a returned PDF `url` can be used directly for LinkedIn `contentType: "DOCUMENT"` posts). Videos are subject to your daily upload quota (`403 upload_limit_reached` when exceeded); images and documents are not. Image assets are excluded from `GET /api/v1/videos`; use the returned `url` in `social-posts` `mediaUrls`. - `POST /api/v1/repurpose` — Localize/dub/repurpose a source video. Body: `{ sourceUrl, sourceLang, targetLang, dubbing?, dubbingVoiceId?, backgroundMusic?, subtitle?, ocr?, autoPublish?, title?, durationSeconds?, ... }`. - `GET /api/v1/localization` — List localization tasks. Query: `page`, `limit`, `vid`, `taskId`, `status`. - `POST /api/v1/localization` — Create a localization task. Body: `{ localProjectId, aiConfig, durationSeconds }`. - `GET /api/v1/tts` — List available TTS (text-to-speech) voices. - `GET /api/v1/connections` — List the caller's linked social accounts. Query: `platform` (optional filter). Each item = `{ connectionId, platform, username, displayName, avatarUrl, status, createdAt, profileUrl, reauthBy, renewsOnUse, health }`; `profileUrl` is the account's public homepage URL (string-concatenated, `null` when not derivable). `health` is `null` when healthy, otherwise `{ state: "suspended"|"locked"|"restricted", reason, since }` — while set, publishes to that connection fail with `errorCode: "ACCOUNT_UNHEALTHY"` without reaching the platform. Use the returned ids as `connectionId` everywhere. - `POST /api/v1/connections/{id}/health/clear` — Mark a suspended / locked / restricted connection as handled after fixing it on the platform; publishing resumes immediately. 404 if the connection is not yours. ## Automation Schedule and manage automated posting strategies and their tasks. All routes are caller-scoped to the API key's owner. - `GET /api/v1/automation/strategies` — List strategies. `POST` — create/upsert a strategy (VIP-gated; 10/hour). - `GET|PATCH|DELETE /api/v1/automation/strategies/{id}` — Read / update / delete a strategy. - `POST /api/v1/automation/strategies/{id}/execute` — Run now. `.../pause` · `.../resume` — toggle scheduling. - `GET /api/v1/automation/tasks` — List tasks. Query: `strategy_id`, `username`, `platform`, `step`, `status`, `from`, `to`, `page`, `limit`. - `POST /api/v1/automation/tasks/{id}/confirm` · `/retry` · `/reprocess` · `/cancel` · `/title-description` — Task lifecycle actions. - `GET /api/v1/automation/quota` — Current automation quota usage. - `GET /api/v1/automation/dispatch-failures` — Recent dispatch failures. - `POST /api/v1/automation/ai-strategy/drafts` — Create an AI-generated strategy draft (rate-limited 10/day and 5/hour per user). `GET /.../{draftId}` read · `POST /.../{draftId}/regenerate` · `POST /.../{draftId}/discard`. ## Meta Ads - `GET /api/v1/meta/ads-token` — Facebook token with whatever ads permissions were granted (`ads_management`/`ads_read`), for injecting into a Meta Ads MCP/agent. No query params; scoped to the caller's own LumiPath account. Persisted from the dedicated ads entry (`POST`/`DELETE /api/link/facebook/ads`) — independent of whatever Facebook Pages the same LumiPath user has linked from the social page. Returns `{ accessToken, expiresAt (ISO 8601 or null if it never expires), scopes: string[], tokenType: "user"|"system_user", userId, userName, businessId }`. `tokenType: "user"` (personal long-lived token: `userId`/`userName` set, `businessId` null) is the current default (2026-08-23 product decision — ads reverted to a personal token); `tokenType: "system_user"` (a BISU token scoped to a Business Portfolio: `businessId` set, `userId`/`userName` null — BISU has no user identity, and it defaults to never expiring) is kept behind an env switch, not currently the default. `404 META_ADS_NOT_CONNECTED` if ads was never authorized in LumiPath, or was authorized without ads permissions; `401 TOKEN_EXPIRED` if the stored token has since expired — either way, re-authorize from LumiPath's 广告 (ads) page. Requires the Meta App's Facebook Login for Business config used by the ads entry to have `ads_management` / `ads_read` / `business_management` enabled (and, only when the system-user switch is on, `response_type=code` — BISU only supports the code flow). ## TikTok Ads Two different TikTok ads tokens, for two different transports. They are **not** interchangeable: the MCP token is scoped to TikTok's Ads MCP server, and calling `https://business-api.tiktok.com/open_api/v1.3/...` with it returns `code: 40105` ("Access token is incorrect or has been revoked"). A user may have authorized either, both, or neither. - `GET /api/v1/tiktok/ads-token` — TikTok **Ads MCP** access token (scope `mcp:tt4b`), for connecting TikTok's official Ads MCP server. No query params; scoped to the caller's own LumiPath account. Persisted from the dedicated TikTok ads entry (`POST`/`DELETE /api/link/tiktok/mcp`), which registers a public OAuth client via Dynamic Client Registration and runs a PKCE authorization-code flow. Returns `{ accessToken, expiresAt (ISO 8601 or null if it never expires), scope, serverUrl }`. Refreshed server-side when expired or close to expiring. `404 TIKTOK_MCP_NOT_CONNECTED` if TikTok Ads MCP was never authorized in LumiPath, or was disconnected; `401 TOKEN_EXPIRED` if the stored token expired and could not be refreshed — re-authorize from LumiPath's 广告 (ads) page. - `GET /api/v1/tiktok/marketing-token` — TikTok **Marketing API** (Business API) access token, for calling `https://business-api.tiktok.com/open_api/v1.3/...` directly (send it as the `Access-Token` request header). No query params; scoped to the caller's own LumiPath account. Persisted from the TikTok Marketing entry (`POST`/`DELETE /api/link/tiktok/marketing`), which runs the TikTok for Business authorization-code flow against a developer app holding Marketing API scopes (ad account information, campaign/ad group/ad, ad insight report). Returns `{ accessToken, advertiserIds: string[], scope: number[], authorizedAt (ISO 8601 or null), appId }`. `advertiserIds` are the ad accounts the user granted on TikTok's authorization page (possibly empty); `scope` is TikTok's numeric permission list, passed through as-is. The token is long-lived — **no refresh token and no expiry** — and stays valid until the user revokes it in TikTok Business Center or re-authorizes, so there is no `TOKEN_EXPIRED` on this route; a revoked token only surfaces as `40105` from TikTok itself. `404 TIKTOK_MARKETING_NOT_CONNECTED` if it was never authorized in LumiPath, or was disconnected — re-authorize from LumiPath's 广告 (ads) page. Uses the same TikTok for Business developer app as content publishing (`TIKTOK_CLIENT_KEY`/`TIKTOK_CLIENT_SECRET`; `TIKTOK_MARKETING_APP_ID`/`TIKTOK_MARKETING_APP_SECRET` are optional overrides if the apps are ever split) but its **own dedicated redirect URI** `https://app.lumipath.cn/api/link/tiktok/marketing/callback`, registered under the Marketing API product's **Advertiser redirect URL** field. Marketing API 的广告主授权回调在开发者后台是单独一栏(Advertiser redirect URL),和社媒登录不共用 —— 2026-09-23 实测共用被 TikTok 拒。Once that URL is registered, the only remaining step is authorizing once from LumiPath's 广告 (ads) page. ### Ads authorization in a popup - `POST /api/v1/ads/link-sessions` — issue a one-time link so a Lumi workspace can run the Facebook / TikTok ads authorization in a popup without the user opening LumiPath. User API key only. Body `{ platform: "meta"|"tiktok", openerOrigin }`; `openerOrigin` must be a bare `https://` origin on the allowlist (`ADS_LINK_OPENER_ORIGINS`, default `https://*.agent.lumipath.cn`), else `400 VALIDATION_FAILED`. Same beta gate as the ads page (`403 FORBIDDEN` otherwise); 10 per minute per user. Returns `{ linkId, url, expiresAt }`: `url` is valid for 10 minutes and opens once; the resulting token is stored for the API key's user, whoever is logged in to LumiPath in that browser. Open it from a page on `openerOrigin` (e.g. `window.open` then set `location`): the link checks that the `Referer` origin equals `openerOrigin` and refuses forwarded / previewed opens without consuming the link, so don't use `rel="noreferrer"` or `Referrer-Policy: no-referrer` on that page. When done, the popup posts `{ type: "lumipath:ads-link", linkId, platform, ok, error }` to `openerOrigin` and closes; the message never carries a token — fetch it with the `ads-token` routes above. - `GET /api/v1/ads/link-sessions/{linkId}` — status of that link, for polling (the popup's `window.opener` may be gone after visiting the provider's pages). User API key only; your own links only, else `404 NOT_FOUND`. Returns `{ status: "pending"|"opened"|"completed"|"failed", error, platform }`; `error` is one of `denied`, `expired`, `exchange_failed`, `no_business`, `csrf_failed`, `missing_code`, or `null`. A link past its expiry that never finished reports `failed` / `expired`. ## MCP server - `GET|POST|DELETE /api/v1/public/{transport}` — Model Context Protocol (MCP) endpoint. Authenticate with `Authorization: Bearer ` (the same key, `lumi_…`). Exposes a subset of the above as MCP tools (connections, social-posts, videos, localization, tts, insights, repurpose) plus project tools (`list_projects`, `create_project`, `get_project`, `update_project`, `delete_project`) for AI agents/clients. ## Documentation This file is a terse index. The authoritative references are: - **Machine-readable contract (OpenAPI 3.1):** `GET https://app.lumipath.cn/api/v1/openapi.json` — the generated spec (every endpoint, parameter, request/response shape, error code). No auth required to read it; ingest or codegen a client from this. The MCP transport is intentionally excluded. - **Full prose reference:** `GET https://app.lumipath.cn/docs/llms-full.txt` — the single consolidated guide: quickstart mental model, the two response envelopes (`{success,data}` vs bare object), the machine-code error table, rate-limit/retry rules, every endpoint grouped by tag, publishing behavior (TikTok synchronous / YouTube fire-and-forget / Instagram, Threads & Pinterest background processing), and the security note (keys are full-access). ## Notes - Request/response only — no webhooks. Poll where you need freshness. - Connection ids must be 24-char hex MongoDB ObjectIds; invalid format → `VALIDATION_FAILED`. - Retryable conditions: `UPSTREAM_ERROR` (502) and `TOKEN_EXPIRED` (after re-auth). `4xx` validation errors are not.