{"openapi":"3.1.0","info":{"title":"Abynex Agent Marketplace API","version":"1.0.0","description":"Agent-native API for fixed-price declarative products. Products are immutable snapshots; the marketplace does not execute seller code, host seller agents, or grant requested permissions. Monetary values are integer Iranian rial."},"servers":[{"url":"https://abynex.ir/api","description":"Production API"},{"url":"/api","description":"Relative to the current site origin"}],"tags":[{"name":"Catalogue"},{"name":"Buyer"},{"name":"Seller"},{"name":"Blueprints"}],"components":{"securitySchemes":{"ToolApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Abynex Tool API key","description":"Key belongs to a human account. The raw secret is returned once only."}},"parameters":{"ProductId":{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"Offset":{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Reuse only for a retry of the same logical request and payload.","schema":{"type":"string","minLength":8,"maxLength":48,"pattern":"^[A-Za-z0-9._:-]{8,48}$"}},"FromDate":{"name":"from_date","in":"query","description":"Inclusive date, YYYY-MM-DD, in the server's local timezone.","schema":{"type":"string","format":"date"}},"ToDate":{"name":"to_date","in":"query","description":"Inclusive date, YYYY-MM-DD, in the server's local timezone.","schema":{"type":"string","format":"date"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Product":{"type":"object","properties":{"id":{"type":"integer"},"product_type":{"type":"string","enum":["agent_template","skill","workflow","prompt_pack"]},"title":{"type":"string"},"summary":{"type":"string"},"seller":{"type":"string"},"source_version":{"type":"integer"},"source_version_id":{"type":"integer"},"price_rial":{"type":"integer","minimum":0},"price_toman":{"type":"integer","minimum":0},"is_free":{"type":"boolean"},"license_terms":{"type":"string"},"review_count":{"type":"integer","minimum":0},"average_rating":{"type":["number","null"],"minimum":1,"maximum":5},"paid_sales_count":{"type":"integer","minimum":0}},"required":["id","product_type","title","summary","seller","source_version","source_version_id","price_rial","price_toman","is_free","license_terms","review_count","average_rating","paid_sales_count"]},"ProductPage":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next_offset":{"type":["integer","null"]}},"required":["results","count","limit","offset","next_offset"]},"PurchaseInput":{"type":"object","properties":{"expected_version_id":{"type":"integer","minimum":1},"expected_price_rial":{"type":"integer","minimum":0}},"required":["expected_version_id","expected_price_rial"],"additionalProperties":false,"description":"Expected version and price are preconditions, not an override. On mismatch the server returns HTTP 409 and does not charge."},"Order":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"product_id":{"type":"integer"},"product_type":{"type":"string"},"title":{"type":"string"},"seller":{"type":"string"},"price_rial":{"type":"integer"},"price_toman":{"type":"integer"},"fee_rial":{"type":"integer"},"seller_proceeds_rial":{"type":"integer"},"version":{"type":"integer"},"license_terms":{"type":"string"},"entitlement_status":{"type":["string","null"]},"installed_draft_id":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"purchased_snapshot":{"type":"object","description":"Included only in the owner-authorized purchase detail response."}},"required":["id","status","product_id","title","price_rial","price_toman"]},"SellerListingInput":{"type":"object","properties":{"source_version_id":{"type":"integer","minimum":1},"product_type":{"type":"string","enum":["agent_template","skill","workflow","prompt_pack"]},"title":{"type":"string","maxLength":120},"summary":{"type":"string","maxLength":500},"details":{"type":"string","maxLength":6000},"price_rial":{"type":"integer","minimum":0},"license_terms":{"type":"string","maxLength":500}},"required":["source_version_id","title","summary","price_rial","license_terms"]},"SellerListingPatch":{"type":"object","properties":{"source_version_id":{"type":"integer","minimum":1},"product_type":{"type":"string","enum":["agent_template","skill","workflow","prompt_pack"]},"title":{"type":"string","maxLength":120},"summary":{"type":"string","maxLength":500},"details":{"type":"string","maxLength":6000},"price_rial":{"type":"integer","minimum":0},"license_terms":{"type":"string","maxLength":500}},"minProperties":1},"ReviewInput":{"type":"object","properties":{"order_id":{"type":"integer","minimum":1},"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string","maxLength":120},"body":{"type":"string","maxLength":2000}},"required":["order_id","rating"]},"PurchaseAction":{"type":"object","properties":{"action":{"type":"string","enum":["archive","restore","refund"]},"reason":{"type":"string","maxLength":1000}},"required":["action"]},"ListingAction":{"type":"object","properties":{"action":{"type":"string","enum":["pause","publish","withdraw"]}},"required":["action"]},"BlueprintInput":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"summary":{"type":"string","maxLength":400},"instructions":{"type":"string","maxLength":12000},"tool_slugs":{"type":"array","items":{"type":"string"},"maxItems":32},"visibility":{"type":"string","enum":["private"]}},"required":["name"]}}},"paths":{"/marketplace/products/":{"get":{"tags":["Catalogue"],"operationId":"listMarketplaceProducts","summary":"Search and filter published products","description":"Public without a key. If a Tool API key is supplied, marketplace:read is required. popular sorting uses verified paid sales, then review signals.","x-required-scope":"marketplace:read (only when a Tool API key is supplied)","security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100}},{"name":"type","in":"query","schema":{"type":"string","enum":["agent_template","skill","workflow","prompt_pack"]}},{"name":"price","in":"query","schema":{"type":"string","enum":["free","paid"]}},{"name":"order","in":"query","schema":{"type":"string","enum":["newest","price_asc","price_desc","popular"],"default":"newest"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated product catalogue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPage"}}}},"400":{"description":"Invalid pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded"}}}},"/marketplace/products/{id}/":{"get":{"tags":["Catalogue"],"operationId":"getMarketplaceProduct","summary":"Get one published product","x-required-scope":"marketplace:read (only when a Tool API key is supplied)","security":[],"parameters":[{"$ref":"#/components/parameters/ProductId"}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"Not found or not published"}}}},"/marketplace/products/{id}/purchase/":{"post":{"tags":["Buyer"],"operationId":"purchaseMarketplaceProduct","summary":"Buy the current fixed-price product version","x-required-scope":"marketplace:purchase","description":"Requires marketplace:purchase. The key must have positive daily and monthly spend caps. Fixed-price purchases share those caps with metered tool calls. Uses the existing account wallet and ledger. Purchase does not execute seller code or enable requested permissions.","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProductId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseInput"}}}},"responses":{"201":{"description":"Purchase created","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"},"created":{"type":"boolean"}}}}}},"200":{"description":"Idempotent replay or entitlement already exists"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope or spend caps"},"409":{"description":"Price/version changed or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Spend cap or rate limit exceeded"}}}},"/marketplace/purchases/":{"get":{"tags":["Buyer"],"operationId":"listMarketplacePurchases","summary":"List purchases owned by the API-key account","x-required-scope":"marketplace:purchases:read","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Owned purchase records"},"403":{"description":"Missing marketplace:purchases:read"}}}},"/marketplace/purchases/{id}/":{"get":{"tags":["Buyer"],"operationId":"getMarketplacePurchase","summary":"Get the private snapshot for an owned purchase","x-required-scope":"marketplace:purchases:read","security":[{"ToolApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Owned purchase and snapshot"},"403":{"description":"Missing marketplace:purchases:read"},"404":{"description":"Order not owned by this account"}}}},"/marketplace/purchases/{id}/actions/":{"post":{"tags":["Buyer"],"operationId":"manageMarketplacePurchase","summary":"Archive/restore an owned copy or request a refund","x-required-scope":"marketplace:purchases:manage","description":"Requires marketplace:purchases:manage. Refund creates an administrator-reviewed request; it does not instantly refund. Restore does not recharge.","security":[{"ToolApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseAction"}}}},"responses":{"200":{"description":"Action applied or replayed"},"201":{"description":"Refund request created"},"400":{"description":"Invalid action"},"403":{"description":"Missing scope"},"404":{"description":"Order not owned by this account"},"409":{"description":"Action conflicts with order state"}}}},"/marketplace/seller/source-versions/":{"get":{"tags":["Seller"],"operationId":"listSellerSourceVersions","summary":"List own draft versions eligible for sale","x-required-scope":"marketplace:sell:read","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Own immutable source versions"},"403":{"description":"Missing marketplace:sell:read"}}}},"/marketplace/seller/listings/":{"get":{"tags":["Seller"],"operationId":"listSellerListings","summary":"List the seller's own listings, including moderation status","x-required-scope":"marketplace:sell:read","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Own listings"},"403":{"description":"Missing marketplace:sell:read"}}},"post":{"tags":["Seller"],"operationId":"submitSellerListing","summary":"Submit an immutable source version for moderation","x-required-scope":"marketplace:sell:write","description":"Requires marketplace:sell:write. The source version must belong to the API-key account. A new or edited listing is not published before moderation. Price is integer rial divisible by 10.","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerListingInput"}}}},"responses":{"201":{"description":"Submitted for moderation"},"200":{"description":"Idempotent replay"},"400":{"description":"Invalid listing"},"403":{"description":"Missing seller scope"},"404":{"description":"Source version not owned by caller"}}}},"/marketplace/seller/listings/{id}/":{"get":{"tags":["Seller"],"operationId":"getSellerListing","summary":"Get one listing owned by the seller","x-required-scope":"marketplace:sell:read","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProductId"}],"responses":{"200":{"description":"Seller listing"},"404":{"description":"Not owned by caller"}}},"patch":{"tags":["Seller"],"operationId":"updateSellerListing","summary":"Edit an owned listing and resubmit it for moderation","x-required-scope":"marketplace:sell:write","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProductId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerListingPatch"}}}},"responses":{"200":{"description":"Updated and awaiting moderation"},"400":{"description":"Invalid listing"},"404":{"description":"Listing or owned source version not found"}}}},"/marketplace/seller/listings/{id}/status/":{"post":{"tags":["Seller"],"operationId":"setSellerListingStatus","summary":"Pause, republish an approved paused listing, or withdraw","x-required-scope":"marketplace:sell:write","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProductId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingAction"}}}},"responses":{"200":{"description":"Status applied or already in requested state"},"400":{"description":"Invalid action"},"404":{"description":"Listing not owned"},"409":{"description":"Transition not allowed"}}}},"/marketplace/seller/dashboard/":{"get":{"tags":["Seller"],"operationId":"getSellerSalesDashboard","summary":"Get paid sales, fees and seller proceeds","x-required-scope":"marketplace:sell:read","description":"Only positive-price paid orders count. Date bounds are inclusive in the server's local timezone and optional.","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/FromDate"},{"$ref":"#/components/parameters/ToDate"}],"responses":{"200":{"description":"Filtered summary and per-product totals"},"400":{"description":"Invalid date range"},"403":{"description":"Missing marketplace:sell:read"}}}},"/marketplace/products/{id}/reviews/":{"get":{"tags":["Catalogue"],"operationId":"listProductReviews","summary":"List reviews from verified paid purchasers","x-required-scope":"Public GET; marketplace:read is required if using a Tool API key","description":"Each review also identifies the immutable product version the buyer purchased.","security":[],"parameters":[{"$ref":"#/components/parameters/ProductId"}],"responses":{"200":{"description":"Verified paid-purchase reviews"},"404":{"description":"Product not found"}}},"post":{"tags":["Buyer"],"operationId":"createVerifiedProductReview","summary":"Create one review for a paid order owned by this account","x-required-scope":"marketplace:review:write","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProductId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewInput"}}}},"responses":{"201":{"description":"Review created"},"400":{"description":"Invalid review"},"403":{"description":"Order does not belong to this buyer"},"409":{"description":"Review already exists"}}}},"/studio/blueprints/":{"get":{"tags":["Blueprints"],"operationId":"listAgentBlueprints","summary":"List private Blueprints owned by the current account","x-required-scope":"studio:read (for Tool API keys)","description":"Tool API keys need studio:read. Account sessions and standard user tokens are also accepted.","security":[{"ToolApiKey":[]}],"responses":{"200":{"description":"Owned Blueprints"},"403":{"description":"Missing studio:read"}}},"post":{"tags":["Blueprints"],"operationId":"createAgentBlueprint","summary":"Create a private declarative Blueprint","x-required-scope":"studio:write (for Tool API keys)","description":"Tool API keys need studio:write. No LLM is hosted and no seller code is executed.","security":[{"ToolApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlueprintInput"}}}},"responses":{"201":{"description":"Blueprint created"},"400":{"description":"Invalid Blueprint"},"403":{"description":"Missing studio:write"}}}},"/studio/blueprints/{id}/":{"get":{"tags":["Blueprints"],"operationId":"getAgentBlueprint","summary":"Get an owned private Blueprint","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BlueprintId"}],"responses":{"200":{"description":"Blueprint"},"404":{"description":"Not owned by caller"}}},"patch":{"tags":["Blueprints"],"operationId":"updateAgentBlueprint","summary":"Update an owned Blueprint and create a new revision","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BlueprintId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlueprintInput"}}}},"responses":{"200":{"description":"Updated Blueprint"},"400":{"description":"Invalid Blueprint"},"404":{"description":"Not owned by caller"}}}},"/studio/blueprints/{id}/versions/":{"get":{"tags":["Blueprints"],"operationId":"listAgentBlueprintVersions","summary":"List immutable revisions of an owned Blueprint","description":"Requires studio:read for Tool API keys. Only the owner can read history.","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BlueprintId"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated revision history with immutable revision numbers"},"400":{"description":"Invalid pagination"},"403":{"description":"Missing studio:read"},"404":{"description":"Blueprint not owned by caller"}}}},"/studio/blueprints/{id}/versions/{revision}/":{"get":{"tags":["Blueprints"],"operationId":"getAgentBlueprintVersion","summary":"Retrieve one immutable revision of an owned Blueprint","description":"Requires studio:read for Tool API keys. Revision numbers identify saved historical snapshots and cannot be overwritten.","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BlueprintId"},{"name":"revision","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Immutable revision snapshot"},"403":{"description":"Missing studio:read"},"404":{"description":"Revision not owned by caller"}}}},"/studio/blueprints/{id}/export/":{"get":{"tags":["Blueprints"],"operationId":"exportAgentBlueprint","summary":"Export an owned Blueprint as JSON","description":"Tool API keys require studio:export; standard user token/session authentication is also accepted.","security":[{"ToolApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/BlueprintId"}],"responses":{"200":{"description":"Private Blueprint export"},"403":{"description":"Missing studio:export"},"404":{"description":"Not owned by caller"}}}},"/tool-usage/":{"get":{"tags":["Buyer"],"operationId":"getAccountToolUsage","summary":"Account-level calls, API-key purchases and per-key caps","description":"Requires account session or standard user token, not a Tool API key. Returns all API keys owned by the account without allowing one key to inspect others.","security":[],"responses":{"200":{"description":"Per-key caps, used/remaining totals, metered calls and fixed-price purchases"},"401":{"description":"Authentication required"}}}}},"x-abynex-fixed-product-safety":{"productTypes":["agent_template","skill","workflow","prompt_pack"],"executableSellerCode":false,"hostedSellerRuntime":false,"purchaseGrantsRequestedPermissions":false,"fixedProductSnapshotIsImmutable":true}}