> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: Create and edit a post
description: Create one independent post from the workspace business details, attach saved media, and hand the review link to the owner.
section: workflows
order: 20
status: implemented
mode: both
reviewed: 2026-11-19
sources: [src/lib/mcp/agent-post-publish-tools.ts, db/migrations/20261119T0400_agent_connected_account.sql, db/migrations/20261112T2130_agent_instagram_destination.sql, src/components/marketing/post-account-choices.tsx, src/lib/marketing/post-clone.ts, src/lib/marketing/post-dates.ts, src/lib/marketing/post-calendar.ts, src/components/marketing/post-calendar.tsx, src/app/[workspace]/(app)/calendar/page.tsx, src/lib/server/review/review.ts, db/publishing.sql, src/lib/youtube/youtube.ts, src/lib/server/youtube/YouTubeService.ts, src/lib/server/marketing/service.ts, src/lib/server/marketing/marketing-agent-tools.ts, src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/server/x/XPublishing.ts, src/components/owner/x-panel.tsx, db/x.sql, src/components/marketing/post-card.tsx, src/components/marketing/website-post-drafts.tsx, src/components/marketing/marketing-workspace.tsx, src/app/posts/review/page.tsx, src/app/[workspace]/(app)/marketing/page.tsx, src/components/owner/post-review.tsx, src/components/owner/instagram-approval-panel.tsx, src/components/owner/instagram-destination-selector.tsx, src/lib/instagram/instagram-owner-publish.ts, src/components/owner/youtube-controls.tsx, src/components/use-draft-autosave.ts, src/lib/review/draft-recovery.ts, src/lib/marketing/post-catalogue.ts, src/lib/marketing/post-scheduling.ts, src/lib/server/marketing/PostScheduling.ts, src/components/owner/post-schedule-controls.tsx, src/components/marketing/post-catalogue-picker.tsx, src/components/marketing/post-format-preview.tsx, src/components/marketing/create-post-stepper.tsx, src/components/owner/post-account-list.tsx, src/components/owner/post-caption-assistant.tsx, src/components/owner/post-media-dialog.tsx, src/components/owner/platform-preview.tsx, src/lib/marketing/post-list-state.ts, src/lib/uploads/owner-uploads.ts, src/lib/server/marketing/PostScheduleStore.ts, src/lib/server/owner/OwnerHandler.ts, src/lib/tiktok/tiktok.ts, src/lib/marketing/marketing-drafts.ts, src/lib/marketing/studio-handoff.ts, src/components/studio/post-return-link.tsx, src/components/studio/studio-page.tsx, src/components/owner/post-review-editor.tsx, src/components/motion/use-project-editor.ts, db/migrations/20261119T0420_agent_delete_cancel_post.sql, src/lib/mcp/agent-post-lifecycle-tools.ts, src/lib/server/marketing/post-lifecycle-agent-tools.ts, src/lib/marketing/post-lifecycle.ts]
tools: [get_workspace, duplicate_post, create_post, get_post, inspect_post, edit_post, get_post_catalogue, list_post_calendar, get_post_schedule, prepare_post_schedule, publish_post, delete_post, cancel_post_schedule]
next: [/docs/workflows/media, /docs/channels/instagram, /docs/contracts/request-ids]
---
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

1. Call `get_workspace` and read the business details. `sourceFacts` may cite only `profile.approvedFacts`.
2. Call `create_post` with a stable `requestId`. Set the channel, format, text and optional saved asset IDs. The result contains one `post` and its protected `review.url`.
3. Read `get_post`, `list_posts` or `inspect_post` to resume the saved work.
4. Call `edit_post` with the `postId` and 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 an `automatic` post on any channel, an agent with Publish uses the one connected account of that channel; `publish_post` and `prepare_post_schedule` save it on the post.
5. Give the owner `review.url` at `/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](/docs/workflows/cross-posting). **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](#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](/docs/workflows/videos#the-editor) 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](/docs/channels/youtube).

For X, the owner selects the account and approves the exact post. See [X publishing](/docs/channels/x).

## 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 |
| --- | --- |
| Instagram | 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 |
| LinkedIn | Text, Link, Image, Carousel, Video |
| Facebook | 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`](/docs/contracts/errors#recovery-by-kind) 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](#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_post` hides one post from `list_posts`, `get_post` and 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_post` cancels it first. For TikTok, it cancels an operation that has not started. `cancelledSchedule` is `true` when 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_schedule` cancels the pending schedule of one post. It returns the cancelled `schedule`, or `schedule: null` for 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](/docs/channels/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.
