updateSingleImagePost
Idempotent
Edit an existing single-image post by ID. Modify only the fields you specify, such as title, status, content, and metadata, without affecting other data.
Instructions
Update a post - Update an existing post record by ID. Fields omitted are untouched. Writes live data.
Use when: editing post content, switching from draft to published (post_status=0->1), updating post title/caption, or correcting post metadata. To move a post to a different post type (rare), pass data_id - but validate the new post type is still in the single-image family.
Required: post_id.
Enums: post_status: 0=Draft (saved but not publicly visible), 1=Published (publicly visible on the site).
post_title rename does NOT update post_filename (the URL slug). post_filename is writable — see Rule: URL slug rename for when to suggest a slug update + redirect. Report post_filename from getSingleImagePost when giving the user a URL.
See also: createSingleImagePost (add new), deleteSingleImagePost (remove permanently).
Returns: { status: "success", message: {...updatedRecord} } - the full updated record after changes applied.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ||
| post_title | No | ||
| post_filename | No | Public URL slug path (e.g. `blog/my-post-slug`). Writable — BD does NOT regenerate the slug when `post_title` changes. See **Rule: URL slug rename** for when to suggest a slug update + redirect. | |
| post_content | No | Post body HTML. Froala body field — see **Rule: Post-body formatting** (structure, `fr-dib fr-fil`/`fr-fir` float + inline `width: 350px`, landscape Pexels images). | |
| post_status | No | 0=Not Published, 1=Published, 3=Pending Approval (rare — set when site admin requires manual moderation before posts go live). | |
| post_caption | No | Deprecated. Leave unset unless user explicitly references it. | |
| post_price | No | ||
| post_promo | No | Jobs-only twin of post_price. On job posts, BD requires post_promo to populate post_price too — send post_promo (BD back-fills post_price). Sending post_price alone leaves post_promo null. | |
| post_image | No | Feature image URL. **LANDSCAPE only — verify orientation via `getImageDimensions` per **Rule: Image dimensions** before commit; bare URL, no `?query`, must end in `.jpg`/`.jpeg`/`.png` (WebP/GIF/AVIF skipped pre-tool per the same rule) — see **Rule: Image URLs**.** Query strings (`?w=1600`, `?auto=compress`) get baked into the imported filename and 404. Pair with `auto_image_import=1` to fetch externals into site storage. | |
| post_category | No | Per-post-type dropdown value, configured in BD admin on the post type's `feature_categories` field. Discover allowed values via `getSingleImagePostFields(form_name=<post type's form_name>)` -> `post_category.choices[].key`. Pass VERBATIM - BD does not trim whitespace, so leading spaces after commas in `feature_categories` persist in the stored option values. | |
| post_tags | No | Comma-separated keywords for the post. | |
| auto_geocode | No | Set to `1` to geocode the post's location. Requires the "Pretty URLs with Google Maps" site feature. | |
| post_meta_title | No | ||
| post_meta_description | No | ||
| post_meta_keywords | No | ||
| post_location | No | Full or partial street address (Event/Coupon/Job/geo-enabled post types). | |
| lat | No | ||
| lon | No | ||
| state_sn | No | ||
| country_sn | No | ||
| post_live_date | No | Creation date stored on the post. Format: `YYYYMMDDHHmmss` in the site's timezone. BD silently truncates other formats, corrupting the value. | |
| post_start_date | No | Scheduled publish date — when the post becomes visible on the public site. Set a future timestamp to schedule (like WordPress's future-publish); set a past timestamp for immediate visibility. REQUIRED on Event post types (marks when the event begins); optional but commonly used on blog/article/news post types for scheduled publishing. Format: `YYYYMMDDHHmmss`. **Event post types: event-local wall-clock** — the time as a visitor in the event's city would read it; do NOT convert to the site's own timezone (a 7 PM Brooklyn event on a Los Angeles-timezoned site stores as `20260616190000`). **Scheduled-publish on blog/article/news types: site timezone.** BD silently truncates other formats, corrupting the value. The wrapper auto-derives `start_time` (`"H:MM AM/PM"`) from this value on `createSingleImagePost` / `updateSingleImagePost` so BD's form-edit time-of-day dropdown stays populated — agent never passes `start_time` directly. | |
| post_expire_date | No | End/expiration date. Coupon post types use this for expiration; Event post types use it for end time. Format: `YYYYMMDDHHmmss`. **Event post types: event-local wall-clock** (match `post_start_date`). **Coupons and other post types: site timezone.** BD silently truncates other formats, corrupting the value. The wrapper auto-derives `end_time` (`"H:MM AM/PM"`) from this value on `createSingleImagePost` / `updateSingleImagePost` — agent never passes `end_time` directly. | |
| post_video | No | YouTube/Vimeo URL - Video post types only. | |
| post_job | No | Employment type - Job post types only. | |
| auto_image_import | No | **Auto-import images to site storage.** Set `1` when any external image URL field on this single-image post (e.g. `post_image`) holds a URL - BD fetches the image and saves locally. Without the flag, BD stores the URL as-is; images break if source host goes down. **Recommended default when supplying external image URLs**; omit or set `0` only if user explicitly wants the external URL reference. Supports JPG/PNG/GIF/WebP/SVG. Processing delay: several minutes. | |
| _clear_fields | No | Column names to clear to empty string. Available on every `update*` operation. Works on base columns AND EAV/`users_meta` rows (rows preserved with `value=""`). To actually clear a field you MUST use this parameter — sending the field with `""` alone is a no-op (BD drops empty values). To remove a `users_meta` row entirely, use `deleteUserMeta`. See **Rule: Clearing fields**. Example: `_clear_fields: ["h2", "hero_link_url"]`. |