{"openapi":"3.1.0","info":{"title":"AIOS Market hosted apps","version":"2026-10-05","description":"Maker API for billed hosted apps and referral conversions. Keep API keys on your server."},"servers":[{"url":"https://aiosmarket.ai"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/hosted/me":{"get":{"operationId":"hostedMe","summary":"Read the listing associated with this API key","responses":{"200":{"description":"Authenticated listing","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hosted/entitlements":{"get":{"operationId":"hostedEntitlements","summary":"Find customer entitlements","description":"Supply exactly one of customer_id, email or licence_key. Multiple or missing selectors return 400.","parameters":[{"name":"customer_id","in":"query","required":false,"schema":{"type":"string"},"description":"Exactly one selector is required."},{"name":"email","in":"query","required":false,"schema":{"type":"string"},"description":"Exactly one selector is required."},{"name":"licence_key","in":"query","required":false,"schema":{"type":"string"},"description":"Exactly one selector is required."}],"responses":{"200":{"description":"Matching subscription entitlements","content":{"application/json":{"schema":{"type":"object","description":"The entitlement result for the selected customer or licence."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hosted/licences/validate":{"post":{"operationId":"validateHostedLicence","summary":"Validate a licence key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"licence_key":{"type":"string"}},"required":["licence_key"]}}}},"responses":{"200":{"description":"Licence validity","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"subscription":{"$ref":"#/components/schemas/Subscription"}},"required":["valid"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hosted/sign-in/redeem":{"post":{"operationId":"redeemHostedSignIn","summary":"Redeem a one-time sign-in token","description":"Tokens expire after five minutes. Verify the signed redirect before redeeming. Create or find the local account using customer.id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}}}},"responses":{"200":{"description":"Customer and subscription","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/Customer"},"subscription":{"$ref":"#/components/schemas/Subscription"}},"required":["customer","subscription"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Token already used or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hosted/referrals/conversions":{"post":{"operationId":"reportHostedReferralConversion","summary":"Report a sale on the maker site","description":"Send a stable external_id for idempotency. Send the landing URL aios_click value as click_id. Amount is in integer minor currency units.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string"},"amount_cents":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"occurred_at":{"type":"string","format":"date-time"},"click_id":{"type":"string"}},"required":["external_id","amount_cents","currency"]}}}},"responses":{"200":{"description":"Previously reported conversion","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"New conversion recorded","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This listing is not a referral listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"subscriptionEvent":{"post":{"operationId":"receiveHostedSubscriptionEvent","summary":"Signed subscription event delivered to the maker","security":[],"description":"Verify HMAC-SHA256 with the UTF-8 signing secret over timestamp + period + unmodified raw body. Accept any matching v1 signature during rotation, reject timestamps outside 300 seconds and deduplicate AIOS-Event-Id. Respond 2xx within 10 seconds. Redirects fail.","parameters":[{"name":"AIOS-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex>; multiple v1 values may be present during the 24 hour rotation window."},{"name":"AIOS-Event-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Stable event ID. Deduplicate durably to prevent replay."},{"name":"AIOS-Event-Type","in":"header","required":true,"schema":{"type":"string","enum":["subscription.created","subscription.renewed","subscription.past_due","subscription.updated","subscription.cancelled","subscription.refunded","subscription.disputed","subscription.dispute_closed","test.ping"]}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"The event ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionEvent"}}}},"responses":{"200":{"description":"Event accepted, including an already processed event"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"aios_sk_live_... / aios_sk_test_...","description":"The API key for this listing, sent as Authorization: Bearer <key>. Never expose it in browser code."}},"schemas":{"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]}},"required":["id","email","name"]},"Subscription":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"subscription"},"listing":{"type":"object","description":"The subscribed listing."},"status":{"type":"string","enum":["active","past_due","cancel_scheduled","cancelled","refunded","disputed","expired"]},"access":{"type":"boolean"},"customer":{"$ref":"#/components/schemas/Customer"},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"interval":{"type":"string","enum":["month","year"]},"amount":{"type":"integer"},"currency":{"type":"string"}},"required":["id","name","interval","amount","currency"]},"licence_key":{"type":"string"},"current_period_end":{"type":["string","null"],"format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"created":{"type":"string","format":"date-time"}},"required":["id","object","listing","status","access","customer","plan","licence_key","current_period_end","cancel_at_period_end","created"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"SubscriptionEvent":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["subscription.created","subscription.renewed","subscription.past_due","subscription.updated","subscription.cancelled","subscription.refunded","subscription.disputed","subscription.dispute_closed","test.ping"]},"created":{"type":"integer","description":"Unix timestamp in seconds"},"livemode":{"type":"boolean"},"api_version":{"type":"string","const":"2026-10-05"},"data":{"type":"object","properties":{"subscription":{"oneOf":[{"$ref":"#/components/schemas/Subscription"},{"type":"null"}]},"invoice":{"type":"object"},"refund":{"type":"object"},"dispute":{"type":"object"}},"required":["subscription"]}},"required":["id","type","created","livemode","api_version","data"]}}}}