set_area

Create an area, or replace one area's content.

PUT/v1/guides/{productId}/areas

MCP tool set_areaScope: writeBetaSince 2026-09-30

Rules that apply to a whole park, island or region (Yellowstone's fee and road season, Rapa Nui's entry form, Tibet's permit) live once here; spots point at it with update_spot areaId and buyers see it on each spot. Without areaId this creates an area and returns its id; with areaId every field is replaced (fields you leave out are cleared). At most 50 per guide.

curl -X PUT "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/areas" \
  -H "Authorization: Bearer $SCENIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Yellowstone National Park",
  "kind": "park",
  "note": "One entrance pass covers every spot in the Yellowstone chapter. Cell coverage is patchy between the geyser basins; download the guide before you drive in.",
  "season": "Most park roads are open to cars from May to early November.",
  "rules": [
    {
      "text": "Stay on boardwalks and marked trails in every thermal area.",
      "kind": "other",
      "sourceUrl": "https://www.nps.gov/yell/planyourvisit/safety.htm"
    }
  ],
  "fees": [
    {
      "label": "Park entrance, private vehicle, 7 days",
      "amount": 35,
      "currency": "USD",
      "per": "vehicle",
      "paidWhere": "online",
      "sourceUrl": "https://www.nps.gov/yell/planyourvisit/fees.htm",
      "checkedOn": "2026-09-20"
    }
  ],
  "links": [
    {
      "kind": "official",
      "url": "https://www.nps.gov/yell/index.htm",
      "label": "Yellowstone National Park (NPS)"
    },
    {
      "kind": "status",
      "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
      "label": "Park road status"
    }
  ],
  "sources": [
    {
      "url": "https://www.nps.gov/yell/planyourvisit/fees.htm",
      "kind": "page",
      "capturedOn": "2026-09-20",
      "supports": [
        "fees"
      ]
    }
  ]
}'

Path parameters

productIdstring · guide idrequired
Id of the guide (a product of type map). From list_guides or create_guide.

Body parameters

namestringrequired
The area's name, at most 100 characters, e.g. Yellowstone National Park.
areaIdstringoptional
The area to replace (from list_areas); omit to create one.
feesarray of Feeoptional
Fees and tickets, full replacement ([] clears), at most 30: [{ label, amount? (major units, e.g. 40 or 12.5; needs currency), currency? (EUR), free?, seeOfficial? (a price left to the official page on purpose), per?: person|vehicle|night|group|entry|day|hour, audience?: all|adult|child|foreign|domestic|resident|student|senior, paidWhere?: online|on_site|in_tour, payment?: cash_only|card_only|cash_or_card, note?, validFrom?, validUntil?, sourceUrl?, checkedOn? }]. Buyers see the amount with an as-of date; readiness flags rows past validUntil or unchecked for a year.
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_site or in_tour (part of a tour price).
  onlineon_sitein_tour
- paymentstringoptional
  How it can be paid: cash_only, card_only or cash_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).
kindstringoptional
park, reserve, island, region, city or other.
parkreserveislandregioncityother
linksarray of GuideLinkoptional
Links with a purpose, full replacement ([] clears), at most 12: [{ kind: official|website|tickets|booking|status|timetable|tide|listing|social|authority|app|other, label?, url? (http or https; http is accepted with a warning), value? (a channel that is not a URL, e.g. WeChat mini program: Li River boats), note? }]. Each needs a url or a value.
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.
notestringoptional
What applies across the area, in the creator's words, at most 1,000 characters.
rulesarray of AccessRuleoptional
[{ text, kind?, months?, appliesTo?, bookingOpens?, sourceUrl? }], as arrival.rules.
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).
seasonstringoptional
The area's season in words, at most 300 characters (roads open May to October).
sourcesarray of SourceRefoptional
Research evidence for reviewers, never shown to buyers; full replacement, at most 40: [{ url? or title?, kind?: page|api|archive|document|other, capturedOn?, note?, supports? (which facts it backs, e.g. fees, arrival.operating, lat/lon), conflict? (true when it disagrees with another source on those facts) }].
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.
statusStatusNoticeoptional
Closure or works notice for the whole area: { state: open|partly_closed|closed|reopening, note?, since?, until?, sourceUrl?, checkedOn? }. set_area replaces every field, so leave it out to clear it (null is not accepted).
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).

Returns

200 OK with this object.

productIdstring · guide idrequired
The guide's id.
createdbooleanrequired
true when this call created the area.
areaAreaWithSpots or nullrequired
The area as stored.
Show 11 fieldsHide fieldsof AreaWithSpots
- idstringrequired
  The area's id.
- namestringrequired
  The area's name.
- kindstringoptional
  park, reserve, island, region, city or other.
  parkreserveislandregioncityother
- notestringoptional
  What applies across the area.
- seasonstringoptional
  The area's season in words.
- rulesarray of AccessRuleoptional
  Access rules for the whole area.
  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).
