# AiVideoEditor public documentation --- --- Source: https://autoposted.buildamicrosaas.com/docs/publishing-overview Reviewed: 2026-11-10 # Publishing overview AiVideoEditor is a social publishing workspace. It manages drafts, scheduling, connected social accounts, and per-destination delivery outcomes through a shared workspace, a REST API under `/api/v1`, and a local stdio MCP adapter. ## Offer facts - Social Posting starts with a 14-day free trial: two connected accounts, unlimited posting, no credit card required. It is $19/month for three accounts. - AI editing includes captions, pause and filler removal, audio cleanup, B-roll, text callouts, full videos and short clips, clean exports and publishing. - Creator is $29/month for 300 processing minutes and videos up to 30 minutes. Pro is $49/month for 900 minutes and videos up to 60 minutes. Studio is $99/month for 2,400 minutes and videos up to 120 minutes. - Try AI editing with 10 free processing minutes. Free downloads carry a watermark. - Usage is based on source recording minutes, not the number of exports. - Existing subscribers retain their existing contract allowances. - All prices are monthly USD. Unused allowances do not roll over. A connected account is one social account or Page, such as an Instagram account or a Facebook Page. Each brand can connect one account per network; support depends on the destination and account eligibility. See [capabilities](/docs/capabilities). ## Start free - Landing page: /en/cross-posting - Signup: /signup?intent=publishing&offer=social ## Using AiVideoEditor as an agent 1. Create a scoped product key in the workspace at /app/developers. Read [authentication](/docs/authentication) for key permissions and limits. 2. Call the REST API under `/api/v1` following the [quickstart](/docs/quickstart), or run the local stdio MCP adapter per the [MCP setup guide](/docs/mcp). Hosted MCP and OAuth are not available. 3. Connect destinations with a workspace member present. Social connections and TikTok publishing require human consent; agents cannot grant it. 4. Create and validate drafts with `POST /api/v1/posts`, then publish or schedule. A `202` response means accepted for dispatch, not confirmed publication. Observe deliveries with `GET /api/v1/posts/{id}` or customer webhooks. AiVideoEditor does not repost from source accounts automatically. Everything published is an explicit draft created in the workspace or through the API. The full endpoint and schema reference is the [API reference](/docs/api) and the machine-readable [OpenAPI specification](/docs/openapi.yaml). --- Source: https://autoposted.buildamicrosaas.com/docs/quickstart Reviewed: 2026-11-11 # AiVideoEditor API quickstart Base URL: `https:///api/v1` (local dev: `http://localhost:3006/api/v1`). ## Authentication Create a product key in **Developers** in the workspace navigation (`/app/developers`). The plaintext key (`pk_v1_…`) is shown **exactly once**; only a hash and a short prefix are stored. Send it as a bearer token: ```bash curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage ``` Keys carry explicit scopes (`accounts:read`, `media:write`, `posts:read`, `posts:write`, `posts:publish`, `usage:read`, `webhooks:manage`) and an optional account allowlist. A **draft-only** key omits `posts:publish` and therefore cannot publish, schedule, cancel or retry. Keys can never create other keys or change billing. Revoking a key **pauses its unsent jobs** as `requires_action`: nothing is deleted, and the revocation UI shows the affected pending-job count first. ## Ground rules - **Every mutation** requires an `Idempotency-Key` header. Same key + same body → the same recorded result (same delivery IDs). Same key + different body → `409 idempotency_conflict`. - Edits and scheduling require `expectedVersion`; a stale version returns `409 revision_conflict` with the current version in `error.details.currentVersion`. - `202` from publish/schedule means **accepted for dispatch**, never "published". Track outcomes with `GET /posts/{id}`, customer webhooks, or bounded polling. - Rate limits are **technical speed limits per workspace** (60/120/240 req/min by plan; `429` + `Retry-After`). There is no request or posting quota: posting is unlimited on every paid plan. - Errors use the normalized envelope: `{ error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }`. ## End-to-end: draft → validate → publish → observe The example requires Bash, `curl`, `jq`, Node 22+, an active workspace, a connected Facebook Page or LinkedIn destination, and a key with `accounts:read`, `posts:read`, `posts:write` and `posts:publish`. Set `ACCOUNT_ID` to a permitted destination from `/accounts`; check its text format support in `/capabilities`. Running the publish command posts real content. ```bash set -euo pipefail BASE="${PUBLISHER_API_URL:?Set the AiVideoEditor origin}/api/v1" AUTH="Authorization: Bearer ${PUBLISHER_KEY:?Set the product key}" JSON="Content-Type: application/json" new_key() { node -e 'console.log(require("node:crypto").randomUUID())'; } curl --fail-with-body -sS -H "$AUTH" "$BASE/accounts" curl --fail-with-body -sS -H "$AUTH" "$BASE/capabilities" : "${ACCOUNT_ID:?Choose a permitted text destination from the responses above}" # Save this key and body; reuse both if the connection fails ambiguously. CREATE_KEY=$(new_key) DRAFT_BODY=$(jq -n --arg account "$ACCOUNT_ID" '{caption:"A new update from our team.",mediaIds:[],brandFolderId:null,destinations:[{accountId:$account,format:"text"}]}') DRAFT=$(curl --fail-with-body -sS -X POST -H "$AUTH" \ -H "Idempotency-Key: $CREATE_KEY" -H "$JSON" \ "$BASE/posts" -d "$DRAFT_BODY") POST_ID=$(jq -er '.post.postId' <<<"$DRAFT") VERSION=$(jq -er '.post.version' <<<"$DRAFT") VALIDATION=$(curl --fail-with-body -sS -X POST -H "$AUTH" "$BASE/posts/$POST_ID/validate") printf '%s\n' "$VALIDATION" jq -e '.validation.valid == true' <<<"$VALIDATION" >/dev/null # 202 means accepted. Keep this key for an identical retry after a timeout. PUBLISH_KEY=$(new_key) ACCEPTED=$(curl --fail-with-body -sS -X POST -H "$AUTH" \ -H "Idempotency-Key: $PUBLISH_KEY" "$BASE/posts/$POST_ID/publish") printf '%s\n' "$ACCEPTED" curl --fail-with-body -sS -H "$AUTH" "$BASE/posts/$POST_ID" ``` For image/video destinations, [upload and finalize media](/docs/media) first, then use the returned asset IDs in `mediaIds` and an eligible destination format. Observe individual delivery IDs from the accepted response; use webhooks or a bounded status poll with backoff. A single immediate status read may still be pending. ## Schedule instead of publish Use this on a draft **instead of** the publish step above. Fetch its current version again after any edit. This computes a future instant rather than using a sample date that will expire. ```bash SCHEDULED_AT=$(node -e 'console.log(new Date(Date.now()+86400000).toISOString())') SCHEDULE_BODY=$(jq -n --arg at "$SCHEDULED_AT" --argjson version "$VERSION" \ '{scheduledAt:$at,timezone:"America/Indiana/Indianapolis",expectedVersion:$version}') SCHEDULE_KEY=$(new_key) curl --fail-with-body -sS -X POST -H "$AUTH" -H "Idempotency-Key: $SCHEDULE_KEY" \ -H "$JSON" "$BASE/posts/$POST_ID/schedule" -d "$SCHEDULE_BODY" ``` The instant must be future and within the **90-day horizon**; the UTC instant and the display timezone are stored separately. If your API key expires at or before that instant, the accepted response includes a `warnings` entry with code `key_expires_before_schedule`. The delivery remains scheduled, but it must be reviewed and resubmitted under an active principal before it can publish. The same warning is preserved when replaying the request. Cancel while safely unclaimed: ```bash curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/cancel # Already submitted? → 409 too_late_to_cancel with the real state. ``` Retry **only** a known failed destination (unknown/successful are refused): ```bash curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry ``` ## Media (direct uploads) Media bytes never pass through this API. ```bash # 1. Reserve bytes → direct instructions (presigned PUT, or multipart for large files) curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/upload-intents -d '{ "filename": "poster.jpg", "declaredMime": "image/jpeg", "declaredBytes": 1048576 }' # 2. Upload bytes DIRECTLY to the returned URL with the documented method. # 3. Finalize: the server verifies size/signature on the immutable final copy. # Send ONLY the session identity (plus part receipts for multipart uploads) #: bytes, MIME and checksum are observed server-side, never declared here. curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{ "sessionId": "…" }' # multipart: include the ETag receipt of every uploaded part. # Files at or above 50 MiB use multipart; use the returned part size and URLs. # Upload every part and retain its ETag. Small files finalize with sessionId only. # These are alternative finalization shapes, not two consecutive operations. curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{ "sessionId": "…", "multipart": { "parts": [ { "partNumber": 1, "etag": "…" } ] } }' # 4. Status/expiry only: there is no permanent public media URL curl -s -H "$AUTH" $BASE/media/$ASSET_ID ``` Files are temporary: scheduled posts keep their media through publishing, and a dynamic `deleteAfter` (or null) is always shown. Keep your originals. ## Usage `GET /usage` reports plan, connected/reserved account slots, members, storage, the 90-day horizon and rate info. Activity numbers are operational metrics only: **there is no remaining-post counter anywhere in the product**. ## Pagination List endpoints use opaque cursors: `?limit=25&cursor=`. Timestamps are UTC ISO-8601. Continue until `nextCursor` is `null`; a filtered posts page can be empty while its non-null cursor points to older records still to scan. Prefer webhooks (see [webhooks](/docs/webhooks)) or bounded polling with backoff over tight status loops. ## Limits and partial success Destination capabilities (from `GET /capabilities`) carry the strictest effective limits: app, provider, network and account. When a limit blocks a request, the error envelope is actionable: ```json { "error": { "code": "storage_limit", "message": "Active temporary media exceeds this plan's storage allowance.", "retryable": false, "requestId": "…" } } ``` `account_limit`, `seat_limit`, `storage_limit`, `subscription_inactive` and `trial_expired` are 402 responses; nothing is deleted, and drafts/queued work is preserved for after an upgrade. A publish/schedule is a batch of independent destination jobs. Partial success is normal and reported per destination: never as an atomic promise: ```json { "post": { "postId": "…", "version": 4, "status": "partially_published", "deliveries": [ { "id": "…", "accountId": "…", "network": "instagram", "state": "published", "nativePostUrl": "https://instagram.com/p/…", "unresolvedExternalOutcome": false }, { "id": "…", "accountId": "…", "network": "linkedin", "state": "reconnect_required", "nativePostUrl": null, "lastErrorCode": "reconnect_required" } ] }, "requestId": "…" } ``` Retry only the failed destination (`POST /deliveries/{id}/retry`); successful destinations are never re-sent. Consent/reconnection requirements return `requires_action` with safe instructions, never a secret. ## Full reference For TikTok, `GET /accounts/{id}/tiktok/settings` returns the connected creator's current privacy choices, interaction permissions, duration limit and publishing mode availability. It requires `accounts:read` and honors the key allowlist. Saving a draft or reading these settings does not supply consent. A publish/schedule lacking current human confirmation returns HTTP 409 `consent_required` with `error.requiresAction.url` pointing to the saved draft in the authenticated composer. Validation can return the same handoff alongside its structured issues. The person reviews the exact video/caption and makes explicit choices there; product keys and MCP cannot confirm on their behalf. After a person confirms, retry through the normal shared publishing service. Editing the content or changing the destination identity requires fresh review. The handoff URL contains no product key, token or signed media URL and grants no access to a person who lacks workspace membership. Its workspace UUID identifies the key's workspace; a browser with a different selected workspace must explicitly switch after a current membership check before reviewing this draft. See [OpenAPI specification](/docs/openapi.yaml) for the complete, current contract. UI, REST and MCP all read the same services, so they apply the same workspace rules. Results reflect each request’s current state; separate requests can observe intervening updates. --- Source: https://autoposted.buildamicrosaas.com/docs/authentication Reviewed: 2026-11-10 # Authentication and product keys AiVideoEditor's UI, REST API and MCP adapter share workspace services. API clients use a product key, not a social-network OAuth token or database credential. Create keys at `/app/developers` after signing in to the correct workspace. Copy the plaintext `pk_v1_…` key once and store it in a secret manager or protected local environment. AiVideoEditor retains a hash and display prefix. ## Send a key ```bash curl --fail-with-body -sS \ -H "Authorization: Bearer $PUBLISHER_KEY" \ "$PUBLISHER_API_URL/api/v1/usage" ``` Use HTTPS for a deployed origin. Keep credentials out of URLs, source control, chat prompts, screenshots and logs. Direct storage uploads use the returned signed URL and headers; do not forward your AiVideoEditor bearer key to storage. ## Scopes and account access | Scope | Capability | |---|---| | `accounts:read` | Inspect accounts, capabilities and TikTok settings | | `media:write` | Reserve, finalize and manage uploads | | `posts:read` | List posts, validate drafts and observe status | | `posts:write` | Create and edit drafts | | `posts:publish` | Publish, schedule, cancel and retry deliveries | | `usage:read` | Read workspace usage and plan information | | `webhooks:manage` | Register, list and remove webhook endpoints | Scopes are exact names, not a hierarchy. Grant only those the integration needs. Keys may also restrict accessible account IDs. Workspace membership, effective role, account restrictions and plan state still apply. A key with `posts:publish` does not automatically gain draft-writing access. The default key scope set omits `posts:publish` and `webhooks:manage`. A draft-only agent can prepare work for review without authority to send it. Keys cannot create other keys or change billing. ## Revocation and recovery Revoke a compromised key in the developer UI. Review its pending-job count first: revocation pauses unsent work as `requires_action`; it does not delete drafts. Create a replacement with appropriate access and review pending work before resuming. Do not assume revocation can recall a submission already sent externally. A `401` means credentials are absent or invalid. A `403` means the authenticated actor lacks permission or account access. Repeatedly retrying either response will not fix it. See [errors and recovery](/docs/errors). --- Source: https://autoposted.buildamicrosaas.com/docs/publishing Reviewed: 2026-11-11 # Publishing and scheduling An AiVideoEditor post has a versioned draft and independent deliveries for its selected accounts. Draft saving is permissive; successful saving does not establish that every destination is publishable. ## Prepare a post 1. Read `/api/v1/accounts` and `/api/v1/capabilities` with the intended key. 2. Upload and finalize any required [media](/docs/media). 3. Create a draft with `POST /api/v1/posts`, or edit with `PATCH /api/v1/posts/{id}`. Supply the current `expectedVersion` on edits and preserve the returned version. 4. Set destination format and explicit per-account variant overrides where needed. The [API reference](/docs/api) defines the request fields. 5. Validate with `POST /api/v1/posts/{id}/validate`. HTTP 200 may contain `valid: false`; inspect every issue before submitting. Invalid accounts are not silently removed from the audience. ## Publish now or later `POST /posts/{id}/publish` submits the current draft. `POST /posts/{id}/schedule` requires `scheduledAt`, `timezone` and `expectedVersion`. The scheduled instant must be future and within 90 days. Store a UTC ISO timestamp and a separate IANA display timezone; resolve daylight-saving ambiguities before sending. Use a distinct `Idempotency-Key` for each new mutation. Retain that key and exact request body before sending. Following a timeout, replay the identical request with the same key. Change the key only when intentionally requesting a new operation. A stale draft edit or schedule returns `revision_conflict`; reread and review the latest content rather than overwriting it blindly. A `202` response means accepted for dispatch. It is not evidence of publication. Record delivery IDs and observe `GET /posts/{id}` or signed customer webhooks. Use bounded polling with increasing delays; stop for terminal results or a human handoff rather than looping indefinitely. ## Per-destination outcomes Deliveries can settle independently. One destination may publish while another needs reconnection or consent. Show each state and native post link when present. Retry only an eligible known failure using `POST /deliveries/{id}/retry`. Successful destinations must not be recreated to recover a failed one. An unknown external outcome needs reconciliation or review, not a fresh submission. Cancel with `POST /deliveries/{id}/cancel` while work remains safely unclaimed. `too_late_to_cancel` means submission has progressed beyond safe cancellation; it does not mean the external post has been removed. ## TikTok human review Read `/accounts/{id}/tiktok/settings` for current creator settings and available privacy choices. A settings read or a draft save does not provide consent. `consent_required` includes a safe `requiresAction` handoff to the authenticated composer. An authorized person reviews the exact video, caption and destination and explicitly confirms the required choices there. Product keys and MCP tools cannot confirm on their behalf. Content or identity changes require fresh review. The handoff grants no membership or access by itself. ## Composer controls Use **Add media** to upload a file or choose an existing library item. The caption is shared until **Customize content** creates an account-specific variant. Emoji and hashtag tools insert ordinary text at the cursor. **Posting options** groups settings for the selected account. Required choices stay visible; optional groups remain collapsed. Changes apply only to that account. **Preview** shows the effective draft without saving or submitting it, including incomplete drafts; native platform presentation can differ. Use private asset references for scheduled covers and thumbnails. Public URL alternatives must remain reachable at delivery time. Subtitle content is stored with the immutable settings rather than depending on a temporary local file. LinkedIn document upload currently accepts PDF; Office formats remain restricted until signature validation is implemented. See the [capabilities reference](/docs/capabilities) for canonical controls and integration limits. New format and confirmation behavior requires the corresponding database migrations before deployment. --- Source: https://autoposted.buildamicrosaas.com/docs/capabilities Reviewed: 2026-11-10 # Networks and destination capabilities AiVideoEditor's beta destinations cover Instagram, Facebook, LinkedIn, YouTube and TikTok. Availability in the UI is distinct from live-provider verification. Read `GET /api/v1/capabilities` with the actual product key before preparing a post; static marketing descriptions cannot establish that a particular account can publish a particular format. | Network | Baseline formats | Account and workflow considerations | |---|---|---| | Instagram | Single image, image set, video | Professional business/creator accounts; Stories are later work | | Facebook | Text, single image, image set, video | Pages, not personal profiles; choose the destination Page explicitly | | LinkedIn | Text, single image, image set, video | Member and organization permissions differ; document carousels are later work | | YouTube | Video | Requires title and visibility; ready-to-upload video; Shorts distribution is not guaranteed | | TikTok | Video | Current creator settings and explicit human consent; an interactive completion step may be required | Demo destinations are labeled simulation: nothing is published externally. Never present demo outcomes as evidence of live network support. ## Use effective limits Capabilities include eligible formats, maximum media count, caption limits, required title, visibility options, consent requirements, known limitations and verification metadata. Apply the strictest effective limit across application, provider, network and connected account. A successful capability read does not replace final validation; connections or creator settings may change later. `lastVerifiedAt: null` means no real verification date has been recorded. Use account IDs returned by `/accounts`, not network names, as draft destinations. Respect pagination and the key's allowlist. If a destination is disconnected or requires review, surface that requirement rather than quietly reducing the audience. For TikTok, `/accounts/{id}/tiktok/settings` supplies current privacy choices, interaction permissions, duration limits and available modes. Never invent a privacy option from a static list or submit human consent through an agent. See [publishing and scheduling](/docs/publishing) for the review handoff. --- Source: https://autoposted.buildamicrosaas.com/docs/media Reviewed: 2026-11-10 # Uploading and retaining media Media bytes travel directly to temporary private object storage. REST and MCP return upload instructions; they do not accept binary file content in tool JSON. Storage must be configured on the deployment or upload creation returns `provider_unavailable`. ## Upload lifecycle 1. Call `POST /api/v1/media/upload-intents` with filename, declared MIME and byte count. Save the returned `assetId` and `sessionId` as separate identities. 2. Inspect `method`. For `presigned_put`, upload the whole file to `uploadUrl` using the returned headers. For `multipart_initiated`, split using `partSizeBytes`, upload each numbered part to its returned URL and retain its ETag receipt. Never add the AiVideoEditor bearer key to storage requests. 3. Finalize at `POST /api/v1/media/{assetId}/finalize` with `sessionId` and, for multipart, `multipart.parts` containing each `partNumber` and `etag`. 4. Use the finalized asset ID in the draft's `mediaIds`. An upload intent alone does not make the asset publishable. The server observes actual bytes and format on an immutable final copy. Declared size/MIME are reservation inputs, not proof of file validity. Supported baseline families are JPEG, PNG and MP4; individual destinations can impose stricter limits. The current maximum file size is 500 MiB (524,288,000 bytes). Files at or above 50 MiB use multipart, normally with 16 MiB parts. Always follow returned sizes, URLs and expiry rather than deriving them from these defaults. ```json { "sessionId": "", "multipart": { "parts": [ { "partNumber": 1, "etag": "" } ] } } ``` This is a multipart shape illustration; include every actual part. Single-PUT finalization sends only `sessionId`. Give each new API mutation its own `Idempotency-Key`; retain it for safe identical retries. ## Resume or abandon Expired signed URLs are not permanent media addresses. Request fresh multipart part URLs with `POST /media/{id}/upload-parts` using `fromPart` and `toPart` (an inclusive range of at most 64 parts). See the [API reference](/docs/api) for the bounded request shape. Do not re-upload completed parts unnecessarily or complete multipart assembly directly through storage: finalization is server controlled. Use `POST /media/{id}/abandon` when canceling an incomplete upload. This releases its reservation through the shared cleanup workflow. Session expiry or consumed multipart state may require a new intent; do not guess storage object keys. ## Temporary retention `GET /media/{id}` returns status and dynamic `deleteAfter` information, not a permanent public URL. Scheduled and in-flight uses protect media through the work. Default policy retains unused draft media for 14 days, settled media for 72 hours, and failed or ambiguous work for 7 days after the relevant attempt. Actual retention depends on all remaining references; `deleteAfter` may be null. Keep originals. If media is expired or deleting, upload it again before publishing. --- Source: https://autoposted.buildamicrosaas.com/docs/webhooks Reviewed: 2026-11-11 # Customer webhooks Outgoing event delivery for your workspace. Register an HTTPS endpoint, verify the one-time signing secret, and receive signed events with bounded retries. ## Register an endpoint ```bash curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \ -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \ $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}' ``` - The signing secret (`whsec_…`) is returned **once**: in the first successful creation response. Store it; an idempotent replay of the same creation returns the endpoint without the secret, and it cannot be shown again. - Destinations must be **HTTPS**, publicly resolvable, and free of embedded credentials. Requests to private, loopback, link-local (including cloud metadata), unique-local and multicast addresses are refused before any connection is made, and redirects are never followed. - Registration enqueues a **targeted** `webhook.verification` event for that endpoint, independent of its `eventTypes` filter. Ordinary events flow only after your endpoint answers the verification with 2xx. ## Verifying deliveries Every request carries: | Header | Meaning | |---|---| | `x-publisher-event-id` | Stable event ID: identical across retries and replays | | `x-publisher-event-type` | Event type, e.g. `post.published` | | `x-publisher-timestamp` | Unix seconds | | `x-publisher-signature` | `t=,v1=` | The signature is HMAC-SHA256 over `${t}.${event_id}.${raw_body}` using your signing secret. Verify with a ±300 second tolerance and reject replays outside it. Node example: ```js import { createHmac, timingSafeEqual } from 'node:crypto'; function verify(secret, headers, rawBody) { const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']); if (!m) return false; const [t, v1] = [Number(m[1]), m[2]]; if (Math.abs(Date.now() / 1000 - t) > 300) return false; const expected = createHmac('sha256', secret) .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`) .digest('hex'); return timingSafeEqual(Buffer.from(expected), Buffer.from(v1)); } ``` Always verify against the **raw** request body before parsing. ## Event envelope ```json { "id": "0192d0d0-0000-7000-8000-00000000000f", "type": "post.published", "createdAt": "2026-11-09T12:00:01Z", "apiVersion": "2026-11-09", "data": { "postId": "…", "deliveryId": "…", "accountId": "…" } } ``` Initial event catalog (extensible; `eventTypes` filters at registration): - `webhook.verification`: challenge payload; answer 2xx to activate the endpoint - `post.published`: one destination confirmed with a native receipt - `delivery.failed`: one destination failed terminally - `delivery.requires_action`: consent/reconnection/late-review required Aggregate post outcomes (`post.partially_published`, `post.failed`) are not emitted yet; they are documented here only once a producer exists, so don't rely on them. Subscribe to the per-destination events above and derive batch state from the post's delivery outcomes. ## Retries, replay and disabling - Attempts: immediately, then +1m, +5m, +30m, +2h, +8h. Retries reuse the **same event ID and byte-identical body** so you can deduplicate safely. - 2xx = delivered. 429/5xx/timeouts retry. Other 4xx fail permanently for that event (fix the endpoint, then replay). - **410 Gone** disables the endpoint: no further events are enqueued to it. - Operator-authorized replay through the internal webhook service re-sends an event with its original ID. An actively-leased in-flight attempt is never yanked; replay reports that the event is busy and can be retried shortly. ## Operational notes - Delivery diagnostics store only safe outcome codes: never your secret, signatures, request headers or response bodies. Payloads are additionally sanitized: provider/OAuth secrets and media presign URLs are stripped before anything is queued. - Endpoints are workspace-scoped: possession of an endpoint UUID from another workspace does nothing. - Delivery is at-least-once per accepted event occurrence; deduplicate on `x-publisher-event-id`. ## Developer tools availability The Developers page lists workspace API keys and webhook endpoints independently of signing-secret encryption configuration. Creating a webhook requires valid server encryption configuration; ask the deployment operator to resolve a configuration warning. API-key management remains available. Existing signing secrets are never shown again. --- Source: https://autoposted.buildamicrosaas.com/docs/errors Reviewed: 2026-11-10 # Errors, retries and recovery API errors use `{ "error": { "code": "…", "message": "…", "requestId": "…" } }` with optional field errors, destination errors, retry hints and action handoffs. Preserve `requestId` for support. Do not log credentials, signed upload URLs or sensitive request content when collecting diagnostics. | Response | Recovery | |---|---| | `401 unauthenticated` | Check missing, malformed or revoked product key | | `403 forbidden_scope` / `account_not_allowed` | Review key scopes and destination access | | `402 account_limit`, `seat_limit`, `storage_limit` | Review workspace entitlement and resource use | | `402 subscription_inactive` / `trial_expired` | Resolve billing state; preserve drafts and queued work | | `409 revision_conflict` | Read the current version, review changes and intentionally reapply | | `409 idempotency_conflict` | The key was reused with a different body; reconcile the original operation | | `409 consent_required` | Ask an authorized person to complete the supplied review handoff | | `409 too_late_to_cancel` | Inspect actual delivery status; do not claim cancellation succeeded | | `media_expired` / `media_deleting` | Re-upload originals and update the draft | | `422 validation_failed` | Correct structured fields or per-destination issues | | `429 rate_limited` | Respect `Retry-After`; reduce concurrency and use backoff | | `submission_unknown` | Reconcile the existing external outcome before attempting another submission | ## Safe mutation retries Generate an idempotency key before the first mutation and store its exact request. If the response is lost, the operation may already have succeeded. Replay the same request with the same key; never generate a fresh key merely because the network timed out. MCP mutating tools echo their key, including in `transport_outcome_unknown` failures. The adapter does not auto-retry mutations. Technical workspace speed limits are not posting credits. Use `/usage` for the current plan and rate information. Back off for transient errors only when appropriate; retrying authorization, validation or human-consent errors without changing their cause does not help. ## Partial success and observation An accepted publish/schedule batch is a set of independent deliveries. Keep successful receipts and native links. Recover a failed destination through its own retry endpoint instead of creating the whole batch again. Prefer signed [webhooks](/docs/webhooks); if polling, use a bounded number of attempts with increasing delays and surface unresolved work to a person. --- Source: https://autoposted.buildamicrosaas.com/docs/mcp Reviewed: 2026-11-10 # MCP setup A local **stdio** MCP server that wraps the same shared services as the UI and REST API via `/api/v1`. The adapter sends your product key only to the configured AiVideoEditor API. No Supabase or provider credentials are used. ## Prerequisites This is a source-checkout adapter, not a published package or hosted connection. Obtain authorized access to the AiVideoEditor repository, install Node 22+, and run `npm ci` at the repository root. Create a workspace product key in `/app/developers` with only the needed scopes and destination access. A draft-only key cannot publish or schedule. Never paste the key into a chat prompt. ## Run it ```bash export PUBLISHER_API_URL=https://app.example.com # HTTPS; http://localhost is allowed for dev export PUBLISHER_API_KEY=pk_v1_… # create in /app/developers node packages/mcp/bin/publisher-mcp.mjs # or: npm start --workspace packages/mcp ``` The bin is a real executable launcher (TypeScript + extensionless imports are resolved through `tsx`). All diagnostics go to **stderr**; stdout carries protocol traffic only. `PUBLISHER_API_URL` must be HTTPS (plain HTTP only for loopback development) and must not carry credentials, queries or fragments. ## Generic client configuration ```json { "mcpServers": { "autoposted": { "command": "node", "args": ["/absolute/path/to/packages/mcp/bin/publisher-mcp.mjs"], "env": { "PUBLISHER_API_URL": "https://app.example.com", "PUBLISHER_API_KEY": "pk_v1_…" } } } } ``` The launcher requires Node 22+ and the workspace dependencies (`tsx`, `@modelcontextprotocol/sdk`). A hosted MCP transport with OAuth is future work; do not assume every desktop or hosted client supports pasted bearer keys. ## Tools | Tool | Read/Mutate | Notes | |---|---|---| | `list_accounts` | read | Honors the key's account allowlist | | `get_capabilities` | read | Formats, limits, consent requirements | | `create_upload_intent` | mutate | Returns direct upload instructions; media bytes never flow through tools | | `finalize_upload` | mutate | Session id (+ multipart part receipts); the server observes bytes/MIME itself | | `create_draft` | mutate | Source + destination variants | | `validate_post` | read | Structured per-destination issues | | `schedule_post` | mutate | One instant, ≤90 days ahead, `expectedVersion` required | | `publish_post` | mutate | 202 semantics; not proof of publication | | `get_post_status` | read | Per-destination states and native links | | `list_posts` | read | Cursor pagination | | `cancel_delivery` | mutate | Only while safely unclaimed | | `retry_delivery` | mutate | Only known failures; never duplicates | | `get_usage` | read | No remaining-post counter exists | ### Required tool arguments | Tool | Required arguments | |---|---| | `list_accounts` | None | | `get_capabilities` | None | | `create_upload_intent` | `filename`, `declaredMime`, `declaredBytes` | | `finalize_upload` | `assetId`, `sessionId` | | `create_draft` | `caption`, `destinations` | | `validate_post` | `postId` | | `schedule_post` | `postId`, `scheduledAt`, `timezone`, `expectedVersion` | | `publish_post` | `postId` | | `get_post_status` | `postId` | | `list_posts` | None | | `cancel_delivery` | `deliveryId` | | `retry_delivery` | `deliveryId` | | `get_usage` | None | Optional arguments include pagination on list tools, `idempotencyKey` on mutations, `multipart.parts` for multipart finalization, and draft media and destination variants. The runtime tool schema returned by `tools/list` is authoritative for optional fields, nested shapes and validation limits. Mutating tools accept an optional `idempotencyKey` argument. When omitted, the server generates one and **echoes it in every result: including transport failures**, where the operation may already have reached the API (the error carries `transport_outcome_unknown` plus the key). Tools never auto-retry mutations; retry with the SAME idempotency key to avoid creating a duplicate operation. ## Agent workflow example 1. `list_accounts` + `get_capabilities` → choose valid destinations. 2. `create_upload_intent` → upload bytes directly → `finalize_upload`. 3. `create_draft` → `validate_post` → fix or deselect invalid destinations. 4. `publish_post` (or `schedule_post`) → note the delivery IDs. 5. `get_post_status` (bounded polling or customer webhooks): treat `requires_action` responses as actionable instructions, e.g. TikTok consent. ## Tested clients - **Official `@modelcontextprotocol/sdk` TypeScript client, real subprocess stdio** against the documented bin (`initialize → tools/list → tools/call`): tested in `packages/mcp/tests/stdio.test.ts`, including clean-stdout and startup-failure checks. - **Official SDK client over in-memory transport**: also covered. - Desktop clients (Claude Desktop, Cursor, etc.): **not yet tested**: configure per the generic snippet above and report results before claiming support. ## Client compatibility | Client or transport | Status | Setup | |---|---|---| | Official TypeScript SDK subprocess stdio | Automated test coverage | Repository launcher shown above | | Official SDK in-memory transport | Automated test coverage | Test harness only | | Claude Desktop / other desktop clients | Not manually verified | Local stdio-capable client; use absolute launcher path | | ChatGPT hosted connection | Not provided by this adapter | Requires a hosted transport; local stdio JSON is not a hosted connector | | Hosted MCP with OAuth | Not implemented | Separate product work | ## Troubleshooting - Launcher cannot resolve dependencies: run `npm ci` in the authorized source checkout and check Node version. Do not substitute an unrelated public package. - Client never initializes: use the absolute launcher path and inspect stderr. Do not write debugging output to stdout. - `401`: verify the configured product key is current; create a replacement in the UI if revoked. `403`: check scopes and account restrictions. - `transport_outcome_unknown`: retain the returned idempotency key and retry the identical operation with that key, never a new one. - `requires_action`: hand the provided instructions to an authorized person; an agent cannot supply TikTok human consent. ## Credential handling The product key is sent **only** to your configured AiVideoEditor API (`Authorization: Bearer`). It is never sent to model providers or social networks, never logged, and URLs are validated so the key cannot follow a redirect or escape the configured origin. --- Source: https://autoposted.buildamicrosaas.com/docs/changelog Reviewed: 2026-11-11 # Documentation changelog ## 2026-11-11 - Clarified developer-tool availability when webhook encryption is misconfigured. - Corrected webhook replay guidance: the current developer UI does not expose event replay; operator tooling uses the internal service. - Updated setup migration coverage, worker budgets, refund-event subscription, and encryption-key recovery instructions; corrected consolidated billing and notification schema references and local quickstart navigation. ## 2026-11-10 - Added public guides for authentication, capabilities, publishing, media and error recovery alongside the API, webhook and MCP references. - Corrected multipart-upload guidance to match the current shared media engine. - Clarified that the local MCP adapter sends its product key to the configured AiVideoEditor API, and that hosted MCP/OAuth is not implemented. - Updated the quickstart to capture returned post IDs and versions, use distinct mutation keys, and compute a future schedule time. These are documentation changes, not a declaration of live-provider or desktop client verification. Review dates record content review, not deployment dates.