Skip to content
Betterstood Developers

Developer contract changelog

Documentation

Section titled “Documentation”

Current hosted-runtime compatibility notice

Section titled “Current hosted-runtime compatibility notice”
  • Public contract v14 still includes operations[].set_intake.intake.quickAnswers.enabled for schema compatibility. When the optional quickAnswers envelope is supplied, enabled remains required by the v14 schema but the hosted runtime ignores its value; the linked Scenario’s form-first field plan determines whether every compatible Voice Campaign uses the hosted form-first journey. Omit the envelope unless changing its localized label. This compatibility behavior does not replace or disable the active Scenario’s required_disclaimer, which the hosted runtime preserves and includes in the journey.
  • campaign_get reports the derived quickAnswers.enabled state for v14 clients. It is compatibility output, not a Campaign-level activation switch.

v14 — Betterstood contract copy

Section titled “v14 — Betterstood contract copy”
  • Updated MCP workflow, server instructions, product-reference descriptions, assistant identity descriptions and credit examples to use Betterstood. Updated the AsyncAPI title and description consistently.
  • Advanced the hosted runtime and elicitra_get_started.contractVersion to v14 and published the parallel /developers/v14/ tree. Every previously published /developers/v1/ through /developers/v13/ artifact remains byte-immutable and available with no scheduled sunset.
  • Kept all fourteen tool names, PATs, scopes, entitlements, quotas, 0-credit MCP operations, export formats, webhook types, signature headers and emitted v5/v6 dataschema URLs unchanged. AsyncAPI remains specification 3.0.0, document version 1.1.0.
  • Regenerated the current reference guides, agent bootstrap, its agent.md compatibility alias and LLM documents from the v14 contract sources.

v13 — prepaid PAYG account access

Section titled “v13 — prepaid PAYG account access”
  • Added payg to elicitra_account_info and PAYG to Developer Access availability: one member, 25 scenarios, 1,000 campaigns, five active PATs and five webhook endpoints.
  • PAYG includes Growth self-service capabilities and bounded beta AI allowances. Ordinary MCP configuration stays at 0 credits; metered respondent execution requires spendable prepaid credits. No subscription, automatic renewal, or monthly credit grant is created.
  • Advanced the hosted contract to v13 and published /developers/v13/, preserving v1-v12 artifacts byte-for-byte. The fourteen tools, scopes, webhook payloads, emitted v5/v6 dataschema URLs, and AsyncAPI document version 1.1.0 are unchanged.

v12 — Brand campaign font contract

Section titled “v12 — Brand campaign font contract”
  • Added brand to the allowed Campaign theme.fontPreset values in draft-update inputs and campaign outputs, selecting the shared Betterstood typography.
  • Advanced the hosted runtime and elicitra_get_started.contractVersion to v12 and published /developers/v12/, preserving all v1-v11 artifacts byte-for-byte with no scheduled sunset.
  • The fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit draft authoring are unchanged. Webhook payloads and emitted v5/v6 dataschema URLs remain unchanged; AsyncAPI document version stays 1.1.0.

v11 — unlimited Scale scenarios

Section titled “v11 — unlimited Scale scenarios”
  • Scale now includes unlimited stored scenarios in Studio and governed MCP draft creation. Growth retains its 25-scenario quota; deleted scenarios do not consume capacity.
  • elicitra_account_info.usage.scenarios.limit is now nullable: null means unlimited on Scale, matching the existing campaign-limit convention. Clients must handle null before numeric comparisons or displaying a remaining count.
  • Advanced the hosted runtime and elicitra_get_started.contractVersion to v11 and published /developers/v11/, preserving all v1-v10 artifacts byte-for-byte with no scheduled sunset.
  • The fourteen-tool allowlist, scopes, AI Copilot allowances, and 0-credit draft authoring are unchanged. Webhook payloads and emitted v5/v6 dataschema URLs remain unchanged; AsyncAPI document version stays 1.1.0.

v10 — Poppins campaign font contract

Section titled “v10 — Poppins campaign font contract”
  • Added poppins to the allowed Campaign theme.fontPreset values in draft-update inputs and campaign outputs, exposing the font already supported by campaign customization.
  • Advanced the unversioned hosted MCP runtime and elicitra_get_started.contractVersion to v10 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
  • Published the parallel /developers/v10/ artifact tree and preserved /developers/v1/ through /developers/v9/ byte-for-byte with no scheduled sunset.
  • Kept all four webhook events and payloads unchanged, with lifecycle dataschema URLs pinned to v5 and conditional-automation dataschema URLs pinned to v6; v10 republishes those unchanged webhook schemas for discovery and keeps AsyncAPI document version 1.1.0.

v9 — true multi-select scenario fields

Section titled “v9 — true multi-select scenario fields”
  • Added multi_select to the governed Scenario field contract used by create, update, get, review, and export operations. It is form-first-only, requires 2–20 stable { value, label } options, and preserves simultaneous selections as ordered arrays.
  • Advanced the unversioned hosted MCP runtime and elicitra_get_started.contractVersion to v9 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
  • Published the parallel /developers/v9/ artifact tree and preserved /developers/v1/ through /developers/v8/ byte-for-byte with no scheduled sunset.
  • Kept lifecycle webhook dataschema URLs pinned to v5 and conditional-automation dataschema URLs pinned to v6; v9 republishes those unchanged webhook schemas for discovery.

v8 — voice-plan publish readiness