- feesarray of Feeoptional
  Fees for the whole area.
  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_site or in_tour (part of a tour price).
  onlineon_sitein_tour
  paymentstringoptional
  How it can be paid: cash_only, card_only or cash_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).
- linksarray of GuideLinkoptional
  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.
- statusStatusNoticeoptional
  A closure 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).
- sourcesarray of SourceRefoptional
  Research evidence, 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.
- spotKeysarray of stringsrequired
  The spots that point at the area (update_spot areaId).
warningsarray of stringsoptional
Notes about things the write accepted but you should look at (a plain http link). Present only when there are any.

Response 200

{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "created": true,
  "area": {
    "id": "area_01m3gvdap06m6mx2kp4t553d6g",
    "name": "Yellowstone National Park",
    "kind": "park",
    "note": "One entrance pass covers every spot in the Yellowstone chapter. Cell coverage is patchy between the geyser basins; download the guide before you drive in.",
    "season": "Most park roads are open to cars from May to early November.",
    "rules": [
      {
        "text": "Stay on boardwalks and marked trails in every thermal area.",
        "kind": "other",
        "sourceUrl": "https://www.nps.gov/yell/planyourvisit/safety.htm"
      }
    ],
    "fees": [
      {
        "label": "Park entrance, private vehicle, 7 days",
        "amount": 35,
        "currency": "USD",
        "per": "vehicle",
        "paidWhere": "online",
        "sourceUrl": "https://www.nps.gov/yell/planyourvisit/fees.htm",
        "checkedOn": "2026-09-20"
      }
    ],
    "links": [
      {
        "kind": "official",
        "url": "https://www.nps.gov/yell/index.htm",
        "label": "Yellowstone National Park (NPS)"
      },
      {
        "kind": "status",
        "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
        "label": "Park road status"
      }
    ],
    "sources": [
      {
        "url": "https://www.nps.gov/yell/planyourvisit/fees.htm",
        "kind": "page",
        "capturedOn": "2026-09-20",
        "supports": [
          "fees"
        ]
      }
    ],
    "spotKeys": []
  }
}

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.
404not_foundThe id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists.
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.

curl -X PUT "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/areas" \
  -H "Authorization: Bearer $SCENIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Yellowstone National Park",
  "kind": "park",
  "note": "One entrance pass covers every spot in the Yellowstone chapter. Cell coverage is patchy between the geyser basins; download the guide before you drive in.",
  "season": "Most park roads are open to cars from May to early November.",
  "rules": [
    {
      "text": "Stay on boardwalks and marked trails in every thermal area.",
      "kind": "other",
      "sourceUrl": "https://www.nps.gov/yell/planyourvisit/safety.htm"
    }
  ],
  "fees": [
    {
      "label": "Park entrance, private vehicle, 7 days",
      "amount": 35,
      "currency": "USD",
      "per": "vehicle",
      "paidWhere": "online",
      "sourceUrl": "https://www.nps.gov/yell/planyourvisit/fees.htm",
      "checkedOn": "2026-09-20"
    }
  ],
  "links": [
    {
      "kind": "official",
      "url": "https://www.nps.gov/yell/index.htm",
      "label": "Yellowstone National Park (NPS)"
    },
    {
      "kind": "status",
      "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
      "label": "Park road status"
    }
  ],
  "sources": [
    {
      "url": "https://www.nps.gov/yell/planyourvisit/fees.htm",
      "kind": "page",
      "capturedOn": "2026-09-20",
      "supports": [
        "fees"
      ]
    }
  ]
}'

Response 200

{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "created": true,
  "area": {
    "id": "area_01m3gvdap06m6mx2kp4t553d6g",
    "name": "Yellowstone National Park",
    "kind": "park",
    "note": "One entrance pass covers every spot in the Yellowstone chapter. Cell coverage is patchy between the geyser basins; download the guide before you drive in.",
    "season": "Most park roads are open to cars from May to early November.",
    "rules": [
      {
        "text": "Stay on boardwalks and marked trails in every thermal area.",
        "kind": "other",
        "sourceUrl": "https://www.nps.gov/yell/planyourvisit/safety.htm"
      }
    ],
    "fees": [
      {
        "label": "Park entrance, private vehicle, 7 days",
        "amount": 35,
        "currency": "USD",
        "per": "vehicle",
        "paidWhere": "online",
        "sourceUrl": "https://www.nps.gov/yell/planyourvisit/fees.htm",
        "checkedOn": "2026-09-20"
      }
    ],
    "links": [
      {
        "kind": "official",
        "url": "https://www.nps.gov/yell/index.htm",
        "label": "Yellowstone National Park (NPS)"
      },
      {
        "kind": "status",
        "url": "https://www.nps.gov/yell/planyourvisit/conditions.htm",
        "label": "Park road status"
      }
    ],
    "sources": [
      {
        "url": "https://www.nps.gov/yell/planyourvisit/fees.htm",
        "kind": "page",
        "capturedOn": "2026-09-20",
        "supports": [
          "fees"
        ]
      }
    ],
    "spotKeys": []
  }
}