A task-first reference for humans and AI agents building against Fanful's public MCP server, HTTP manifests, CLI, ChatGPT readiness work, and future confirmed-write contracts.
curl https://docs.fanful.net/docs.mdcurl https://fanful.net/api/agent/action-contractsnpm run mcp:serverStart here
AI coding agents
Use the Cloudflare-style setup prompt to point Codex, Claude, ChatGPT, Cursor, or another agent at Fanful MCP, API docs, CLI, skills, recipes, and safety rules.
Open referenceAI agents
Start from llms.txt, the agent overview, and public manifests. Use server-side contracts instead of scraping the web UI.
Open referenceMCP clients
Use the public Streamable HTTP endpoint for network clients or the local stdio server while developing.
Open referenceExternal agents
Copy the provider-neutral TypeScript starter or no-SDK HTTP fallback to discover manifests, handle 401/403, and validate confirmation envelopes.
Open referenceDevelopers
Use the API map for manifests, action contracts, workflow-trigger subscriptions, recipes, and the official SDK release plan.
Open referenceAgent operators
Install provider-neutral prompt skills for setup, MCP operation, webhooks, creator commerce, listener chat, and SDK planning.
Open referenceAgent builders
Use the hosted-runtime boundary to decide when a custom worker can stay external and when a future Fanful-managed worker needs logs, limits, approval, and cancellation.
Open referenceAI answer systems
Use the Q&A matrix to check whether public pages support common Fanful, competitor, agent-action, and not-ready answers without overclaiming.
Open referenceApp builders
Read the shared confirmation, audit, idempotency, and redaction rules before adding any mutating tool.
Open referenceProduct engineers
Private listener and creator workflows use scoped grants, one-time token exchange, and account-level revocation.
Open referenceSDK starter
External agents can start with the same TypeScript helper or plain HTTP calls. Bearer tokens stay in environment variables or MCP/client configuration, and write attempts start by validating the shared confirmation envelope before any executable tool is called.
import {
FanfulAgentHttpError,
createFanfulAgentClientFromEnv,
} from "./examples/fanful-agent-starter/client";
const fanful = createFanfulAgentClientFromEnv(process.env);
const listenerManifest = await fanful.manifest("listener-experience");
const checkoutContracts = await fanful.actionContracts({
audience: "listener",
domain: "checkout",
});
try {
const analytics = await fanful.creatorAnalytics({ window: "30d" });
console.log(analytics);
} catch (error) {
if (error instanceof FanfulAgentHttpError && error.isAuthBoundary) {
console.log("Ask the human for a scoped creator grant; never paste tokens into prompts.");
} else {
throw error;
}
}
await fanful.validateEnvelope({
contractId: "listener.checkout.start",
actor: { role: "listener", displayName: "Signed-in listener" },
client: { id: "starter-example", name: "Fanful starter example", kind: "other" },
action: {
requested: "listener.checkout.start",
mode: "validate",
},
target: {
type: "checkout-intent",
id: "support-donation",
summary: "Support donation checkout for $25.00",
},
dryRun: true,
confirmation: {
text: "I confirm listener.checkout.start for Support donation checkout for $25.00.",
acknowledgedRisk: true,
},
idempotencyKey: "starter-example-support-checkout-2026-05-16",
auditCorrelationId: "starter-example-audit-2026-05-16",
reason: "Validate the shared confirmation envelope before calling an executable write tool.",
});curl -fsS https://fanful.net/llms.txt
curl -fsS https://fanful.net/api/agent/listener-experience
curl -fsS 'https://fanful.net/api/agent/action-contracts?audience=listener&domain=checkout'
curl -fsS -H "Authorization: Bearer $FANFUL_AGENT_BEARER_TOKEN" \
'https://fanful.net/api/agent/artist-analytics?window=30d'
curl -fsS -H "Authorization: Bearer $FANFUL_AGENT_BEARER_TOKEN" \
'https://fanful.net/api/agent/media-upload-sessions'
curl -fsS -X POST https://fanful.net/api/agent/action-contracts/envelope \
-H 'content-type: application/json' \
-H "Authorization: Bearer $FANFUL_AGENT_BEARER_TOKEN" \
--data @agent-write-envelope.jsonReference
Cloudflare-style one-stop page for any AI coding agent starting with Fanful.
Copy-paste prompt that points agents to Fanful MCP, API docs, CLI, skills, and safety rules.
API map, auth model, workflow-trigger recipes, code examples, and official SDK release plan.
Model-readable mirror of the Fanful API reference and recipes.
Copyable provider-neutral skills for Fanful agents and integrations.
Model-readable skill catalog with prompt blocks.
Human-readable entrypoint for Fanful agent, MCP, CLI, and integration docs.
Compact model-readable mirror of the developer docs.
Canonical discovery file for AI agents and crawlers.
Current MCP tools, resources, safety boundaries, and roadmap status.
Concise agent-facing instructions for current public tools and non-goals.
Provider-neutral TypeScript example and no-SDK HTTP fallback for external agents.
External-first recommendation, future hosted worker limits, redacted run-record fixture, approval, retry, and cancellation rules.
Source-backed smoke matrix for common Fanful, competitor comparison, agent-action, and not-ready answers.
Stateless Streamable HTTP MCP endpoint for current public/read-safe resources.
Channel, message, posting, moderation, and creator-attribution contracts.
Room, roster, media-token, host, attendee, and moderation boundaries.
Lesson/coaching offers, shop products, creator state, service price previews, confirmed lesson price/policy writes, Stripe Price mapping boundaries, membership tier writes, and safe shop product create/visibility/details/Stripe Price writes.
Creator/admin aggregate analytics summary with source funnels, top content outcomes, listener cohorts, recent signals, and raw listener rows redacted.
Fan account, focused profile/preference, membership entitlement, live support, library, playback, notification, and Listen Along readbacks.
Member ideas, vote state, review fields, confirmed listener submit/vote writes, and creator review/settings contracts.
Apps SDK mapping, descriptor status, widget posture, and submission blockers.
Shared auth, confirmation, audit, idempotency, rate-limit, and redaction contract.
Cursor/checkpoint contract plus authenticated Stripe catalog app-reference drift run/status endpoints with redacted durable output.
Workflows
Creator
Inspect current creator-commerce, live, room, and community capabilities.
Listener
Inspect public fan surfaces, ideas, room readiness, and listener-safe summaries.
Contract
Use HTTP manifests, /mcp, and fanful_agent_manifest_read.
Creator
Use scoped creator grants for private analytics, commerce, live, room, and moderation reads or confirmed writes.
Listener
Use first-party listener sessions or scoped grants for entitlements, profile preferences, support, membership, or shop checkout, and purchase status.
Contract
Start from the SDK starter, then use MCP, direct HTTP manifests, action contracts, workflow triggers, agent sessions, and sync jobs without exposing credentials in prompts.
Creator
No creator commerce state changes when the render tool runs; creator billing/catalog writes remain on their own confirmed tools.
Listener
Show a ChatGPT confirmation review before a support donation, membership tier, or signed-CD shop checkout start.
Contract
Use fanful_listener_checkout_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/listener-checkout-confirmation.html, and must be followed by fanful_listener_support_checkout_start, fanful_listener_membership_checkout_start, or fanful_listener_shop_checkout_start with scoped listener credentials, the exact purchase-link preview confirmation text, idempotency, reason, and audit correlation. Lesson and paid-room starts remain blocked.
Creator
Keep custom reasoning external unless a bounded worker family has explicit logs, limits, approval, cancellation, rollback, and audit semantics.
Listener
Listener-impacting workers stay preview/read-only until a confirmed action contract says a write is executable.
Contract
Use the hosted-runtime boundary and safe run-record fixture before opening worker-family implementation issues.
Creator
Preview lesson or coaching price/policy impact without changing Stripe, checkout, booking policy, or public pages.
Listener
Fan-facing checkout starts remain planned.
Contract
Use fanful_creator_lesson_price_preview first; lesson price cents, existing lesson Stripe Price mapping, and replacement lesson Stripe Price creation have confirmed wrappers.
Creator
Preview a lesson or coaching price change, then confirm the supported Fanful offering price update through the wrapper.
Listener
Future fan-facing catalogs see the new Fanful service price after the confirmed creator write succeeds.
Contract
Use fanful_creator_service_price_policy_update with exact confirmation, observed updated_at, idempotency, reason, and audit correlation. Stripe Price, credit, refund, cancellation execution, and entitlement writes remain blocked.
Creator
Read the latest creator-commerce policy settings, then confirm an artist-default or offering-override lesson policy settings change.
Listener
Future lesson surfaces can explain the configured cutoff, refund, no-show, skip-week, and credit-expiration settings after the confirmed creator write succeeds.
Contract
Use fanful_creator_lesson_policy_update with exact confirmation, observed lesson_policy_settings.updated_at or observed policy id set, idempotency, reason, and audit correlation. Refund execution, credit ledger mutations, booking cancellation/reschedule execution, bundles, subscriptions, and entitlement writes remain blocked.
Creator
Show a ChatGPT confirmation review for a lesson price or lesson policy settings change before the separate write tool runs.
Listener
No listener-facing lesson catalog or policy change occurs until the matching confirmed write succeeds.
Contract
Use fanful_creator_lesson_price_policy_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/creator-lesson-price-policy-confirmation.html, and must be followed by fanful_creator_service_price_policy_update or fanful_creator_lesson_policy_update with exact confirmation, stale-state guards, idempotency, reason, audit correlation, and scoped/admin credentials.
Creator
Read the latest creator-commerce lesson availability, render the optional ChatGPT confirmation review when useful, then confirm one future open/cancelled lesson window change.
Listener
Future lesson surfaces see the updated open/cancelled availability only after the confirmed creator write succeeds.
Contract
For ChatGPT UI, use fanful_creator_lesson_availability_confirmation_render first. Then use fanful_creator_lesson_availability_update with exact confirmation, observed lesson_availability_windows.updated_at or observed availability id set, idempotency, reason, and audit correlation. Held/booked slots, booking workflow execution, meeting URLs, private notes, refunds, credits, and Stripe remain blocked.
Creator
Read the latest creator-commerce or Stripe catalog state, then confirm selecting or clearing an already-known Stripe Price mapping for one lesson offering.
Listener
Future lesson checkout uses the mapped Stripe Price only after the confirmed creator write succeeds.
Contract
Use fanful_creator_lesson_stripe_price_select with exact confirmation, observed updated_at, idempotency, reason, and audit correlation. Product metadata, policy, tier, credit, cancellation, and entitlement writes remain blocked.
Creator
Read the latest creator-commerce or Stripe catalog state, then confirm creating and selecting one replacement Stripe Price for one lesson offering.
Listener
Future lesson checkout uses the replacement Stripe Price only after the confirmed creator write succeeds.
Contract
Use fanful_creator_lesson_stripe_price_create with exact confirmation, observed updated_at, idempotency, reason, audit correlation, server-side Stripe credentials, and existing product context. Product metadata, policy, tier, credit, cancellation, and entitlement writes remain blocked.
Creator
Read the latest creator-commerce or Stripe catalog state, then confirm selecting or clearing an already-known Stripe Price mapping for one membership tier.
Listener
Future membership checkout uses the mapped Stripe Price only after the confirmed creator write succeeds.
Contract
Use fanful_creator_membership_stripe_price_select with exact confirmation, observed updated_at, idempotency, reason, audit correlation, and catalog compatibility checks. Tier profile, amount, entitlement metadata, and existing membership writes remain blocked.
Creator
Read the latest creator-commerce or Stripe catalog state, then confirm creating and selecting one replacement monthly Stripe Price for one membership tier.
Listener
Future membership checkout uses the replacement monthly Stripe Price only after the confirmed creator write succeeds.
Contract
Use fanful_creator_membership_stripe_price_create with exact confirmation, observed updated_at, monthly amount, interval=month, idempotency, reason, audit correlation, server-side Stripe credentials, and existing product context. Tier profile, entitlement metadata, checkout policy, and existing membership writes remain blocked.
Creator
Create an inactive tier draft, update one tier's public profile/benefits, or archive/restore a tier for future joins through focused confirmed tools.
Listener
Future membership surfaces see the changed tier catalog only after the confirmed creator write succeeds.
Contract
Use fanful_creator_membership_tier_create, fanful_creator_membership_tier_update, or fanful_creator_membership_tier_archive_state with exact confirmation, stale-state/catalog guards, idempotency, reason, and audit correlation. Amount changes, Stripe Price mapping, entitlement metadata, checkout policy, and existing membership revocation stay in separate tools or blocked contracts.
Creator
Show a ChatGPT confirmation review for a membership tier create, update, archive/restore, or Stripe Price change before the separate write tool runs.
Listener
No listener-visible catalog change occurs until the matching confirmed write succeeds.
Contract
Use fanful_creator_membership_tier_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/creator-membership-tier-confirmation.html, and must be followed by the matching membership write tool with exact confirmation, stale-state/catalog guards, idempotency, reason, audit correlation, and scoped/admin credentials.
Creator
Read the latest creator-commerce shop catalog, then confirm one safe product create with observed product ids.
Listener
Future shop and checkout surfaces see the new product only after the confirmed creator write succeeds and the product is active/visible.
Contract
For ChatGPT UI, use fanful_creator_shop_product_confirmation_render first. Then use fanful_creator_shop_product_create with exact confirmation, observed product ids, idempotency, reason, audit correlation, duplicate id/slug checks, and scoped/admin credentials. Raw download URLs, external URLs, Stripe Price ids, checkout sessions, fulfillment execution, orders, refunds, and credits remain blocked.
Creator
Read the latest creator-commerce shop product state, then confirm safe details on one existing editable product.
Listener
Future shop and checkout surfaces see the changed copy, inventory, and fulfillment metadata only after the confirmed creator write succeeds.
Contract
For ChatGPT UI, use fanful_creator_shop_product_confirmation_render first. Then use fanful_creator_shop_product_visibility_update for active/show-in-shop flags and fanful_creator_shop_product_details_update for title, description, inventory tracking/count, fulfillment note, download display metadata, and sort order. Raw download URLs, external URLs, product kind/id, checkout sessions, order fulfillment, and refunds remain blocked or separate contracts.
Creator
Read the latest creator-commerce or Stripe catalog state, then confirm selecting/clearing a compatible Price or creating one replacement one-time Price for an existing shop product.
Listener
Future shop checkout uses the selected or replacement Stripe Price only after the confirmed creator write succeeds.
Contract
For ChatGPT UI, use fanful_creator_shop_product_confirmation_render first. Then use fanful_creator_shop_product_stripe_price_select or fanful_creator_shop_product_stripe_price_create with exact confirmation, observed updated_at, idempotency, reason, audit correlation, catalog compatibility checks, server-side Stripe credentials for creation, and existing Product context. Raw download URLs, external URLs, checkout sessions, fulfillment execution, orders, refunds, and credits remain blocked.
Creator
Read the latest community channel state, then confirm one non-default channel access-mode or membership-tier access metadata change.
Listener
Listener access to that protected community channel updates only after the confirmed creator/admin write succeeds.
Contract
For ChatGPT UI, use fanful_creator_entitlement_metadata_confirmation_render first. Then use fanful_creator_entitlement_metadata_update with exact confirmation, observed community_chat_channels.updated_at, idempotency, reason, audit correlation, and scoped creator/admin credentials. Inactive tier creation is handled by the separate membership-tier lifecycle contract; paid-room policy, entitlement-group, and membership writes remain blocked.
Creator
Show a ChatGPT confirmation review for go-live, end, cancel, or scheduled-status transitions before the separate live status write tool runs.
Listener
No listener-visible live room state changes until the matching confirmed status write succeeds.
Contract
Use fanful_creator_live_status_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/creator-live-status-confirmation.html, and must be followed by fanful_creator_live_status_update with exact confirmation, observed live_events.updated_at, idempotency, reason, audit correlation, and scoped/admin credentials. Event creation, schedule edits, stream provider provisioning, roster/stage changes, chat moderation, and notification fan-out stay in separate contracts.
Creator
No creator write is performed; this only explains fan access to gated experiences.
Listener
Ask what membership tier, benefits, purchases, and gated experiences the signed-in fan can access.
Contract
Use listener.entitlementStatus or fanful_listener_entitlements_read with listener:entitlements:read for private scoped clients.
Creator
No creator write is performed; this only explains the fan's own account preference state.
Listener
Ask what email confirmation state, notification channels, categories, and community-chat notification routing are configured.
Contract
Use listener.profilePreferences or fanful_listener_profile_preferences_read with listener:profile:read plus listener:preferences:read for private scoped clients.
Creator
No creator write is performed; this only changes the signed-in fan's account display name for future attribution.
Listener
Read the current display name, choose the exact new visible name, then confirm the update so future account chrome, community posts, chat, and comments use it.
Contract
Use fanful_listener_display_name_confirmation_render when a ChatGPT UI confirmation summary is useful, then use fanful_listener_display_name_update or POST /api/agent/listener-experience with confirm_listener_display_name_update after a fresh profile read, exact confirmation text, acknowledged risk, idempotency key, reason, audit correlation id, observed display-name stale-state guard, and scoped listener:profile:write or first-party listener credentials.
Creator
No creator write is performed; this only explains what support CTA agents may show during live rooms.
Listener
Ask whether a live-room support CTA is available, what generic support/donation confirmation copy is needed, confirm support-only checkout start, then inspect redacted checkout status.
Contract
Use listener.liveSupport or fanful_listener_live_support_preview first, then fanful_listener_support_checkout_start or POST /api/agent/listener-experience with listener.checkout.start. Use listener.purchaseLinkStatus or fanful_listener_purchase_link_status for redacted follow-up status. Membership checkout uses listener.purchaseLinkPreview plus fanful_listener_membership_checkout_start; signed-CD shop checkout uses listener.purchaseLinkPreview plus fanful_listener_shop_checkout_start; lesson and paid-room starts remain blocked.
Creator
Check whether a future creator action carries confirmation, idempotency, actor, and client attribution.
Listener
Check whether a future fan action has the same confirmation and audit fields.
Contract
Use /api/agent/action-contracts and the dry-run envelope validator once merged.
Creator
Preview a live create, schedule edit, or reschedule payload with stream/replay fields redacted, optionally preview follower notification copy, then confirm supported new-event creates or existing-event updates through the wrappers.
Listener
Listener-facing live room state and optional in-app notification-center rows update only after the confirmed creator/admin write succeeds. Email and push are not sent by the schedule-write slice.
Contract
Use fanful_live_schedule_preview first, then fanful_creator_live_schedule_create for new events or fanful_creator_live_schedule_update for existing events with confirmation, idempotency, reason, audit correlation, and matching fanNotification audience/title/body/timeZone when notifying followers. Existing-event updates also require observed updated_at.
Creator
Preview a live-room status change, then confirm go-live, end, cancel, or restore-scheduled through the wrapper.
Listener
Listener-facing live room state updates only after the confirmed creator/admin write succeeds.
Contract
Use fanful_live_status_preview first. In ChatGPT UI, optionally render fanful_creator_live_status_confirmation_render before fanful_creator_live_status_update with confirmation, observed updated_at, idempotency, reason, and audit correlation.
Creator
Read one embedded-room roster, then confirm a single invite, co-host promotion, stage move, removal, or restore through the wrapper.
Listener
Listener room access and presenter state update only after the confirmed creator/admin write succeeds.
Contract
Use fanful_agent_manifest_read(surface=embedded-rooms) first, then fanful_creator_embedded_room_roster_update with confirmation, observed participant updated_at for existing participants, idempotency, reason, and audit correlation.
Creator
Ask for aggregate source funnels, top content outcomes, listener cohorts, and recent signals without exporting listener rows.
Listener
No listener-facing data is exposed; raw listener ids, anonymous ids, session ids, and referrer query strings stay redacted.
Contract
Use fanful_agent_manifest_read(surface=artist-analytics) or /api/agent/artist-analytics with creator:laurel:analytics:read, creator:laurel:read, admin, or automation credentials.
Creator
Run the first-party Stripe catalog app-reference drift worker and inspect redacted checkpoint output before proposing commerce changes.
Listener
No listener-facing write is performed; sync output only informs creator/operator review.
Contract
Use fanful_sync_job_run with an idempotency key and audit correlation id, then fanful_sync_job_status_read or /api/agent/sync-jobs?jobId=... to inspect durable redacted runs.
Creator
Approve scoped creator grants for live, commerce, rooms, and moderation.
Listener
Approve scoped listener grants for entitlements, preferences, purchases, and Listen Along.
Contract
Uses scoped grants, one-time token exchange, account revocation, and MCP principal resolution.
Creator
Moderate rooms, speak as creator, or make broader commerce changes only after confirmation.
Listener
Start support, membership, or shop checkout, post ideas, update preferences, or join experiences only with scoped attribution.
Contract
Live schedule/status, embedded-room roster/stage, lesson price, lesson Stripe Price mapping/creation, membership tier lifecycle, membership Stripe Price mapping/creation, shop product create/visibility/details/Stripe Price writes, support checkout, membership checkout, signed-CD shop checkout, and community-message post/reply writes are ready in narrow wrappers; destructive, unsupported public-content, and unsupported billing writes remain unavailable until a manifest explicitly marks them ready.
Safety boundary
Use MCP resources and HTTP manifests before browser automation. Current public reads are intentionally safe and redacted.
Never put admin secrets or bearer credentials into prompt-visible tool input. Private agent access is split into scoped grants, token exchange, revocation, and principal resolution.
Confirmed live schedule/status and lesson price writes are currently executable through scoped contracts. Billing, moderation, creator-speech, checkout, and preference writes stay unavailable until a manifest explicitly marks them ready and requires confirmation plus audit attribution.
ChatGPT app widgets and metadata should layer over the shared MCP contracts. They are not separate product contracts.