createSingleImagePost
Create a single-image post (blog, event, job, or coupon) with a feature image and body content. Automatically checks for title uniqueness before saving.
Instructions
Create a post - Create a new post record. Writes live data.
Use when: creating a blog article, event, job listing, coupon, or any other single-image post type. Look up data_id + data_type via listPostTypes first - the post type's data_type field determines which create endpoint is correct. If data_type=4 on the post type, use createMultiImagePost instead. For posts with scraped external image URLs, include auto_image_import=1 to fetch and store them locally.
Required: user_id, data_id, data_type.
Pre-check before create: BD does NOT enforce uniqueness on post_title, and BD auto-generates filename (the URL slug) from the title - so a duplicate title produces a URL collision (two posts fighting for the same public URL, unpredictable which one resolves). Do a server-side filter-find: listSingleImagePosts property=post_title property_value=<proposed> property_operator==. Zero rows = title free; >=1 row = taken. If post_title contains commas/colons/special chars (the = operator trips the CSV validator on those), switch to property_operator=like property_value=<distinctive-prefix>% using a 3-4-word prefix unique to this event. Do NOT paginate unfiltered lists - sites in the wild have thousands of posts; filtered lookup is one tiny response. If taken: reuse via updateSingleImagePost, OR ask the user, OR pick an alternate post_title and re-check. Never silently create a duplicate.
Parameter interactions:
user_id- owner; must be an existing member (discover vialistUsersorsearchUsers)data_id- post type category ID; get vialistPostTypesdata_type- data type classification; usually matches the post type's data typepost_status:0=Draft (not visible),1=Published (public)Response includes both
post_idandpost_token- the token is used for sharable URLs
See also: updateSingleImagePost (modify existing).
Which endpoint to use - data_type family decides:
Every post type in data_categories has a data_type field that classifies its family. Call listPostTypes or getPostType to see the data_type of your target post type, then choose:
| Family | Use endpoint |
| Multi-image (albums, galleries, photo-heavy listings - e.g. Classified, Photo Album, Property, Product) |
|
| Single-image video |
|
| Single-image article / event / blog / job / coupon |
|
| Internal admin types (Member Listings, Reviews, Sub Accounts, Specialties, Favorites) - NOT posts | Use the resource-specific endpoint (e.g. |
If you call the wrong create endpoint for a given post type, BD may accept the row but it won't render on the public site correctly.
For "make a blog post" intent: look up data_categories for data_name matching "blog" (commonly data_id=14 with data_type=20) -> createSingleImagePost with that data_id + data_type.
For "make a photo album" / "gallery" intent: look up the album post type (often data_id=10, data_type=4) -> createMultiImagePost with that data_id + data_type. Photos are added separately via createMultiImagePostPhoto using the returned group_id.
Picking post_category (and other per-type dropdowns): post_category values are configured PER POST TYPE by the site admin in the post type's feature_categories CSV. Read the CSV from your listPostTypes/getPostType result (or getPostTypeCustomFields.post_category.choices where your workflow routes through it) and pass ONE value from it VERBATIM - never from getSingleImagePostFields.post_category.choices, which BD fills from platform master defaults on some forms - BD does not trim whitespace when splitting feature_categories, so options after the first may have a leading space (e.g. " Category 2"). If the user names a category that isn't in the list: ask whether to pick the closest existing option or have them add the new option in BD admin first - do NOT invent a new value. WARNING: if form_name does not match a real post type form, getSingleImagePostFields silently returns a generic SUPER-UNION field list (HTTP 200, no error) - verify form_name exists in listPostTypes first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude for the post's location (geo-enabled post types). Decimal degrees as string. | |
| lon | No | Longitude for the post's location (geo-enabled post types). Decimal degrees as string. | |
| data_id | Yes | Parent post-type ID (data_categories.data_id, from listPostTypes). | |
| user_id | Yes | ||
| post_job | No | Employment type - used by Job post types only. Other post types ignore this field. | |
| post_url | No | Explicit CTA button link rendered under the feature image on the post-detail page. Use when the owner wants a prominent button. Full `http(s)://` URL. Stored in `users_meta` (database=`data_posts`, database_id=this `post_id`, key=`post_url`), not the `data_posts` column - the wrapper routes it automatically, scoped to this post. | |
| state_sn | No | 2-letter state/region code for the post's location (e.g. `CA`). | |
| data_type | Yes | Classification family, read from target post type's `data_type` column (via `listPostTypes`/`getPostType`). Values: - `4` = multi-image - use `createMultiImagePost` instead - `9` = single-image video - `20` = single-image article/event/job/coupon Internal-only values (`10`, `13`, `21`, `28`, `29`) are NOT post-creatable via this endpoint - use the resource-specific creator (e.g. `createReview` for `13`). Do NOT call `listDataTypes` - `data_type` is a classification, not a per-site FK. | |
| post_tags | No | Comma-separated keywords for the post. Free-form strings - not related to the `Tags` resource. | |
| country_sn | No | 2-letter country code for the post's location (e.g. `US`). | |
| 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. Default: Pexels landscape URL + `auto_image_import=1` (skip only on explicit no-image request). | |
| post_price | No | ||
| post_promo | No | Twin of post_price (job pay, event ticket price, coupon price — live-verified on jobs and events). BD requires post_promo to populate post_price — send post_promo (BD back-fills post_price). Sending post_price alone leaves post_promo null. | |
| post_title | No | ||
| post_venue | No | Event/post venue name/landmark where the event is held (e.g. `Staples Center`) - distinct from `post_location` (the street address). Free text. Stored in `users_meta` (database=`data_posts`, database_id=this `post_id`, key=`post_venue`), not the `data_posts` column - the wrapper routes it automatically, scoped to this post. | |
| post_video | No | Full URL of a YouTube or Vimeo video. Only used by Video post types (`data_type=9`). | |
| post_status | No | 0=Not Published, 1=Published, 3=Pending Approval (rare — set when site admin requires manual moderation before posts go live). | |
| auto_geocode | No | Set to `1` to geocode the post's location via Google Maps (uses `post_location`/lat/lon/state_sn/country_sn if supplied). Requires the "Pretty URLs with Google Maps" site feature. | |
| post_caption | No | Deprecated. Leave unset unless user explicitly references it. | |
| post_content | No | Main HTML body of the post. Froala body field — see **Rule: Post-body formatting** (structure, `fr-dib fr-fil`/`fr-fir` float + inline `width: 350px`, landscape Pexels images). HTML allowed; supports `[widget=Name]` shortcodes and `%%%template_tokens%%%`. | |
| post_category | No | Per-post-type dropdown value, configured in BD admin on the post type's `feature_categories` field. Discover allowed values from `feature_categories` on your `listPostTypes`/`getPostType` result, or `getPostTypeCustomFields.post_category.choices` where your workflow routes through it - NOT from `getSingleImagePostFields.post_category.choices` (BD fills that from platform master defaults on some forms). Pass VERBATIM - BD does not trim whitespace, so leading spaces after commas in `feature_categories` persist in the stored option values. | |
| post_location | No | Full or partial street address for the post (Event, Coupon, Job, or any geo-enabled post type). Pair with `auto_geocode=1` to resolve to lat/lon automatically, or set `lat`/`lon`/`state_sn`/`country_sn` explicitly. | |
| 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. Usually auto-set on create; override only for import/migration. | |
| post_meta_title | No | SEO `<title>` override for the post's public page. | |
| 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. | |
| 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. | |
| post_meta_keywords | No | SEO meta keywords (comma-separated) for the post's public page. | |
| post_meta_description | No | SEO meta description override for the post's public page. |