🏠properties_listRead

List all host properties with status and configuration details.

Click to expand parameters →

No parameters required.

🏠properties_get_analyticsRead

Revenue and occupancy analytics for your portfolio over a configurable period.

Click to expand parameters →

period_daysintegerLookback period in days (7–90).

👤guests_queryRead

Query guest CRM records with spend and stay filters. Read-only — does not create folders or campaigns.

Click to expand parameters →

limitintegerMax results (1–12).

min_spendnumberMinimum total spent (currency-agnostic).

min_spend_brlnumberMinimum total spent in BRL.

min_staysintegerMinimum completed stays.

👤guests_get_profileRead

Full guest profile with loyalty status and stay history summary.

Click to expand parameters →

guest_iduuidrequiredGuest UUID.

👤guests_get_segment_summaryRead

Aggregate guest segment counts by spend bracket and repeat status.

Click to expand parameters →

No parameters required.

👤guests_tagWrite

Apply up to 12 operational tags to one guest record. Does not create folders.

Click to expand parameters →

guest_iduuidTarget guest.

tagsstring[]Array of tag labels (max 12).

👤guests_create_folderWrite

Create a CRM guest folder (manual segment). Idempotent — returns existing folder if name matches.

Click to expand parameters →

namestringFolder name (1–80 chars).

descriptionstringFolder description (max 240 chars).

color_hexstringFolder color as hex.

👤guests_add_to_folderWrite

Add up to 12 guests to an existing CRM folder. Call after guests_create_folder.

Click to expand parameters →

folder_iduuidTarget folder.

guest_idsuuid[]Array of guest UUIDs (1–12).

👤guests_list_foldersRead

List all CRM guest folders (manual segments) with member counts.

Click to expand parameters →

No parameters required.

👤guests_get_message_historyRead

View a guest's full communication history across email, WhatsApp, and SMS.

Click to expand parameters →

guest_iduuidrequiredTarget guest.

channelenumemail | whatsapp | sms | all

limitintegerMax messages (1–50).

sincedatetimeISO 8601 cutoff date.

📅reservations_listRead

List recent reservations across your portfolio.

Click to expand parameters →

limitintegerMax results (1–12).

statusstringFilter by booking status.

📅reservations_check_availabilityRead

Check if a property is available for a specific date window.

Click to expand parameters →

property_idstringTarget property.

check_indateArrival date (YYYY-MM-DD).

check_outdateDeparture date (YYYY-MM-DD).

📅reservations_get_gap_nightsRead

Identify orphan gap nights between bookings — short vacant windows ripe for targeted offers.

Click to expand parameters →

property_idstringSpecific property (optional — all if omitted).

horizon_daysintegerLookahead window (7–90 days).

📅reservations_create_reservationWrite

Create a manual reservation hold on a property calendar.

Click to expand parameters →

property_idstringTarget property.

guest_emailemailGuest email address.

check_indateArrival date.

check_outdateDeparture date.

📅reservations_create_quoteWrite

Prepare a stay quote for host review. No calendar hold is placed.

Click to expand parameters →

No parameters required.

📧campaigns_create_email_campaignAsync

Create an email campaign draft with full HTML body, merge fields, and audience targeting. Never sends — always starts as a draft.

Click to expand parameters →

subjectstringrequiredEmail subject line (5–200 chars).

body_htmlstringrequiredFull HTML email body with merge fields like {{guest_name}}.

preheaderstringInbox preview text.

cta_urlurlCTA button destination URL.

cta_labelstringCTA button text (max 60 chars).

guest_folder_iduuidTarget audience folder.

namestringInternal campaign label.

goalstringCampaign objective metadata.

📧campaigns_create_whatsapp_campaignAsync

Create a WhatsApp campaign draft via AI. Runs as an async job.

Click to expand parameters →

goalstringCampaign objective for AI generation.

📧campaigns_send_campaignApproval

Send a prepared campaign to its target audience. Requires approval token.

Click to expand parameters →

campaign_iduuidCampaign to send.

approval_tokenstringShort-lived approval token.

📧campaigns_send_to_guestApproval

Send a campaign or custom message to a single guest. Supports merge variables and subject/body overrides.

Click to expand parameters →

guest_iduuidrequiredTarget guest.

approval_tokenstringrequiredScope-locked approval token.

campaign_iduuidCampaign template to use.

channelenumemail | whatsapp

merge_varsobjectCustom merge variables.

override_subjectstringOverride the campaign subject.

override_bodystringOverride the campaign body.

💬messaging_get_or_create_threadWrite

Get or create a messaging thread for a guest on WhatsApp, SMS, or email.

Click to expand parameters →

guest_iduuidrequiredTarget guest.

channelenumwhatsapp | sms | email

create_if_missingbooleanCreate thread if none exists.

💬messaging_prepare_whatsapp_messageWrite

Draft a WhatsApp message for host review. Does not send.

Click to expand parameters →

thread_iduuidWhatsApp thread.

messagestringMessage content (max 4096 chars).

💬messaging_send_whatsapp_messageApproval

