{"openapi":"3.1.0","info":{"title":"Composium.app ConductAComposition HTTP API","version":"1.0.0","description":"OpenAPI documentation for implemented HTTP routes. An owner may grant scoped read-only Card access; purchase and external Conduct execution remain human-controlled."},"servers":[{"url":"https://composium.app"}],"paths":{"/healthz":{"get":{"operationId":"health","summary":"Runtime health","responses":{"200":{"description":"Application process and configured database connection are available."}}}},"/api/child/operation/start":{"post":{"operationId":"startHumanOperation","summary":"Start or resume one server-owned Composium operation","description":"Same-origin human browser action from the HOME entry. The human-facing composium_id is the same UUID stored as composition_id. The server reserves that identity and Card reference, records the database start time and 300/400-second deadlines, and sets HttpOnly operation and owner capabilities. Repeating the action during an active operation resumes the same identity; it never creates a second ID.","x-rate-limit":"60 requests per minute per trusted client IP","responses":{"200":{"description":"The active Composium identity (stored as composition_id) and authoritative deadlines."},"429":{"description":"Rate limit exceeded."},"503":{"description":"Operation could not be reserved."}}}},"/api/child/operation/current":{"get":{"operationId":"readCurrentHumanOperation","summary":"Read the active browser operation state","description":"Requires the HttpOnly operation capability cookie. Returns the same Composition identity, server clock, and deadlines. Private writing is returned only to the holder of that capability.","security":[{"operationCapability":[]}],"responses":{"200":{"description":"Private operation state."},"404":{"description":"No operation capability or operation."}}}},"/api/child/composium/create-checkout":{"post":{"operationId":"createHumanCheckout","summary":"Create or recover the human's Checkout for one Composition","description":"Same-origin browser endpoint. Requires the active server-issued operation identity and capability. It atomically freezes the submitted writing and human Click as the exact proposal on that existing Composition before opening one €4 Stripe Checkout. Only verified payment completes the purchase commitment; payment changes state, not identity. The server refuses a first proposal freeze after 300 seconds and a new Checkout after 400 seconds.","x-rate-limit":"10 requests per 15 minutes per trusted client IP","x-authorization":"Same-origin browser request; human completes Stripe Checkout and accepts Terms. Server verifies payment before fulfillment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"https://composium.app/machine/contracts/composition.v1.schema.json"}}}},"responses":{"201":{"description":"Checkout created, or the already issued Card is ready.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CheckoutRedirect"},{"$ref":"#/components/schemas/CheckoutReady"}]}}}},"202":{"description":"Same purchase is pending and may be recovered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutPending"}}}},"400":{"description":"Invalid or additional input fields."},"409":{"description":"Composition identity binding or purchase state conflict."},"410":{"description":"The operation deadline has ended."},"429":{"description":"Rate limit exceeded."},"503":{"description":"Checkout or purchase preparation is temporarily unavailable."}}}},"/api/child/composium/fulfill":{"post":{"operationId":"recoverHumanFulfillment","summary":"Verify a Checkout Session and recover its Card","description":"Same-origin browser recovery. The session identifier is not proof of payment. The server retrieves it from Stripe, verifies the €4 test-mode payment and Composition binding, then fulfills idempotently.","x-rate-limit":"60 requests per minute per trusted client IP","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id"],"properties":{"session_id":{"type":"string","pattern":"^cs_"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Paid purchase produced or recovered the same Card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentReady"}}}},"202":{"description":"Verified payment is pending fulfillment or manual reconciliation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingFulfillment"}}}},"402":{"description":"Session is not verified as paid."},"429":{"description":"Rate limit exceeded."},"503":{"description":"Temporary recovery error."}}}},"/api/child/composium/verify":{"post":{"operationId":"verifyHumanPayment","summary":"Verify the payment status for a Checkout Session","description":"Same-origin browser recovery; never treats the return URL as payment proof.","x-rate-limit":"60 requests per minute per trusted client IP","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id"],"properties":{"session_id":{"type":"string","pattern":"^cs_"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Payment verified or fulfillment status returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVerification"}}}},"402":{"description":"Payment is not verified."},"429":{"description":"Rate limit exceeded."},"503":{"description":"Temporary verification error."}}}},"/api/child/card/{reference}":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"readPrivateCard","summary":"Read a Card through owner custody or an explicitly released share","description":"Owners receive the private owner Card contract. A recipient with an explicitly granted X-Composium-Share capability receives only one_line, tone, composition, conduct, and reference; no payment, private source, custody, or internal authority metadata is returned. A reference alone grants no access; GET is read-only and never executes Conduct.","security":[{"ownerCapability":[]},{"shareCapability":[]}],"responses":{"200":{"description":"Owner Card or the narrower recipient Card, selected by the verified access capability.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"https://composium.app/machine/contracts/card.v1.schema.json"},{"$ref":"https://composium.app/machine/contracts/card.v1.schema.json#/$defs/recipientCard"}]}}}},"202":{"description":"Card is not issued yet."},"404":{"description":"Missing, deleted, or unauthorized Card."},"503":{"description":"Temporary Card service error."}}},"delete":{"operationId":"deletePrivateCard","summary":"Permanently delete Card contents using the owner capability","description":"Same-origin browser request. Clears Card contents and revokes access while retaining the stable reference and necessary purchase record. Irreversible.","security":[{"ownerCapability":[]}],"x-rate-limit":"60 requests per minute per trusted client IP","responses":{"204":{"description":"Deleted, including an idempotent repeat."},"404":{"description":"Missing or unauthorized Card."},"429":{"description":"Rate limit exceeded."}}}},"/api/child/card/{reference}/share":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"releaseReadOnlyCardShare","summary":"Grant a read-only share capability","description":"Requires same-origin owner capability and is called only after the human chooses SEND. Returns a bearer token; the database stores only its digest. It grants no source, Vault, purchase, or external execution authority. Current grants have no automatic expiry and can be revoked by the owner.","security":[{"ownerCapability":[]}],"responses":{"200":{"description":"A new read-only share capability."},"404":{"description":"Missing or unauthorized Card."}}}},"/api/child/card/{reference}/share/revoke":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revokeReadOnlyCardShares","summary":"Revoke all read-only shares for a Card","description":"Requires same-origin owner capability. Idempotently revokes share grants while preserving Card identity, content, owner access and Vault custody.","security":[{"ownerCapability":[]}],"responses":{"200":{"description":"Number of active read-only share grants revoked."},"404":{"description":"Missing or unauthorized Card."}}}},"/api/child/card/{reference}/vault/claim-capability":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createVaultClaimCapability","summary":"Create a short-lived Vault claim after owner proof","description":"Same-origin browser route. Requires the existing HttpOnly Card owner capability; returns a single-use, short-lived claim token for the explicit magic-link round trip. The raw owner capability is never returned.","security":[{"ownerCapability":[]}],"x-rate-limit":"60 requests per minute per trusted client IP","responses":{"200":{"description":"A short-lived one-time Vault claim token."},"404":{"description":"Missing, deleted, or unauthorized Card."},"429":{"description":"Rate limit exceeded."}}}},"/api/child/card/{reference}/vault/save":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"saveComposiumToVault","summary":"Save this owned Composium to the signed-in Vault","description":"Requires both a server-verified Supabase user session and the Card owner capability. One Composium can belong to only one Vault account.","security":[{"ownerCapability":[],"supabaseUser":[]}],"responses":{"200":{"description":"The same Composium is in the owner's Vault."},"404":{"description":"Missing, deleted, or unauthorized Card."},"409":{"description":"The Card is already held by another Vault account."}}}},"/api/child/card/{reference}/vault/claim":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"claimComposiumIntoVault","summary":"Consume the one-time claim after magic-link sign-in","description":"Requires a verified Supabase user session and the short-lived one-time claim issued after owner proof.","security":[{"supabaseUser":[]}],"responses":{"200":{"description":"The same Composium is now in the authenticated Vault."},"401":{"description":"Supabase sign-in is required."},"404":{"description":"Claim is missing, expired, used, or does not match this Card."}}}},"/api/vault":{"get":{"operationId":"listVaultComposia","summary":"List Composia held by the authenticated owner","description":"Returns only each Card reference, One Line, issuance date, and Vault creation date. No private Tone, Composition, Conduct, or original Click is included in the index.","security":[{"supabaseUser":[]}],"responses":{"200":{"description":"Private Vault index."},"401":{"description":"Supabase sign-in is required."}}}},"/api/vault/card/{reference}":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"readVaultComposium","summary":"Reopen a Card through its Vault owner","description":"A verified account is checked against the Vault custody row. A stable Card reference alone is not authority.","security":[{"supabaseUser":[]}],"responses":{"200":{"description":"The same private Composium Card."},"401":{"description":"Supabase sign-in is required."},"404":{"description":"Missing, deleted, or not held by this account."}}}},"/api/vault/card/{reference}/share":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"releaseVaultOwnedCardShare","summary":"Grant a read-only share from the authenticated Vault","description":"Verifies the signed-in Supabase user owns this saved Card, then grants read-only access. The owner still controls the original Card; the share does not grant custody or execution authority.","security":[{"supabaseUser":[]}],"responses":{"200":{"description":"A new read-only share capability."},"401":{"description":"Supabase sign-in is required."},"404":{"description":"Missing or not held by this account."}}}},"/api/vault/card/{reference}/share/revoke":{"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revokeVaultOwnedCardShares","summary":"Revoke read-only shares from the authenticated Vault","description":"Verifies Vault custody and idempotently revokes share grants while preserving the Card and authenticated owner access.","security":[{"supabaseUser":[]}],"responses":{"200":{"description":"Number of active share grants revoked."},"401":{"description":"Supabase sign-in is required."},"404":{"description":"Missing or not held by this account."}}}},"/api/vault/delete":{"post":{"operationId":"deleteVaultComposium","summary":"Delete a Card held by the authenticated Vault owner","description":"Deletes only a Card associated with the verified user. Clears Composition/Card content, removes Vault custody, revokes Card capabilities, and retains its stable reference and payment records.","security":[{"supabaseUser":[]}],"responses":{"204":{"description":"Card and Vault access deleted."},"401":{"description":"Supabase sign-in is required."},"404":{"description":"Missing or not held by this account."}}}},"/api/child/stripe/webhook":{"post":{"operationId":"receiveStripeWebhook","summary":"Receive signed Stripe events","description":"Stripe-only route; validates the raw request signature. Paid sessions are verified and fulfilled idempotently; recoverable failures return a retryable non-2xx response. This is not a customer or machine endpoint.","security":[{"stripeSignature":[]}],"responses":{"200":{"description":"Event accepted or intentionally acknowledged for manual reconciliation."},"400":{"description":"Invalid Stripe signature."},"503":{"description":"Paid fulfillment remains recoverable and Stripe should retry."}}}}},"components":{"schemas":{"CheckoutRedirect":{"type":"object","required":["ok","url","purchase_id","composition_id","reference"],"properties":{"ok":{"type":"boolean","const":true},"url":{"type":"string","format":"uri"},"purchase_id":{"type":"string","format":"uuid"},"composition_id":{"type":"string","format":"uuid"},"reference":{"type":"string","format":"uuid"}},"additionalProperties":false},"CheckoutReady":{"type":"object","required":["ok","ready","purchase_id","composition_id","reference"],"properties":{"ok":{"type":"boolean","const":true},"ready":{"type":"boolean","const":true},"purchase_id":{"type":"string","format":"uuid"},"composition_id":{"type":"string","format":"uuid"},"reference":{"type":"string","format":"uuid"}},"additionalProperties":false},"CheckoutPending":{"type":"object","required":["ok","pending","retryable","purchase_id","composition_id","reference"],"properties":{"ok":{"type":"boolean","const":false},"pending":{"type":"boolean","const":true},"retryable":{"type":"boolean","const":true},"purchase_id":{"type":"string","format":"uuid"},"composition_id":{"type":"string","format":"uuid"},"reference":{"type":"string","format":"uuid"}},"additionalProperties":false},"FulfillmentReady":{"type":"object","required":["ok","paid","purchase_id","reference"],"properties":{"ok":{"type":"boolean","const":true},"paid":{"type":"boolean","const":true},"purchase_id":{"type":"string","format":"uuid"},"reference":{"type":"string","format":"uuid"}},"additionalProperties":false},"PendingFulfillment":{"type":"object","required":["ok","paid","retryable","status","purchase_id"],"properties":{"ok":{"type":"boolean","const":false},"paid":{"type":"boolean","const":true},"retryable":{"type":"boolean","const":true},"status":{"type":"string","enum":["composing","retryable","reconciliation_required","paid_pending"]},"purchase_id":{"type":"string","format":"uuid"}},"additionalProperties":false},"PaymentVerification":{"type":"object","required":["ok","paid","ready","retryable","status"],"properties":{"ok":{"type":"boolean"},"paid":{"type":"boolean"},"ready":{"type":"boolean"},"retryable":{"type":"boolean"},"status":{"type":"string"},"reference":{"type":"string","format":"uuid"}},"additionalProperties":false}},"securitySchemes":{"ownerCapability":{"type":"apiKey","in":"cookie","name":"child_owner_{compositionId}"},"shareCapability":{"type":"apiKey","in":"header","name":"X-Composium-Share","description":"Bearer token explicitly released by the Card owner. It grants only read access to the recipient Card contract, not Vault ownership or Conduct execution; the owner can revoke it."},"operationCapability":{"type":"apiKey","in":"cookie","name":"child_operation","description":"HttpOnly, short-lived capability bound to one server-reserved Composition operation."},"stripeSignature":{"type":"apiKey","in":"header","name":"Stripe-Signature"},"supabaseUser":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase Auth access token; verified server-side and mapped to a private Vault owner."}}},"x-composium-operation":"/machine/contracts/operation.v1.json","x-not-implemented":["machine composition submission","autonomous machine purchasing","MCP endpoint"]}