Section titled “v8 — voice-plan publish readiness”
  • Added PUBLISH_VOICE_TIER_UNAVAILABLE to Campaign draft review results so an integration can distinguish a plan upgrade requirement from caller-number remediation before a human publishes a voice campaign.
  • Advanced the unversioned hosted MCP runtime and elicitra_get_started.contractVersion to v8 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
  • Published the parallel /developers/v8/ artifact tree and preserved /developers/v1/ through /developers/v7/ byte-for-byte with no scheduled sunset.
  • Kept lifecycle webhook dataschema URLs pinned to v5 and conditional-automation dataschema URLs pinned to v6; v8 republishes those unchanged webhook schemas for discovery.

v7 — shared-resource edit contention

Section titled “v7 — shared-resource edit contention”
  • Added RESOURCE_LOCKED for Scenario and Campaign mutations that contend with an active editor lease. Clients must wait for release or expiry and then read the latest revision before retrying; there is no automatic takeover.
  • Added optional expectedRevision to the common public error object so revision conflicts can report both the attempted and current revisions.
  • Advanced the unversioned hosted MCP runtime and elicitra_get_started.contractVersion to v7 while keeping the same fourteen-tool allowlist, Growth/Scale entitlement, scopes, quotas, and 0-credit authoring behavior.
  • Published the parallel /developers/v7/ artifact tree and preserved /developers/v1/ through /developers/v6/ byte-for-byte with no scheduled sunset.
  • Kept lifecycle webhook dataschema URLs pinned to v5 and conditional-automation dataschema URLs pinned to v6; v7 republishes those unchanged webhook schemas for discovery.

v6 — conditional automation destination

Section titled “v6 — conditional automation destination”
  • Added optional definition.assistantName plus set_metadata.assistantName; null clears the identity-label override while Betterstood keeps AI identity and recording/transcription wording server-owned.
  • Added com.elicitra.automation.triggered.v1 with a fixed, data-minimized analysis and activation payload.
  • Added deliveryMode metadata to distinguish the three unchanged lifecycle_subscription events from the new conditional_destination event. Automation is not subscribable and omits lifecycleSequence.
  • Published the assistant-name schema addition in the parallel v6 tree while the hosted public MCP runtime remained pinned to v5 until a later runtime migration. The fourteen-tool allowlist and three-event lifecycle subscription inventory stayed unchanged.
  • Published AsyncAPI 3.0.0 document version 1.1.0 and the parallel /developers/v6/ artifact tree.
  • Preserved /developers/v1/ through /developers/v5/ byte-for-byte with no scheduled sunset.

v5 — bilingual Betterstood product knowledge

Section titled “v5 — bilingual Betterstood product knowledge”
  • Added the read-only elicitra_knowledge_search tool for customer-safe product concepts, campaigns, credits, pricing tiers, and use cases in en-US or it-IT.
  • Kept the existing scenario:read scope, Growth/Scale entitlement, shared rate limits, and 0-credit weight; read PATs now expose 10 tools and full PATs expose 14.
  • Kept product-reference search separate from organization scenario Knowledge Base administration and respondent data.
  • Published /developers/v5/ while preserving /developers/v1/ through /developers/v4/ byte-for-byte. The three webhook events and payload contracts are unchanged.

v4 — account context and campaign DRAFT authoring

Section titled “v4 — account context and campaign DRAFT authoring”
  • Expanded the public catalog from seven to thirteen tools with allowlisted account context and campaign list/get/create/update/review operations.
  • Added campaign:read and campaign:write. Legacy read and write PAT profiles gain the matching effective campaign scopes without rotation.
  • Added atomic, idempotent DRAFT campaign updates for scenario, channel, intake, and constrained theme configuration, plus deterministic review and operator handoff.
  • Added CAMPAIGN_LOCKED; kept publishing, access configuration, provider operations, live testing, and respondent data outside public MCP.
  • Published /developers/v4/, preserved /developers/v1/ through /developers/v3/ byte-for-byte, and kept all three webhook events and payloads unchanged.

v3 — Live Fit policy

Section titled “v3 — Live Fit policy”
  • Added optional definition.liveFit to scenario drafts and exports, with at most ten ordered typed gates.
  • Added the closed set_live_fit operation to create/update drafts, including explicit acknowledgement for gate removals.
  • Kept the public catalog at exactly seven tools and left webhook event types, payloads, signature syntax, and the Scenario export envelope unchanged.
  • Published /developers/v3/ as the current contract and preserved /developers/v1/ and /developers/v2/ byte-for-byte.

v2 — form-first scenario fields

Section titled “v2 — form-first scenario fields”
  • Added stable machine value plus respondent-facing label objects to public select options while continuing to accept legacy string options.
  • Published a parallel /developers/v2/ contract and made v2 the contract advertised by the hosted MCP endpoint.
  • Kept webhook event types, webhook payload shapes, HMAC signature syntax, and the Scenario export format unchanged.
  • Preserved /developers/v1/ byte-for-byte as the previous immutable contract. It is not currently scheduled for sunset.

v1 — initial public contract

Section titled “v1 — initial public contract”
  • Added hosted, stateless Streamable HTTP MCP with seven semantic scenario tools.
  • Added personal bearer PATs with scenario:read and scenario:write scopes.
  • Added signed interaction.ended, analysis.completed, and analysis.failed lifecycle webhooks.
  • Added CloudEvents envelopes, HMAC-SHA256 signatures, replay, JSON Schema, and AsyncAPI artifacts.
  • Developer Access is included in Growth and Scale at 0 incremental credits.

No public REST API is part of v1.