Send a WhatsApp message to a guest. Requires approval token.

Click to expand parameters →

thread_iduuidTarget thread.

messagestringMessage content (max 4096 chars).

approval_tokenstringApproval token.

💬transactional_email_sendApproval

Send a transactional email to one guest via Resend. Requires approval token when send_immediately=true. Respects guest unsubscribe status.

Click to expand parameters →

to_emailemailrequiredRecipient email.

subjectstringrequiredEmail subject (max 200 chars).

body_htmlstringrequiredHTML email body.

to_namestringRecipient display name.

body_textstringPlain text fallback.

reply_toemailReply-to address.

merge_varsobjectTemplate variables.

approval_tokenstringRequired for immediate send.

send_immediatelybooleanSend now (vs queue).

allow_externalbooleanAllow non-CRM recipients.

📸content_create_instagram_postAsync

Queue an Instagram carousel in SparkOS Studio. Supports 2–10 slides with title, subtitle, body, and image URL. Never publishes — host reviews and approves in Studio.

Click to expand parameters →

property_idstringrequiredProperty to associate.

captionstringInstagram caption (20–2200 chars).

slidesobject[]2–10 slides: { title, subtitle?, body?, image_url? }

goalstringContent objective.

themestringLegacy — auto-builds slides when slides[] is omitted.

schedule_days_outintegerAuto-schedule days ahead (1–30).

📸content_schedule_instagram_postApproval

Schedule a queued Instagram post for publication. Requires approval token.

Click to expand parameters →

post_iduuidPost to schedule.

scheduled_atdatetimePublication time (ISO 8601).

approval_tokenstringApproval token.

📊analytics_analyze_portfolioAsync

Deep AI-powered portfolio analysis. Runs as an async job — poll jobs_get_status for results.

Click to expand parameters →

No parameters required.

📊analytics_forecast_revenueAsync

AI-powered revenue forecast over a configurable horizon. Async job.

Click to expand parameters →

horizon_daysintegerForecast horizon (30–365 days).

⭐loyalty_get_tier_summaryRead

Guest count per loyalty tier across your portfolio.

Click to expand parameters →

No parameters required.

⭐loyalty_get_guest_tierRead

Get the current loyalty tier for a specific guest.

Click to expand parameters →

guest_iduuidTarget guest.

⭐loyalty_update_guest_tierApproval

Update a guest's loyalty tier. Requires approval token.

Click to expand parameters →

guest_iduuidTarget guest.

tier_iduuidNew loyalty tier.

approval_tokenstringApproval token.

⚡automation_create_ruleWrite

Create an automation rule draft. Requires approval token.

Click to expand parameters →

namestringRule name.

triggerstringEvent trigger.

approval_tokenstringApproval token.

⚡automation_activateApproval

Enable, trigger once, or test an automation rule.

Click to expand parameters →

rule_iduuidrequiredTarget rule.

activation_modeenumrequiredenable | trigger_once | test

approval_tokenstringRequired for enable/trigger_once.

target_guest_iduuidGuest for trigger_once/test.

💳payments_create_payment_linkWrite

Create a secure payment link draft tied to a reservation. Requires approval token.

Click to expand parameters →

reservation_iduuidAssociated reservation.

amountnumberPayment amount.

approval_tokenstringApproval token.

🔐approval_token_requestWrite

Mint a short-lived, scope-locked approval token for Tier 3 actions (campaign send, WhatsApp, transactional email, automation).

Click to expand parameters →

action_typeenumrequiredcampaign_send | campaigns_send_to_guest | automation_activate | whatsapp_send | transactional_email

reasonstringrequiredHuman-readable justification (3–500 chars).

scopeobjectOptional scope constraints.

ttl_secondsintegerToken lifetime (60–600 seconds).

⏳jobs_get_statusRead

Poll async job status and result. Required after any async tool — do not mark tasks complete until status=completed.

Click to expand parameters →

job_iduuidJob UUID from the initial call.

🤝marketplace_get_partnersRead

List Spark Nearby local partner businesses for your properties.

Click to expand parameters →

No parameters required.

SparkOS Documentation

What is SparkOS?

🏠 Property Management

👤 Guest CRM

📧 Multi-Channel Campaigns

💬 Direct Messaging

📊 AI Analytics

📸 Studio (Content)

Quickstart Guide

Connect SparkOS in Claude

Explore Your Properties

Query Your Guests

Create a Campaign

Understand the Approval System

All 36 Tools

🏠 Property Management

👤 Guest Management

📅 Reservation Operations

📧 Email & WhatsApp Campaigns

💬 Direct Messaging

📸 Content Creation

📊 Analytics & Forecasting

⭐ Loyalty Program

⚡ Automation Rules

💳 Payment Links

Key Concepts

🔐 Approval Tokens

⏳ Async Jobs

📂 Guest Folders

🏷️ Tags vs Folders

📨 Merge Fields

💰 Currency Filters

🔄 Transactional vs Campaign Email

📅 Gap Nights

🤝 Spark Nearby