Create one post for one channel. A post has text, media, an approval and delivery records. It has one current version: an edit changes it in place. There is no campaign, goal or brief field. Creating a draft does not spend provider credits or publish it.
Steps#
- Call
get_workspaceand read the business details.sourceFactsmay cite onlyprofile.approvedFacts. - Call
create_postwith a stablerequestId. Set the channel, format, text and optional saved asset IDs. The result contains onepostand its protectedreview.url. - Read
get_post,list_postsorinspect_postto resume the saved work. - Call
edit_postwith thepostIdand the changes. An empty asset list removes attachments. An edit on the same channel keeps the selected account. A channel change clears the account selection. The owner selects the destination in the editor. Updated 2026-11-19: for anautomaticpost on any channel, an agent with Publish uses the one connected account of that channel;publish_postandprepare_post_schedulesave it on the post. - Give the owner
review.urlat/posts/review. The link opens the selected post under/{n}/marketing?tab=posts&post=<id>. The owner reviews the content, media and destination in the shared app layout. For Instagram, Publish checks the saved media and account, then queues one exact publication. Facebook and Threads require exact Page/profile review and a loaded media preview before approval. A failed check shows the next action. The page has a Posts breadcrumb to return to the post list.
The Posts editor saves valid text, format and media changes in the background after 5 seconds without another edit. Each edit is kept in browser local storage immediately, scoped to the owner, workspace and post. Unfinished edits return after navigation or reload. A failed save keeps the edits and shows Retry save. Publishing waits for the current edits to be saved. Title names the post in Posts and Calendar. The text field uses the platform's name for it: Instagram Caption; Facebook Description for video, Caption for photos and Message for text and link posts; TikTok Caption for video and Description for photo posts; YouTube Description; X, Threads, LinkedIn and manual posts Post text. YouTube keeps its published title in its own panel. The editors have no separate Hook or Call to action inputs. Put any hook or call to action in the published text or media.
The editor shows the platform and format with Change. Connected account lists the accounts that can publish the current format. Select one to save it. An account on another platform asks for confirmation, because it changes the platform. Add account opens Connections. A post with a planned date and no schedule shows Planned. A planned date alone does not publish the post.
Delete removes an unpublished or scheduled post from Posts, Calendar and agent reads. It cancels a schedule that has not started. A published post shows Archive instead: it stays on the social account, and ShipContent hides it. A post that is being published cannot be removed until the result is known. Records of generation, approval and delivery are kept.
Read current state with get_post before a new edit. After a lost response, replay the same request ID and input. Approval history closes the draft editing path.
Adapt to another channel#
Call duplicate_post with the source post ID and the target channel. Use the catalogue to choose a valid target format and placement when the source format does not fit the target channel. This creates one independent draft. It copies saved media references and content. It starts with no approval, schedule, delivery receipt or automatic publication mode. Adapt the text and format, then run the new channel's checks. The owner Clone and adapt dialog selects the platform and format before creation. A definite rejection permits correction in the dialog. An unknown result keeps the exact request for retry. A session check failure shows a reload action.
Clone retains Thread entries, their media, the link URL and the Story media choice. Fields outside the selected format stay saved but inactive. Thread media do not become top-level media, and a saved video does not become an image. Select compatible media in the new draft. The source stays unchanged.
The owner can create a blank draft, use a saved website idea or select Use in post from saved media. Create post has two steps. Format shows each format with a sample preview. Account · optional selects a connected account or a platform for that format. Select more than one account to make a draft for each: they open as one multi-platform post. Continue creates the draft and opens the editor. With no account chosen, the button reads Continue without account and the draft saves without an account. If no connected account can publish the format, the draft still saves. Connect an account to publish it. Create media in Studio, then attach the saved media to a post. Write with AI in the editor suggests text for the caption. See Write with AI.
Pick from library#
Updated 2026-10-26: accounts with first-video controls enabled have Make a video in Studio. A compatible video or video Story saves its current edits first, then opens native Studio. A thread entry has its own video action. Image, carousel, image Story, text and link drafts need an explicit compatible selection through existing Change controls, where available, followed by a valid save. Retained media must fit; it is never cleared or converted silently. If the format is locked, fixed by a set, or has no compatible choice, Create a standalone video opens Studio without a post target.
The native handoff carries only the post and optional entry IDs. It reads the current authorized post before using a return target. It creates no full Quick AI intent and does not load the private caption or brief into the general idea or manual form. Existing Quick AI video and image generation remain separate; this change does not repair legacy Quick recovery privacy.
Native creation does not attach a file, duplicate a post, schedule or publish. After rendering, Return to post opens the matching post; select the current rendered file explicitly from Library or the entry media picker. A missing, foreign, locked or stale target stays an error. See the editor's save and Return rules before leaving an open editor.
The media picker shows a thumbnail grid. Each tile shows the type, size and, where known, dimensions and duration. Search matches the file name as literal text, without case. The server runs the search: GET /owner/assets accepts an optional q parameter. Upload a file with the button or drag and drop. An image can be up to 30 MB. A video can be up to 50 MB (MP4 or MOV). Upload shows its progress. Then it shows that the file is saved in the workspace and that uploading does not publish it. The new file is selected when it fits the format. A video that is not vertical shows a warning for Reels, Shorts, Stories and TikTok video. The owner can dismiss the warning and still use the video.
Write with AI#
Write with AI is under the caption or thread editor. It is available for each format that shows a caption field. It is not available for YouTube video and Shorts. The owner can add an optional request of up to 280 characters. Suggest, Shorter and Try another each send one paid AI request. Shorter and Try another replace the suggestion that is shown. There is no automatic retry. The editor sends no new request while one is pending. When the post and the workspace give Luna nothing to write from, the editor says what to add: say what the post should say, or add brand text on the Brand page. Updated 2026-10-18.
Nothing in the post changes until the owner selects Use this caption, Use this text or Use this thread. Then the suggestion replaces the caption. For a Thread it also replaces the entry text and keeps the entry media. For a Link post it also replaces the link URL. The post name and the other fields stay. Facts used lists the saved product facts that the suggestion used.
Updated 2026-10-17: the queued text generation is removed. The owner actions generate-post, generate-text, apply-generated-text and recover-planner no longer exist, and a saved post shows no generation status or Recover generation.
The owner action suggest-text sends one paid request to Luna with the post, the workspace details and the brand text. It takes postId, a new requestId, an optional instruction (up to 280 characters) and an optional refine (shorter or another) with the previous suggestion. It returns a suggestion and does not change the post. The same requestId returns the saved result and is not sent again. A post that is approved, scheduled or sent cannot get suggestions. Updated 2026-10-17.
For YouTube, use prepare_youtube_publication. The editor saves the selected video and YouTube details in the background, then the owner selects Approve and upload for the exact saved video. The editor reads saved upload progress automatically. Read get_youtube_status for upload evidence. See YouTube.
For X, the owner selects the account and approves the exact post. See X publishing.
Planned dates and Calendar#
Select Set planned date in the post editor. Choose a local date, time and IANA zone. If a clock change repeats a time, choose its UTC offset. A time in a clock gap is rejected. A past planned date stays a draft. No account connection is required.
Open /{n}/calendar for Month or Week. The URL keeps view, date and optional post. The Calendar and all dates use the browser time zone. The Calendar loads every page in the visible range. Select a day to create a draft with a Planned for date at 09:00 in the browser zone, then confirm its date and catalogue before save. A planned date never publishes automatically. A clone clears it.
Immediate queued work shows Queued; running work shows Sending. Completed delivery shows Published, Uploaded · Private or Uploaded · Unlisted from its saved delivery status. The app Review item remains the media editor.
Platform and format catalogue#
Read get_post_catalogue before selecting a platform, format and placement. All these choices support saved drafts, saved media and generation without a connected account:
| Platform | Draft formats |
|---|---|
| Image, Carousel, Reel video, Story | |
| TikTok | Text, Image, Carousel, Video, Story |
| YouTube | Community Text, Image and Carousel; Video; Short video |
| X | Text, Link, Image, Carousel, Video, Thread |
| Text, Link, Image, Carousel, Video | |
| Text, Link, Image, Carousel, Reel video, Story | |
| Threads | Text, Link, Image, Carousel, Video, Thread |
Story keeps its image or video choice. A link has a separate URL. Carousel assets and Thread entries keep their order. A platform or account change retains content for correction. Incompatible media shows an inline error. Closing the media picker returns focus to the draft.
Publishing code supports owner immediate Instagram feed images, image carousels, Reels and Stories; Facebook Page text/photo/Reels; Threads text/image/video; X text/one image/one video; YouTube video uploads; and TikTok video. Other operations show Coming soon. This includes TikTok Text/Image/Carousel/Story, LinkedIn, Threads Link/Carousel/Thread, other Facebook formats, X Link/Carousel/Thread and YouTube Community posts. TikTok Ads is a separate advertising workflow. Catalogue publishing: "implemented" states code support only. It proves no account access, application approval or delivery.
Media generation does not require publication availability. A late generation result cannot replace a later media choice or edit a scheduled or delivered post. Its saved output remains in Library for an explicit selection.
Automatic schedules#
A Planned for date gives no delivery authority. For an enabled supported operation, select Schedule, choose a future time and confirm the saved content, operation, destination, visibility, local date/time, UTC offset, IANA zone and UTC instant. Preparation and final confirmation wait for all current edits to save. A failed save keeps edits and sends no schedule request. Changed saved content requires reload, another check and new confirmation.
Updated 2026-10-28. The final confirmation of Schedule sends the review digest of the post that the owner sees. If the saved post changed after that, for example after an agent edit, the schedule is refused with CONTENT_CHANGED and nothing is saved. Select Reload saved post, check the post, then schedule again. A repeated request with the same ID still returns its saved schedule.
Call prepare_post_schedule with a stable requestId, postId, future UTC runAt and IANA timeZone. With Publish (list_workspaces.access.canPublish) and an automatic post, it returns mode: "scheduled" and a saved schedule. Provider checks still apply. Updated 2026-11-19: this works on Instagram (Reel, image, carousel), Facebook, Threads, X and YouTube, and the post uses the one connected account of its channel. To publish now and not at a later time, call publish_post with the postId and a requestId; it has the same conditions and returns mode: "queued". Otherwise it saves no schedule and returns mode: "owner_review", reason and reviewUrl for the owner. Replay the same request ID and input after a lost response. Read get_post_schedule for the durable result and list_post_calendar for events; continue with nextCursor until it is null.
A scheduled post for which sending has not started shows Change time. It shows the current time and the new time, and it needs a new confirmation. The change is atomic: ShipContent cancels the old schedule and creates a new one with the same saved content and account. If sending has started, the change is refused with SCHEDULE_DISPATCH_STARTED and the live state is shown. A past time or the same time is refused, and the old schedule stays. The owner action is change-post-schedule-time.
A confirmed schedule locks editing. Cancel schedule or Remove schedule and edit needs an owner confirmation. An agent cancels a schedule that an agent made with cancel_post_schedule; see Delete a draft or cancel a schedule. Read the durable result before editing. SCHEDULE_DISPATCH_STARTED means sending started; cancellation did not stop that job. A cancelled schedule does not restore a planned date. The worker cannot dispatch before the confirmed instant. Its dispatch-start deadline is 15 minutes after that instant; late undispatched work becomes blocked and needs a new owner action.
After an unknown schedule or cancellation response, keep the same request ID and exact input. Reload or Retry confirmed schedule recovers that request after current edits save. Do not create replacement authority from a lost response. Provider jobs use their existing recovery paths; unknown publication never starts another submission.
get_post_schedule.schedule.clientId and list_post_calendar.events[].agentClientId identify the agent that scheduled work; they are null for owner schedules, including an owner replacement made with Change time. Calendar attribution uses the current saved schedule, including after dispatch. Owner pages can show the agent name. Turning off Publish keeps this work; disconnect cancels unsent agent work across all workspaces.
Calendar uses the scheduled instant until delivery completes, then the saved completion instant and actual visibility. Immediate work stays Queued or Sending, rather than Scheduled. Past-due planned drafts stay unpublished. Failed and unknown results stay distinct. View in calendar opens the exact date, zone and post, with the selected event highlighted. A cancelled schedule cannot supply the label or zone of a new planned date. If cancellation requires reload, the confirmation dialog shows Reload saved post and disables confirmation.
Delete a draft or cancel a schedule#
Updated 2026-11-19. An agent can delete a post and can cancel a schedule that an agent made. Both tools need a live grant for the workspace and the Publish permission. Without Publish they return PUBLISH_NOT_ALLOWED and change nothing. Neither tool calls a provider.
delete_posthides one post fromlist_posts,get_postand the calendar. It deletes no row, and there is no undo. A second call returns the same success. When an agent made a schedule for the post,delete_postcancels it first. For TikTok, it cancels an operation that has not started.cancelledScheduleistruewhen the schedule that an agent made for the post is cancelled, by this call or by an earlier one. A second call returns the same result.cancel_post_schedulecancels the pending schedule of one post. It returns the cancelledschedule, orschedule: nullfor a TikTok post. A second call returns the same result.
After a cancelled post schedule, the post is an open draft again. Edit it with edit_post, or schedule it again with prepare_post_schedule. A cancelled schedule does not restore a planned date. After a cancelled TikTok operation, the post stays locked, because it has an approval. Call duplicate_post to make a new draft.
| Case | Code | What changes |
|---|---|---|
| The post is published | POST_PUBLISHED | Nothing. Only the owner can archive it. Archiving does not remove it from the social network. |
| A delivery started or its result is unknown | PUBLISH_IN_PROGRESS | Nothing. Wait for the result. |
| The owner made the schedule | SCHEDULE_OWNER_LOCKED | Nothing. Only the owner can cancel it or delete the post. |
Sending started (cancel_post_schedule) | SCHEDULE_DISPATCH_STARTED | Nothing. Cancelling cannot stop the provider job. |
The post has no pending schedule (cancel_post_schedule) | NOT_FOUND | Nothing. |
Posts list and previews#
Each row in the Posts list has one action that depends on the state: View post, View schedule, Review issue, Fix account or Continue draft. A row shows the account name when it is known. If accounts cannot load, rows show Continue draft. Story, Thread and Link previews look close to the platform. Each preview says that it is approximate and that the platform decides the final layout.
For TikTok, prepare one saved video with channel: "tiktok" and format: "video". create_post and edit_post accept the caption, saved video ID, six tiktok.settings booleans and a proposed tiktok.schedule together. Timing is an explicit UTC dueAt with an IANA timeZone, or null. The post follows publishMode; these fields alone do not queue publication. Call prepare_tiktok_publication after all fields are saved. With Publish and an automatic post it can return mode: "queued", the saved operation and review: null. Otherwise give review.url to the owner for one approval and resolve any review blockers. TikTok timing stays in tiktok.schedule; prepare_post_schedule does not schedule TikTok. Read get_tiktok_status with postId afterward to find the operation, then read get_tiktok_operation. Use Upload video in Posts or select a saved generated video; no re-upload is needed. See TikTok.
Caption credit approval#
Updated 2026-10-18: Suggest, Shorter and Try another show the current ai.post.text credit price. Each new request saves that quote with its request ID. A price change stops the request; select the action again to accept the refreshed price. An uncertain response keeps the original request and quote across reload. Selecting Suggest again checks that request without a second provider call.
A successful provider response is charged once, including a response with unusable text. A confirmed rejection releases its hold. An unknown result keeps its hold for reconciliation. The owner action suggest-text accepts the optional quote field. The server checks the current plan, balance and editable post before the provider call. Billing stays off until an operator enables it.
An unreadable suggestion response shows a recovery message. Select Suggest again to check the saved request; this does not create a new provider call. Updated 2026-10-18.
If the provider succeeds but the post becomes locked or owner access ends before saving, the request is marked completed and charged with its result not kept. It does not remain a running or unknown request. Updated 2026-10-18.
Updated 2026-10-18: CAPTION_UNCONFIRMED means the browser did not receive a usable response. Check saved request keeps the original ID, instructions and quote. CAPTION_UNKNOWN is a saved server outcome. After that response, New request explicitly starts separate paid work at the displayed price with the current instructions. The prior attempt and its credit hold stay recorded. No retry starts a new paid request automatically.
Updated 2026-10-31: when Spanish is available for your account, the post editor, its publish, schedule and approval panels, platform previews, the media dialog and the performance view show your account language, English or Spanish. A saved delivery failure that the app knows shows in your language; other saved failures show a general recovery sentence in Spanish. A language change keeps your unsaved caption, planned date and schedule zone, and sends no publish request.
Captions, the text you wrote, channel names, URLs and the text of an agent edit stay as saved. A draft made from the Calendar has the saved title Planned for in English until you edit it. Tool output, error codes and the text agents read stay in English.