{"openapi":"3.1.0","info":{"title":"Artyfile Agent API","version":"1.0.0","description":"Programmatic music licensing on artyfile.com — real recordings by real orchestras and musicians (never AI-generated). Buy loop for AI agents: (1) GET /api/search to find tracks; (2) GET /api/license-terms to confirm the rights fit — tracks with licenseScope \"master_only\" (Cover Editions) carry NO sync licence; (3) POST /api/checkout/basic → returns a Stripe hosted-payment URL that a HUMAN must open and approve (EU PSD2 strong customer authentication) plus a publicId; (4) poll GET /api/order/{publicId} until status \"paid\" (session expires after 1h); (5) fetch downloadUrl (WAV), invoiceUrl and certificateUrl from the order payload. Basic licence €29.90 per track (worldwide, perpetual sync); Limited Edition €69.90 per 1% numbered master share. An MCP server with the same capabilities is available at https://artyfile.com/api/mcp (Streamable HTTP).","contact":{"name":"Artyfile LTD","email":"info@artyfile.com","url":"https://artyfile.com"},"termsOfService":"https://artyfile.com/company/terms-conditions"},"servers":[{"url":"https://artyfile.com"}],"paths":{"/api/search":{"get":{"operationId":"searchTracks","summary":"Search the catalog (hybrid keyword + semantic ranking)","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Free-text query (mood, use case, instrumentation …)"},{"name":"genre","in":"query","schema":{"type":"string"}},{"name":"mood","in":"query","schema":{"type":"string"}},{"name":"tempo","in":"query","schema":{"type":"string"}},{"name":"instrument","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":24}}],"responses":{"200":{"description":"Ranked results. results[].id is the productId POST /api/checkout/basic accepts.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"productId for checkout"},"slug":{"type":"string"},"title":{"type":"string"},"artist":{"type":"string"},"genre":{"type":"string"},"mood":{"type":"array","items":{"type":"string"}},"tempo":{"type":"string"},"instruments":{"type":"array","items":{"type":"string"}},"previewUrl":{"type":"string","description":"Watermarked MP3 preview"},"coverUrl":{"type":"string"},"basicPriceEur":{"type":"number"},"lePriceEur":{"type":"number"},"licenseScope":{"type":"string","enum":["full","master_only"],"description":"master_only = Cover Edition: NO sync licence, LE collector shares only"},"pageUrl":{"type":"string","description":"Human product page (absolute URL)"},"licenseTermsUrl":{"type":"string"}}}}}}}}},"429":{"description":"Rate limited (300 text queries/hour/IP)"}}}},"/api/license-terms":{"get":{"operationId":"getLicenseTerms","summary":"Machine-readable licence summary (binding text: the linked Terms & Conditions)","parameters":[{"name":"tier","in":"query","schema":{"type":"string","enum":["basic","le"]}},{"name":"scope","in":"query","schema":{"type":"string","enum":["full","master_only"]},"description":"master_only returns the Cover-Edition terms (overrides tier)"}],"responses":{"200":{"description":"Licence summary JSON: seller, rights granted, restrictions, territory (worldwide), duration (perpetual), prices"}}}},"/api/checkout/basic":{"post":{"operationId":"createCheckout","summary":"Create a Stripe hosted-checkout session for one track","description":"Returns a payment URL a human must open and approve (EU PSD2 — there is no headless card charge). The optional Idempotency-Key header makes retries safe: the same key replays the original session instead of creating a duplicate order.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string","description":"results[].id from /api/search"},"tier":{"type":"string","enum":["basic","le"],"default":"basic"},"shares":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"LE only: number of 1% master shares"},"giftName":{"type":"string","maxLength":120,"description":"LE only: issue the ownership certificate to this name"},"locale":{"type":"string","enum":["en","de"]}}}}}},"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Stripe hosted payment page — present to the user for approval"},"publicId":{"type":"string","description":"Order id — the bearer capability for order status, download, invoice"},"orderStatusUrl":{"type":"string"},"licenseTermsUrl":{"type":"string"},"expiresAt":{"type":"integer","description":"Unix seconds; the session expires after 1h"}}}}}},"404":{"description":"product_not_found"},"409":{"description":"basic_unavailable (Cover Edition — no sync licence) or le_capacity (with availablePct)"},"429":{"description":"Rate limited (10 checkouts/hour/IP)"}}}},"/api/order/{publicId}":{"get":{"operationId":"getOrderStatus","summary":"Poll order status; paid orders include download/invoice/certificate URLs","parameters":[{"name":"publicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order payload","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string"},"status":{"type":"string","enum":["pending","paid","failed","refunded"]},"tier":{"type":"string","enum":["basic","le"]},"shares":{"type":"integer"},"productId":{"type":"string"},"title":{"type":["string","null"]},"artist":{"type":["string","null"]},"licenseScope":{"type":["string","null"]},"amountEur":{"type":"number"},"currency":{"type":"string"},"wavPending":{"type":"boolean","description":"paid but master not yet uploaded — retry later, the licence is already valid"},"downloadUrl":{"type":["string","null"],"description":"302s to the HMAC-signed 44.1 kHz WAV (paid orders only)"},"invoiceUrl":{"type":["string","null"]},"certificateUrl":{"type":["string","null"]},"pollIntervalSeconds":{"type":"integer"}}}}}},"404":{"description":"order_not_found"},"429":{"description":"Rate limited (300/hour/IP)"}}}},"/api/download":{"get":{"operationId":"downloadTrack","summary":"Download the licensed WAV (302 redirect to a signed URL)","parameters":[{"name":"order","in":"query","required":true,"schema":{"type":"string"},"description":"The order publicId"}],"responses":{"202":{"description":"wav_pending — paid, master not yet uploaded"},"302":{"description":"Redirect to the WAV (token valid 1h; re-request anytime)"},"402":{"description":"not_paid"},"404":{"description":"order_not_found"}}}},"/api/invoice":{"get":{"operationId":"getOrderDocument","summary":"PDF invoice or licence/ownership certificate for a paid order","parameters":[{"name":"order","in":"query","required":true,"schema":{"type":"string"}},{"name":"doc","in":"query","schema":{"type":"string","enum":["invoice","certificate"],"default":"invoice"}}],"responses":{"200":{"description":"application/pdf"},"404":{"description":"order_not_found"}}}}}}