create_guide
Create a new draft guide.
/v1/guidesCreates an empty draft map guide (status draft, not visible anywhere). Only do this when the creator asked for a new guide; otherwise edit the existing one. The slug derives from the name unless given.
curl -X POST "https://sceniq.earth/api/v1/guides" \
-H "Authorization: Bearer $SCENIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "American West: Parks at First Light",
"slug": "american-west-first-light"
}'Body parameters
- namestringrequired
Guide title, 1-120 characters, e.g. American West: Parks at First Light.
- slugstringoptional
Optional URL slug (lowercase letters, digits, hyphens). Derived from the name when omitted.
Returns
201 Created with Guide: A guide: settings, region, areas, properties and price.
- productIdstring · guide idrequired
The guide's id.
- namestringrequired
The guide's title.
- slugstringrequired
URL slug of the sales page.
- headlinestring or nullrequired
One-line promise under the title on the sales page.
- purchaseButtonTextstring or nullrequired
The buy button label, or null for the default.
- statusstringrequired
draft (not on sale), published (on sale) or archived.
draftpublishedarchived - visibleOnStorebooleanrequired
Whether the guide shows in the Sceniq store (set in the studio).
- storeReviewStatusstring or nullrequired
The store review's state, or null before a review.
pendingapprovedrejected - storeReviewNotestring or nullrequired
The store review team's note.
- storeTagsarray of stringsrequired
Store tags from the fixed vocabulary.
- countrystring or nullrequired
ISO 3166-1 alpha-2 code of the country the guide covers; null means worldwide.
- reviewsShownbooleanrequired
Whether buyer reviews show on the store card.
- buyerCountShownbooleanrequired
Whether the buyer count shows on the sales page (set in the studio).
- pricingobjectrequired
How the guide is sold.
Show 3 fieldsHide fields
- oneTimeEnabledbooleanrequired
Whether the guide sells for a one-time price.
- subscriptionIncludedbooleanrequired
Whether it is part of a subscription.
- currencystringrequired
The guide's currency.
- originalLanguagestringrequired
The language the guide is written in (BCP 47).
- createdAtnumberrequired
When the row was created (Unix time in milliseconds).
- updatedAtnumberrequired
When the row last changed (Unix time in milliseconds).
- publishedAtnumber or nullrequired
When the guide first went on sale (Unix time in milliseconds).
- lastApiWriteAtnumber or nullrequired
When a key last changed the guide (Unix time in milliseconds).
The map region the viewer opens on.
Show 5 fieldsHide fieldsof MapRegion
- labelstringoptional
A name buyers recognise for the region, at most 120 characters (Hokkaido, the Dolomites).
- centerLatnumberoptional
Latitude of the opening center (-90 to 90), usually the middle of the spots.
- centerLonnumberoptional
Longitude of the opening center (-180 to 180).
- defaultZoomnumberoptional
The opening zoom level, 0 to 22; 8 to 11 suits a region.
- bboxarray of numbersoptional
The bounding box as [west, south, east, north] in decimal degrees, exactly four numbers. It should contain every spot: readiness flags spots outside it.
Parks, islands and regions spots can point at.
Show 10 fieldsHide fieldsof Area
- idstringrequired
The area's id, minted by
set_area; spots point at it withareaId. - namestringrequired
The area's name, at most 100 characters (Yellowstone National Park).
- kindstringoptional
park, reserve, island, region, city or other, shown as the area's label (Park, Island). Absent reads as other (Area).
parkreserveislandregioncityother - notestringoptional
What applies across the area, in the creator's words, at most 1,000 characters.
- seasonstringoptional
The area's season in words, at most 300 characters (roads open May to October).
Up to 20 access rules for the whole area (permits, timed entry), each shown in its months.
Show 6 fieldsHide fieldsof AccessRule
- textstringrequired
The rule in the creator's words, at most 300 characters.
- kindstringoptional
reservation, permit, guide, registration,
no_independent_travel, vehicle or other.reservationpermitguideregistrationno_independent_travelvehicleother - monthsarray of numbersoptional
The months the rule applies (1 to 12); the apps show it only then. Absent means all year.
- appliesTostringoptional
car for a rule that only binds drivers (a timed entry for vehicles), all for everyone.
carall - bookingOpensstringoptional
When booking opens, in words, at most 100 characters (90 days ahead at 07:00).
- sourceUrlstringoptional
The page that states the rule (http or https).
Up to 30 fees for the whole area (park entry, a vehicle pass).
Show 14 fieldsHide fieldsof Fee
- labelstringrequired
What the fee is for, at most 80 characters (Adult entry, Car park, Boat transfer).
- amountnumberoptional
The price in major units (40, 12.5). Needs currency. Absent when the fee is free or left to the official page.
- currencystringoptional
ISO 4217 code (USD, EUR, ARS). Required with amount.
- freebooleanoptional
true for no charge. Cannot be combined with an amount.
- seeOfficialbooleanoptional
true for a price the guide leaves to the official page on purpose (it changes too often to copy).
- perstringoptional
What one amount pays for: person, vehicle, night, group, entry, day or hour.
personvehiclenightgroupentrydayhour - audiencestringoptional
Who pays this rate: all, adult, child, foreign, domestic, resident, student or senior.
alladultchildforeigndomesticresidentstudentsenior - paidWherestringoptional
Where it is paid: online,
on_siteorin_tour(part of a tour price).onlineon_sitein_tour - paymentstringoptional
How it can be paid:
cash_only,card_onlyorcash_or_card.cash_onlycard_onlycash_or_card - notestringoptional
One line of context, at most 300 characters (free on the first Sunday of the month).
- validFromstringoptional
The first day the price applies (YYYY-MM-DD).
- validUntilstringoptional
The last day the price applies (YYYY-MM-DD). Readiness flags the row after it.
- sourceUrlstringoptional
The page the price comes from (http or https).
- checkedOnstringoptional
The day the value was last checked against its source (YYYY-MM-DD).
Up to 12 links for the whole area.
Show 5 fieldsHide fieldsof GuideLink
- kindstringrequired
What the link is for. official and website are the place's own pages; tickets and booking sell entry or rooms; status, timetable and tide carry live conditions; listing, social, authority and app cover the rest.
officialwebsiteticketsbookingstatustimetabletidelistingsocialauthorityappother - labelstringoptional
The link text buyers see, at most 60 characters. Without it the apps name the link by its kind.
- urlstringoptional
An http or https page. http is accepted with a warning.
- valuestringoptional
A channel that is not a URL, at most 200 characters, for example a WeChat mini program and its search term.
- notestringoptional
One line of context shown under the link, at most 300 characters.
A closure or works notice for the whole area.
Show 6 fieldsHide fieldsof StatusNotice
- statestringrequired
open,
partly_closed, closed or reopening. reopening with until means it reopens on that day.openpartly_closedclosedreopening - notestringoptional
What is closed or changed, in the creator's words, at most 500 characters.
- sincestringoptional
The day the state began (YYYY-MM-DD).
- untilstringoptional
The day the state is expected to end (YYYY-MM-DD). Must not be before since.
- sourceUrlstringoptional
The page that announced it (http or https).
- checkedOnstringoptional
The day the value was last checked against its source (YYYY-MM-DD).
Up to 40 research sources, never shown to buyers.
Show 7 fieldsHide fieldsof SourceRef
- urlstringoptional
The page, API or archive copy the facts come from (http or https).
- titlestringoptional
A name for a source without a URL (a park leaflet, a phone call with the operator), at most 200 characters.
- kindstringoptional
page, api, archive, document or other.
pageapiarchivedocumentother - capturedOnstringoptional
The day the source was read (YYYY-MM-DD).
- notestringoptional
What the source says or why it was chosen, at most 500 characters.
- supportsarray of stringsoptional
Which facts it backs, up to 12 entries of at most 60 characters (fees, arrival.operating, lat/lon).
- conflictbooleanoptional
true when this source disagrees with another on the facts it backs. Say which one the value follows in note or
reviewNotes.
- mapStyleobject or nullrequired
The map's style, set in the studio.
Show 3 fieldsHide fields
- basemapstringoptional
The base map style.
- pinStylestringoptional
The pin style.
- themeColorstringoptional
The accent color.
- propertySchemaVersionnumber or nullrequired
Bumped on every property change.
Custom property definitions.
Show 12 fieldsHide fieldsof Property
- propertyDefIdstring · property idrequired
The property's id.
- keystringrequired
The immutable key spots use in
customValues. - labelstringrequired
The label buyers see.
- kindstringrequired
The kind; it decides the value's type and whether buyers can filter by it.
shortLabellongSectionnumberdatecheckboxsingleSelect - ordernumberrequired
Display order (ascending).
- requiredbooleanoptional
true when every spot must carry a value. Absent means false.
- filterablebooleanrequired
Whether buyers can filter by it (number, date, checkbox and
singleSelect). - placeholderstring or nullrequired
Editor placeholder text.
- numUnitstring or nullrequired
Unit label for number properties.
- optionsarray of objectsrequired
Options of checkbox and
singleSelectproperties.Show 4 fieldsHide fields
- idstringrequired
The option's immutable id: the value spots store.
- labelstringrequired
The option's label.
- ordernumberrequired
Display order (ascending).
- archivedbooleanrequired
true when the option is retired; stored values stay.
- archivedbooleanrequired
true when the property is archived; stored values stay.
- schemaVersionnumberrequired
The guide's property schema version after the last change.
- priceobject or nullrequired
The active one-time price, or null when none is set.
Show 2 fieldsHide fields
- amountMinornumberrequired
The price in minor units (2900 is 29.00).
- currencystringrequired
ISO 4217 code in lower case (usd, eur, chf).
- spotCountnumberrequired
Number of spots, archived ones included.
- thumbnailUrlstring or nullrequired
The 4:5 store thumbnail.
- dashboardUrlstringrequired
The guide in the studio.
- salesPageUrlstringrequired
The public sales page (live once published).
{
"productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
"name": "American West: Parks at First Light",
"slug": "american-west-first-light",
"headline": null,
"purchaseButtonText": null,
"status": "draft",
"visibleOnStore": false,
"storeReviewStatus": null,
"storeReviewNote": null,
"storeTags": [],
"country": null,
"reviewsShown": true,
"buyerCountShown": false,
"pricing": {
"oneTimeEnabled": true,
"subscriptionIncluded": false,
"currency": "usd"
},
"originalLanguage": "en",
"createdAt": 1789895640000,
"updatedAt": 1789895640000,
"publishedAt": null,
"lastApiWriteAt": null,
"region": null,
"areas": [],
"mapStyle": null,
"propertySchemaVersion": 1,
"properties": [],
"price": null,
"spotCount": 0,
"thumbnailUrl": null,
"dashboardUrl": "https://creators.sceniq.earth/products/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
"salesPageUrl": "https://sceniq.earth/mara-lindgren/american-west-first-light"
}Errors
Every error is { error: { code, message } }. Act on the code.
- 400invalid_argumentA required field is missing, a field is unknown, or a value does not match its type (the Convex validator's path and value are in the message).
- 400invalid_requestA writer refused a value: a map link on a host that is not allowed, a title that is too long, a date that does not exist, too many items in a list. The message is the writer's own sentence.
- 401unauthenticatedThe request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key).
- 401invalid_api_keyThe key is unknown, revoked or expired.
- 403api_scope_requiredA read-only key called a write operation, or a key without the publish option called publish_changes.
- 403forbiddenThe key belongs to a creator account that is no longer active.
- 413payload_too_largeA JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB.
- 429rate_limitedOver a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour.
- 500internal_errorAn unexpected failure. The message is hidden on purpose.