Compatibility and versioning

Stable surfaces

• MCP endpoint: https://betterstood.com/api/mcp.
• Scenario export format: elicitra.scenario.v1.
• Webhook event types end in .v1.
• The current machine contract lives under /developers/v14/ and is byte-immutable after publication.
• The previous /developers/v1/ through /developers/v13/ trees remain available and byte-immutable; no sunset is currently scheduled.
• Webhook contracts are published as AsyncAPI 3.0.0 (document version 1.1.0).

MCP protocol negotiation is separate from Betterstood contract versioning. The hosted server is stateless: it creates a fresh protocol server per POST and never returns Mcp-Session-Id.

Every published version tree is immutable. Consumers should ignore unknown JSON object properties when reading output, but must send inputs that match the current published closed schemas. Any contract-field addition or descriptive copy change is published under a parallel version before runtime starts returning it.

The unversioned MCP endpoint advertises and serves the v14 MCP runtime contract. It updates the public descriptions to Betterstood and preserves the v13 account contract. It includes the payg plan in elicitra_account_info, with one member, Growth self-service features, 25 scenarios, 1,000 campaigns, and five PATs/webhooks. PAYG has no monthly credit grant or renewal; metered execution uses purchased credits, while Growth beta AI allowances are included. It retains brand in Campaign theme.fontPreset in draft-update inputs and campaign outputs, selecting the shared Betterstood typography. It keeps the same fourteen-tool allowlist and represents unlimited Scale scenario capacity as null in elicitra_account_info.usage.scenarios.limit, matching the campaign-limit convention. Clients must handle null before numeric comparisons or displaying remaining capacity. Growth retains its 25-scenario limit. It retains the v10 poppins Campaign font value. It retains the v9 true form-first multi_select Scenario fields with 2–20 stable option objects and ordered array values, the v8 PUBLISH_VOICE_TIER_UNAVAILABLE Campaign review result, and the v7 RESOURCE_LOCKED and optional expectedRevision error metadata. Both initialize.serverInfo.version and elicitra_get_started.contractVersion are v14. Versioned directories are pinned machine artifacts, not alternate MCP routes. Webhook event type suffixes (.v1), HMAC signature entries (v1=), and the elicitra.scenario.v1 export format are independent protocols.

The assistant-name schema addition and fourth public event required the parallel v6 artifact tree because v5 is immutable. V6 kept the hosted v5 MCP runtime and the three lifecycle subscriptions unchanged until a later runtime migration while adding the non-subscribable com.elicitra.automation.triggered.v1 conditional-destination event. The later v7 tree is the shared-resource MCP error-contract migration, v8 is the Campaign voice-plan readiness migration, v9 is the true multi-select Scenario field migration, v10 adds the Poppins Campaign font value, v11 makes the scenario capacity limit nullable for Scale, v12 adds the Brand Campaign font value, and v13 adds prepaid PAYG account access, and v14 updates the Betterstood display copy without adding tools or changing access; all preserve the webhook inventory.

Existing lifecycle deliveries remain pinned to their v5 dataschema URLs, so a consumer that validates the immutable URL continues to receive the same contract. Only com.elicitra.automation.triggered.v1 uses the v6 dataschema; the v14 tree republishes all unchanged webhook schemas for discovery without changing emitted CloudEvent URLs.

Active MCP and documentation destinations use https://betterstood.com. CloudEvent source remains https://elicitra.eigen.rest, and dataschema retains its published https://elicitra.eigen.rest/developers/v5/ or /v6/ identity. These are immutable wire identifiers, independent of HTTP routing. Download pinned schemas from https://betterstood.com/developers/v5/ or /v6/ at the same schema path; preserve the downloaded bytes, original $id and event identity. Queued events retain their original bytes and signature inputs. This does not require the legacy host to remain online.

The versioned manifest.json publishes a deterministic sha256: digest for every MCP input/output and webhook data schema. Consumers can use those hashes to pin reviewed contracts and detect accidental artifact drift.

An incompatible change introduces a parallel version. Betterstood retains the previous public tool/event artifacts for at least 180 days. If a version is deprecated, its deprecation and sunset dates are published here and in the changelog before removal.

Runtime brand identifiers

The rebrand does not rename published tool names, PATs, export formats, webhook types or the elicitra-signature header. Keep using elicitra_get_started, elicitra_account_info and elicitra_knowledge_search. The server advertises betterstood-developer-access; existing client entries named elicitra and environment references to ELICITRA_MCP_TOKEN remain valid. New setup examples use betterstood and BETTERSTOOD_MCP_TOKEN.

HTTP request headers accept both x-betterstood-* and the corresponding x-elicitra-* names for locale, test/poll/web tokens and call/session/device identifiers. A supplied canonical value takes precedence, even if invalid. Release/runtime identity responses include both names; health responses omit both. Existing authentication and endpoint permissions are unchanged.

Legacy aliases have no automatic expiry. Retirement requires all dependencies migrated or decommissioned and verified, plus separate approval in LINEAR-736. The published minimum artifact overlap above is a floor, not an alias sunset. The application records legacy header/cookie family names without values; MCP telemetry retains the requested stable tool name and outcome. Traffic silence alone does not permit removal. No additional metered operation is added.

Client support

Betterstood tests the current stable Codex CLI/IDE extension, Claude Code, and Cursor against staging before GA and after transport changes. A client is listed as supported only if it can:

1. send an environment-backed bearer token;
2. negotiate stateless Streamable HTTP without GET/session requirements;
3. list the correct scope-filtered tools;
4. complete the draft workflow without storing the PAT in the project.

If a client release cannot meet those invariants, the release is marked temporarily unsupported; Betterstood does not weaken tenant, auth, or stateless transport controls to accommodate it.