{"openapi":"3.1.0","info":{"title":"YourSong personal agent commerce","version":"1.0.0","description":"YOURSONG_AGENT_COMMERCE_V1; all prices in ILS agorot, VAT 0. Cards stay on Grow. Existing-order ownership never comes from an email address."},"servers":[{"url":"https://agents.your-song.co.il"}],"security":[{"orderSession":[]}],"components":{"schemas":{"Error":{"type":"object","required":["error","nextAction","retryable"],"properties":{"error":{"type":"string"},"nextAction":{"type":"string"},"retryable":{"type":"boolean"},"retryAfterSeconds":{"type":"integer","minimum":1},"fields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"}}}}}},"Credentials":{"type":"object","required":["accessToken","refreshToken","tokenType","expiresIn"],"properties":{"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"tokenType":{"const":"Bearer"},"expiresIn":{"const":900}}}},"securitySchemes":{"orderSession":{"type":"http","scheme":"bearer","description":"Short-lived guest access token. Store in client credential storage."},"refreshCredential":{"type":"http","scheme":"bearer","description":"Rotating REST refresh credential. Same-key retries return the original pair; different-key reuse revokes its family."},"handoffGrant":{"type":"http","scheme":"bearer","description":"One-use grant from create_handoff. Exchange via header; never place it in query parameters."},"mcpOAuth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://agents.your-song.co.il/authorize","tokenUrl":"https://agents.your-song.co.il/oauth/token","refreshUrl":"https://agents.your-song.co.il/oauth/token","scopes":{"orders:read":"Read authorized carts and their status","orders:write":"Build, quote and create hosted checkout"}}}}}},"paths":{"/v1/agent/catalog":{"get":{"security":[],"operationId":"readPublicCatalog","responses":{"200":{"description":"Versioned current offer, eight initial combinations and separate post-purchase clip guidance, five song languages, availability and timing policy"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/sessions":{"post":{"security":[],"operationId":"createGuestSession","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"responses":{"201":{"description":"New contactless guest. No access to existing orders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/sessions/refresh":{"post":{"operationId":"refreshSession","security":[{"refreshCredential":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"responses":{"200":{"description":"Atomically rotated credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/sessions/revoke":{"post":{"description":"Revoke this principal and all of its REST access credentials.","security":[{"refreshCredential":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"responses":{"200":{"description":"Original result of the command or its retry","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/handoffs/exchange":{"post":{"description":"Exchange a private grant for access to exactly the same order. Keep the grant and exchange key until the response is safely saved.","security":[{"handoffGrant":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"responses":{"200":{"description":"Original result of the command or its retry","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/get_catalog":{"post":{"operationId":"get_catalog","security":[],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/assess_gift":{"post":{"operationId":"assess_gift","security":[],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budgetAgorot":{"type":"integer","minimum":0,"maximum":1000000},"neededAt":{"type":"string","format":"date-time"},"language":{"type":"string","enum":["he","en","fr","ar","ru"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/start_order":{"post":{"operationId":"start_order","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cart":{"type":"object","properties":{"brief":{"type":"object","properties":{"songLanguage":{"type":"string","enum":["he","en","fr","ar","ru"]},"recipient":{"type":"object","properties":{"name":{"type":"string","maxLength":300},"relationship":{"type":"string","maxLength":300},"pronunciation":{"type":"string","maxLength":300},"relationshipDescription":{"type":"string","maxLength":1200}},"additionalProperties":false},"occasion":{"type":"object","properties":{"type":{"type":"string","maxLength":300},"eventDate":{"type":"string","maxLength":40},"eventTitle":{"type":"string","maxLength":300}},"additionalProperties":false},"music":{"type":"object","properties":{"genreId":{"type":"string","enum":["israeli_pop","mediterranean","israeli_emotional","rock_indie","israeli_faith_pop","israeli_acoustic"]},"tempoId":{"type":"string","enum":["calm","steady","upbeat","high_energy"]},"vocalPreference":{"type":"string","enum":["no_preference","female","male"]}},"additionalProperties":false},"qualities":{"type":"array","items":{"type":"string","maxLength":1200},"maxItems":12},"qualityElaborations":{"type":"array","items":{"type":"object","properties":{"sourceIndex":{"type":"integer","minimum":0,"maximum":11},"sourceFeature":{"type":"string","maxLength":1200},"description":{"type":"string","maxLength":18000}},"required":["sourceIndex","sourceFeature","description"],"additionalProperties":false},"maxItems":4},"creativeContext":{"type":"object","properties":{"scene":{"type":"string","maxLength":600},"people":{"type":"string","maxLength":600},"signaturePhrase":{"type":"string","maxLength":300},"adaptiveQuestion":{"type":"string","maxLength":220},"adaptiveAnswer":{"type":"string","maxLength":900}},"additionalProperties":false},"emotion":{"type":"object","properties":{"message":{"type":"string","maxLength":1200},"direction":{"type":"string","enum":["מגבר לאישה","מאישה לגבר","מגבר לגבר","מאישה לאישה","מיחיד לרבים","מרבים ליחיד"]}},"additionalProperties":false},"memories":{"type":"string","maxLength":18000},"closingMessage":{"type":"string","maxLength":1200},"senderName":{"type":"string","maxLength":300},"requiredFacts":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":30},"forbiddenTopics":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":20},"cover":{"type":"object","properties":{"requested":{"type":"boolean"},"consent":{"type":"boolean"}},"required":["requested","consent"],"additionalProperties":false}},"additionalProperties":false},"buyer":{"type":"object","properties":{"fullName":{"type":"string","maxLength":200,"default":""},"email":{"type":"string","maxLength":320,"default":""},"city":{"type":"string","maxLength":120,"default":""},"streetAddress":{"type":"string","maxLength":200,"default":""},"postalCode":{"type":"string","default":""},"phone":{"type":"string","maxLength":30,"default":""},"phoneCountryCode":{"type":"string","maxLength":8,"default":"+972"}},"additionalProperties":false},"selections":{"type":"object","properties":{"tier":{"type":"string","enum":["STANDARD","EXPRESS"]},"karaoke":{"type":"boolean"},"fullControl":{"type":"boolean"},"memoriesClip":{"type":"boolean"},"promoCode":{"type":"string","maxLength":80,"default":""}},"required":["tier","karaoke","fullControl","memoriesClip"],"additionalProperties":false},"deliveryDestination":{"type":"object","properties":{"kind":{"type":"string","enum":["BUYER_EMAIL"]}},"required":["kind"],"additionalProperties":false,"default":{"kind":"BUYER_EMAIL"}},"media":{"type":"object","properties":{"coverSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"photoIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{64}$"},"maxItems":20,"default":[]},"photoConsentVersion":{"type":"string","enum":["private-clip-generated-likeness-2026-10-01"]}},"additionalProperties":false,"default":{"photoIds":[]}}},"required":["brief","buyer","selections"],"additionalProperties":false}},"required":["cart"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/get_order":{"post":{"operationId":"get_order","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"}},"required":["orderId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/update_order":{"post":{"operationId":"update_order","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"expectedRevision":{"type":"integer","minimum":0,"maximum":1000000},"cart":{"type":"object","properties":{"brief":{"type":"object","properties":{"songLanguage":{"type":"string","enum":["he","en","fr","ar","ru"]},"recipient":{"type":"object","properties":{"name":{"type":"string","maxLength":300},"relationship":{"type":"string","maxLength":300},"pronunciation":{"type":"string","maxLength":300},"relationshipDescription":{"type":"string","maxLength":1200}},"additionalProperties":false},"occasion":{"type":"object","properties":{"type":{"type":"string","maxLength":300},"eventDate":{"type":"string","maxLength":40},"eventTitle":{"type":"string","maxLength":300}},"additionalProperties":false},"music":{"type":"object","properties":{"genreId":{"type":"string","enum":["israeli_pop","mediterranean","israeli_emotional","rock_indie","israeli_faith_pop","israeli_acoustic"]},"tempoId":{"type":"string","enum":["calm","steady","upbeat","high_energy"]},"vocalPreference":{"type":"string","enum":["no_preference","female","male"]}},"additionalProperties":false},"qualities":{"type":"array","items":{"type":"string","maxLength":1200},"maxItems":12},"qualityElaborations":{"type":"array","items":{"type":"object","properties":{"sourceIndex":{"type":"integer","minimum":0,"maximum":11},"sourceFeature":{"type":"string","maxLength":1200},"description":{"type":"string","maxLength":18000}},"required":["sourceIndex","sourceFeature","description"],"additionalProperties":false},"maxItems":4},"creativeContext":{"type":"object","properties":{"scene":{"type":"string","maxLength":600},"people":{"type":"string","maxLength":600},"signaturePhrase":{"type":"string","maxLength":300},"adaptiveQuestion":{"type":"string","maxLength":220},"adaptiveAnswer":{"type":"string","maxLength":900}},"additionalProperties":false},"emotion":{"type":"object","properties":{"message":{"type":"string","maxLength":1200},"direction":{"type":"string","enum":["מגבר לאישה","מאישה לגבר","מגבר לגבר","מאישה לאישה","מיחיד לרבים","מרבים ליחיד"]}},"additionalProperties":false},"memories":{"type":"string","maxLength":18000},"closingMessage":{"type":"string","maxLength":1200},"senderName":{"type":"string","maxLength":300},"requiredFacts":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":30},"forbiddenTopics":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":20},"cover":{"type":"object","properties":{"requested":{"type":"boolean"},"consent":{"type":"boolean"}},"required":["requested","consent"],"additionalProperties":false}},"additionalProperties":false},"buyer":{"type":"object","properties":{"fullName":{"type":"string","maxLength":200,"default":""},"email":{"type":"string","maxLength":320,"default":""},"city":{"type":"string","maxLength":120,"default":""},"streetAddress":{"type":"string","maxLength":200,"default":""},"postalCode":{"type":"string","default":""},"phone":{"type":"string","maxLength":30,"default":""},"phoneCountryCode":{"type":"string","maxLength":8,"default":"+972"}},"additionalProperties":false},"selections":{"type":"object","properties":{"tier":{"type":"string","enum":["STANDARD","EXPRESS"]},"karaoke":{"type":"boolean"},"fullControl":{"type":"boolean"},"memoriesClip":{"type":"boolean"},"promoCode":{"type":"string","maxLength":80,"default":""}},"required":["tier","karaoke","fullControl","memoriesClip"],"additionalProperties":false},"deliveryDestination":{"type":"object","properties":{"kind":{"type":"string","enum":["BUYER_EMAIL"]}},"required":["kind"],"additionalProperties":false,"default":{"kind":"BUYER_EMAIL"}},"media":{"type":"object","properties":{"coverSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"photoIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{64}$"},"maxItems":20,"default":[]},"photoConsentVersion":{"type":"string","enum":["private-clip-generated-likeness-2026-10-01"]}},"additionalProperties":false,"default":{"photoIds":[]}}},"required":["brief","buyer","selections"],"additionalProperties":false}},"required":["orderId","expectedRevision","cart"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/quote_order":{"post":{"operationId":"quote_order","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"expectedRevision":{"type":"integer","minimum":0,"maximum":1000000}},"required":["orderId","expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/create_checkout":{"post":{"operationId":"create_checkout","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"expectedRevision":{"type":"integer","minimum":0,"maximum":1000000},"quoteId":{"type":"string","format":"uuid"},"termsVersion":{"type":"string","enum":["2026-10-02"]},"termsAccepted":{"type":"boolean","enum":[true]},"marketingConsent":{"type":"boolean","default":false}},"required":["orderId","expectedRevision","quoteId","termsVersion","termsAccepted"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/create_handoff":{"post":{"operationId":"create_handoff","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"}},"required":["orderId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/get_order_status":{"post":{"operationId":"get_order_status","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"}},"required":["orderId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/get_delivery":{"post":{"operationId":"get_delivery","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"}},"required":["orderId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/prepare_upload":{"post":{"operationId":"prepare_upload","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"expectedRevision":{"type":"integer","minimum":0,"maximum":1000000},"actionGrantId":{"type":"string","format":"uuid"},"requestRevision":{"type":"string","maxLength":200},"kind":{"type":"string","enum":["COVER","MEMORY"]},"bytes":{"type":"integer","minimum":1,"maximum":10485760},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/heic","image/heif","image/avif","image/gif"]},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"consent":{"type":"boolean","enum":[true]},"consentVersion":{"type":"string","enum":["private-clip-generated-likeness-2026-10-01"]}},"required":["kind","bytes","mimeType","sha256","consent"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/complete_upload":{"post":{"operationId":"complete_upload","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"actionGrantId":{"type":"string","format":"uuid"},"uploadId":{"type":"string","format":"uuid"}},"required":["uploadId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/get_customer_action":{"post":{"operationId":"get_customer_action","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"purpose":{"type":"string","enum":["review","complete"]},"invitation":{"type":"string","maxLength":1200},"actionGrantId":{"type":"string","format":"uuid"}},"required":["purpose"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/submit_customer_action":{"post":{"operationId":"submit_customer_action","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"purpose":{"type":"string","enum":["review","complete"]},"actionGrantId":{"type":"string","format":"uuid"},"requestRevision":{"type":"string","maxLength":200},"action":{"type":"string","enum":["APPROVE","NOTES","FULL_REPLACEMENT","SUBMIT"]},"text":{"type":"string","maxLength":18000},"answers":{"type":"object","additionalProperties":{"type":"string","maxLength":4000}},"coverDecision":{"type":"string","enum":["UPLOAD","DECLINE","UNCHANGED"]},"memoryPhotoIds":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{64}$"},"maxItems":20},"memoryPhotoConsent":{"type":"boolean"},"memoryPhotoConsentVersion":{"type":"string","enum":["private-clip-generated-likeness-2026-10-01"]}},"required":["purpose","actionGrantId","requestRevision","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/commands/request_support":{"post":{"operationId":"request_support","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"message":{"type":"string","maxLength":1200,"minLength":1}},"required":["orderId","message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Structured result and next action; order views include the revision and frozen checkout for safe human takeover"},"201":{"description":"Order or constrained upload destination created"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/uploads/{uploadId}":{"put":{"operationId":"uploadFileBytes","security":[{"orderSession":[]},{"mcpOAuth":["orders:write"]}],"parameters":[{"in":"path","name":"uploadId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid","minLength":32,"maxLength":128},"description":"Cryptographically random key; keep private. Reuse exactly after a lost response. A different body with this key is rejected."},{"in":"header","name":"X-YourSong-Credential-Type","schema":{"enum":["MCP"]},"description":"Required when using an OAuth MCP bearer token."}],"requestBody":{"required":true,"description":"Exact bytes, MIME type and SHA-256 declared in prepare_upload. At most 10 MiB. No arbitrary remote URL ingestion.","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/heic":{"schema":{"type":"string","format":"binary"}},"image/heif":{"schema":{"type":"string","format":"binary"}},"image/avif":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Verified immutable attachment receipt"},"400":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Refresh the revision, retain the same checkout identity, or honor a retryable busy response.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error; honor nextAction and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Honor nextAction. Never open another payment to resolve ambiguity.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}