ConductAComposition — API

One human-authorized operation: Conduct A Composition. Price: 400 EUR cents (€4). HOME reserves one server-owned Composition and starts its 400-second deadline. COMPOSE displays a 300-second writing interval. New Checkout is refused after the total deadline and open unpaid Checkout is expired; a verified paid delivery remains recoverable.

OpenAPI 3.1 specification · Operation contract · Composition input schema · Purchase verification schema · Card output schema

Callable operation and output

The canonical operation is ConductAComposition. The browser call returns a Stripe Checkout URL for the human, a pending status, or the stable Composition/Card reference. After verified payment, the authorized Card API returns the same four composed fields with composium_id, server-generated canonical address, issue time, verified payment status/mode, and separate purchase, read, and execution authority. Its machine-readable response uses the Card schema.

What can I call?

The implemented HTTP endpoints support the existing human journey. Write endpoints enforce same-origin requests. Public machine callers can read the operation and schemas; machines cannot submit a Composition or purchase autonomously. A recipient can read a Card only when the owner deliberately grants a scoped read-only share: send the token from the Card address fragment in the X-Composium-Share header to GET /api/child/card/{reference}. A reference alone grants no access, and GET never executes Conduct.

Input and identity

The HOME entry action calls POST /api/child/operation/start, which reserves one server-owned composition_id, stable Card reference, and database start/deadline timestamps. GET /api/child/operation/current returns that same private operation to its HttpOnly capability holder. COMPOSE carries the ID in same-tab state while writing remains local. POST /api/child/composium/create-checkout accepts that composition_id, writing (1–1500 characters), the original human Click (1–2000 characters), and a stable purchase idempotency_key. At that request, writing and Click are frozen together on the reserved row before Stripe Checkout opens. A changed proposition under the same identity fails. One Composition identity may have separate failed or expired Checkout attempts, but at most one paid entitlement is accepted for it.

Price and authorization

The server creates Stripe Checkout for €4. The human must complete Checkout and accept Terms there. A return URL or session identifier is not payment proof. The server retrieves the Stripe session and verifies that its mode matches the configured runtime, along with amount, currency, paid status, payment intent, legal acceptance, and Composition/Purchase binding before calling Carmelita. Test and live credentials must remain separate.

Fulfillment and recovery

After verified payment, the server claims the same Composition, invokes the existing composition engine once under a database lease, validates Tone, Composition, and Conduct, then atomically issues one Card and removes raw writing. Stripe webhooks and browser recovery share the same idempotent flow. Retryable paid failures are retried; after 48 hours they stop, raw writing and Click are removed, and the purchase requires manual support reconciliation. An old Checkout session still reported as complete but unpaid, or a payment status Stripe cannot confirm, is held for manual status resolution; source material may remain beyond 48 hours to avoid losing material needed for a possible paid delivery. No automatic refund is performed.

Purchase records use pending, paid, expired, failed, and refunded states. Composition fulfillment moves through committed/checkout, paid, composing, issued, or a recoverable/manual failure state. Expired and failed payment attempts may be retried under the same Composition identity; no more than one paid entitlement is allowed for that Composition.

Receiving a Card

GET /api/child/card/{reference} accepts either the owner's active capability or the owner's explicit X-Composium-Share grant. A share grant is read-only and revocable; it does not transfer Vault custody or authorize external action. The response excludes private writing, original Click, customer email, and Stripe session details. Owners can revoke shares at POST /api/child/card/{reference}/share/revoke; Vault owners use POST /api/vault/card/{reference}/share/revoke. DELETE /api/child/card/{reference} or the authenticated Vault delete route permanently deletes the Card and revokes its access.

Rate limits and failures

Checkout creation: 10 requests per 15 minutes per trusted client IP. Browser verify, fulfill, and Card deletion: 60 per minute. Excess requests return 429 and Retry-After. Common responses include 400 invalid input, 402 unverified payment, 404 missing/unauthorized Card, 409 identity/state conflict, 202 pending recovery, and 503 temporary provider/database failure. The Stripe webhook validates its signature separately.

Provider dependencies

Stripe Checkout and signed webhooks handle payment; Supabase stores the Composition, Purchase, Card, and owner capability hash; Anthropic receives source writing and Click after verified payment to compose the Card; Railway or the configured host runs the HTTP service. Private provider credentials are server-only.

No API call authorizes external execution of Conduct. A human decides whether to share or carry out the Card. Future machine/MCP adapters must reference the same operation contract and must not gain payment authority merely from API access.