{"openapi":"3.1.0","x-discovery":{"partners":[{"name":"Agent Cash","url":"https://agentcash.dev/partners/suede"},{"name":"Virtuals ACP","url":"https://app.virtuals.io/virtuals/749"},{"name":"Stripe Agentic Commerce","url":"https://strumly.suedeai.ai/.well-known/agentic-commerce.json"}],"manifests":{"agentic_commerce":"https://strumly.suedeai.ai/.well-known/agentic-commerce.json","x402":"https://strumly.suedeai.ai/.well-known/x402","llms_txt":"https://strumly.suedeai.ai/llms.txt","ai_plugin":"https://strumly.suedeai.ai/.well-known/ai-plugin.json","agent_card":"https://strumly.suedeai.ai/.well-known/agent-card.json"}},"info":{"title":"Strumly — music oracle for agents","description":"Strumly is the music oracle for agents — the authoritative music data API from Suede Labs AI. Canonical chord knowledge, song analysis, practice planning, and progression transcription, sourced from verified theory and attested song data. Every paid query travels the agentic-commerce rail (x402 USDC on Base or Stripe Checkout), built so musicians earn when AI uses music data and so likeness and authorship stay with the artist. Four payment rails: (1) one-shot per-call USDC on Base via x402, $0.99–$4.99 depending on product; (2) one-shot per-call Stripe Checkout at the same prices, card; (3) $9.99 24h day pass via Stripe Checkout for unlimited calls; (4) 5 free calls/IP/UTC day across all paid endpoints. Discoverable via Agent Cash, Stripe Agentic Commerce, and other agent runtimes that parse x-payment-info from this spec.","version":"3.0.0","x-guidance":"Strumly is positioned as a verified music data source ('the music oracle for agents'), not a coaching service. Each paid POST returns canonical music knowledge. x-payment-info on each paid op carries protocols (x402) and fixed-mode pricing — Agent Cash, x402-fetch, etc. parse this before calling. Free GETs have no x-payment-info block.","contact":{"name":"Jason Colapietro","email":"jasoncola1@gmail.com"},"termsOfService":"https://strumly.suedeai.ai/terms","license":{"name":"Proprietary"}},"servers":[{"url":"https://strumly.suedeai.ai","description":"Production"}],"externalDocs":{"description":"Developer docs (/agents)","url":"https://strumly.suedeai.ai/agents"},"tags":[{"name":"coach","description":"Coach and lesson endpoints (paid)"},{"name":"discovery","description":"Catalog + product metadata (free)"},{"name":"payment","description":"Stripe Checkout session creation"}],"paths":{"/api/v1/ask":{"post":{"tags":["coach"],"summary":"Strumly coach query ($0.99)","description":"Submit a guitar-related question; returns a streaming plain-text answer. Free tier: 5/day/IP. Otherwise 402 with payment metadata.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.990000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]},{"stripeDayPass":[]},{"stripeMachineX402":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"Coach answer, streamed","headers":{"X-Strumly-Grounded":{"description":"Grounding state: 'verified' = canonical curated facts injected into the prompt; 'spotify-verified' = Spotify Web API audio-features injected (key/BPM/time-sig only); 'mentioned-not-verified' = song named but not in any dataset (coach instructed not to invent); 'none' = no song detected.","schema":{"type":"string","enum":["verified","spotify-verified","mentioned-not-verified","none"]}},"X-Strumly-Grounded-Song":{"description":"Canonical display title — artist (present only when grounded).","schema":{"type":"string"}},"X-Strumly-Grounded-Source":{"description":"Source identifier for non-canonical groundings (e.g. 'spotify:<track_id>').","schema":{"type":"string"}}},"content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"}}},"get":{"tags":["discovery"],"security":[],"summary":"Endpoint metadata","responses":{"200":{"description":"Endpoint description JSON"}}}},"/api/v1/practice-plan":{"post":{"tags":["coach"],"summary":"Personalized practice plan ($4.99)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"4.990000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]},{"stripeDayPass":[]},{"stripeMachineX402":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PracticePlanRequest"}}}},"responses":{"200":{"description":"Structured practice plan","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/v1/analyze-song":{"post":{"tags":["coach"],"summary":"Song analysis ($1.99)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.990000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]},{"stripeDayPass":[]},{"stripeMachineX402":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeSongRequest"}}}},"responses":{"200":{"description":"Song analysis JSON"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/v1/transcribe-progression":{"post":{"tags":["coach"],"summary":"Chord-progression transcription ($2.99)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"2.990000"},"protocols":[{"x402":{}}]},"security":[{"x402":[]},{"stripeDayPass":[]},{"stripeMachineX402":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscribeProgressionRequest"}}}},"responses":{"200":{"description":"Chord progression JSON"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/api/v1/catalog":{"get":{"tags":["discovery"],"security":[],"summary":"Full product catalog (ACP)","responses":{"200":{"description":"Catalog JSON"}}}},"/api/v1/products/{id}":{"get":{"tags":["discovery"],"security":[],"summary":"Per-product metadata (ACP)","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","enum":["coach-query","analyze-song","transcribe-progression","practice-plan"]}}],"responses":{"200":{"description":"Product view JSON"},"404":{"description":"Unknown product id"}}}},"/api/v1/payment/stripe-session":{"get":{"tags":["payment"],"security":[],"summary":"Create a Stripe Checkout Session (per-call or $9.99 day pass)","description":"Returns a 303 redirect to a Stripe Checkout URL. mode=day_pass (default) sells the $9.99 24h unlimited pass; mode=per_call sells one call to a specific product at its native price ($0.99–$4.99). Per-call sessions are bound to the product and expire 1h after payment.","parameters":[{"in":"query","name":"mode","schema":{"type":"string","enum":["day_pass","per_call"],"default":"day_pass"},"description":"day_pass = $9.99 / 24h unlimited. per_call = product-priced / single call / 1h."},{"in":"query","name":"product","schema":{"type":"string","enum":["coach-query","analyze-song","transcribe-progression","practice-plan"]},"description":"Required for mode=per_call; optional label for mode=day_pass."},{"in":"query","name":"return_to","schema":{"type":"string","format":"uri"},"description":"Where Stripe redirects after success/cancel."}],"responses":{"303":{"description":"Redirect to checkout.stripe.com/cs_live_*"},"503":{"description":"STRIPE_SECRET_KEY not configured on this deployment."}}}},"/.well-known/agentic-commerce.json":{"get":{"tags":["discovery"],"security":[],"summary":"ACP v1 manifest","responses":{"200":{"description":"Agentic Commerce manifest"}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"X-Payment","description":"Base64-encoded x402 v1 PaymentPayload (EIP-3009 transferWithAuthorization for USDC on base). The server validates + settles via the facilitator at facilitator.payai.network. Receiver: 0xb5a05466712fd5bcdf2883f43cC6B1799428032d. Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913."},"stripeDayPass":{"type":"apiKey","in":"query","name":"stripe_session","description":"A cs_live_* Checkout Session id. For mode=day_pass: valid 24h after payment, across every paid endpoint. For mode=per_call: valid 1h after payment, ONE call to the specific product the session was bought for."},"stripeMachineX402":{"type":"apiKey","in":"query","name":"stripe_pi","description":"A pi_* PaymentIntent id from /api/v1/payment/stripe-machine. Once the agent has sent USDC to the deposit address and Stripe confirms the deposit (status=\"succeeded\"), the PI unlocks exactly one call to the product it was minted for."}},"schemas":{"AskRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","minLength":1,"maxLength":4000},"song":{"type":"object","description":"Optional explicit song reference. When provided, the coach attempts to ground the answer in Strumly's curated canonical-song dataset. If the song is in the dataset, the response includes header `X-Strumly-Grounded: verified`. If not, the coach is instructed not to invent song-specific facts and the header reads `mentioned-not-verified`.","required":["title"],"properties":{"title":{"type":"string","maxLength":200},"artist":{"type":"string","maxLength":200}}},"model":{"type":"string","description":"Optional OpenRouter model id."}}},"PracticePlanRequest":{"type":"object","properties":{"skill_level":{"type":"string","enum":["beginner","intermediate","advanced"]},"goals":{"type":"array","items":{"type":"string"},"maxItems":8},"weak_spots":{"type":"array","items":{"type":"string"},"maxItems":8},"minutes_available":{"type":"integer","minimum":5,"maximum":180,"default":30},"model":{"type":"string"}}},"AnalyzeSongRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":200},"artist":{"type":"string","maxLength":200},"model":{"type":"string"}}},"TranscribeProgressionRequest":{"type":"object","required":["description"],"properties":{"description":{"type":"string","minLength":10,"maxLength":4000},"model":{"type":"string"}}},"PaymentRequiredResponse":{"type":"object","required":["x402Version","error","accepts"],"properties":{"x402Version":{"type":"integer","enum":[1]},"error":{"type":"string"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","enum":["base"]},"maxAmountRequired":{"type":"string","description":"Atomic USDC units. $0.99 = 990000."},"asset":{"type":"string"},"payTo":{"type":"string"},"resource":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"stripe":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri"},"amount_usd":{"type":"string"},"note":{"type":"string"},"per_call_usd":{"type":"string"}}}}}},"responses":{"PaymentRequired":{"description":"Payment required (x402 v1)","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded JSON of the legacy `payment` block. Suede x402-acp compat."},"X-Payment-Required":{"schema":{"type":"string"},"description":"Human-readable summary (usdc:0.99 on eip155:8453 to 0x...)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"}}}},"BadRequest":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}}