{"openapi":"3.1.0","info":{"title":"AI Marketplace OS — Agent API","version":"1.0.0","description":"Versioned agent-native marketplace API: search, inspect, compare, plan, quote, purchase (policy-governed), entitlements, invocation, updates. Authenticate with x-api-key. All catalog data in this environment is DEMO/SAMPLE."},"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{},"parameters":{}},"paths":{"/search":{"post":{"summary":"Semantic catalog search (public)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":2000},"limit":{"type":"integer","minimum":1,"maximum":50}},"required":["query"]}}}},"responses":{"200":{"description":"Explained, grounded results","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/products/{id}":{"get":{"summary":"Inspect a product (manifest, offers, licenses, trust, versions)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Product detail","content":{"application/json":{"schema":{"nullable":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/compare":{"post":{"summary":"Compare products across a capability matrix","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":6}},"required":["products"]}}}},"responses":{"200":{"description":"Comparison","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/solution-plans":{"post":{"summary":"Plan a multi-product solution for an objective","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"objective":{"type":"string","minLength":5,"maxLength":4000}},"required":["objective"]}}}},"responses":{"200":{"description":"Solution plan (grounded in real catalog ids)","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/compatibility/check":{"post":{"summary":"Check declared compatibility between products","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":10}},"required":["products"]}}}},"responses":{"200":{"description":"Compatibility result","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/cost-estimates":{"post":{"summary":"Estimate one-time + recurring cost for a set of offers","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"offerId":{"type":"string"},"quantity":{"type":"integer","minimum":1}},"required":["offerId"]},"minItems":1}},"required":["items"]}}}},"responses":{"200":{"description":"Cost estimate","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/quotes":{"post":{"summary":"Create a quote (server-side pricing only)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"offerId":{"type":"string"},"quantity":{"type":"integer","minimum":1}},"required":["offerId"]},"minItems":1}},"required":["items"]}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"nullable":true}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/purchase-requests":{"post":{"summary":"Request a purchase from a quote (policy-evaluated; may require human approval)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"},"idempotencyKey":{"type":"string","minLength":8,"maxLength":120}},"required":["quoteId","idempotencyKey"]}}}},"responses":{"200":{"description":"Order with state + approval info","content":{"application/json":{"schema":{"nullable":true}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/purchase-requests/{id}":{"get":{"summary":"Get purchase status; resumes an approved order idempotently","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Order state","content":{"application/json":{"schema":{"nullable":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/approval-requests":{"post":{"summary":"List pending approvals (GET-like helper) or decide one","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"approvalRequestId":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"Pending approvals or decision result","content":{"application/json":{"schema":{"nullable":true}}}},"403":{"description":"Agents cannot approve","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/provisioning-jobs":{"post":{"summary":"Get a provisioning job status","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"}},"required":["jobId"]}}}},"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"nullable":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/entitlements":{"get":{"summary":"List the organization's entitlements","responses":{"200":{"description":"Entitlements","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/invocations":{"post":{"summary":"Invoke a purchased demo service (entitlement-gated, metered)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"string"},"operation":{"type":"string","minLength":1,"maxLength":200},"input":{"type":"object","additionalProperties":{"nullable":true}}},"required":["product","operation"]}}}},"responses":{"200":{"description":"Invocation output","content":{"application/json":{"schema":{"nullable":true}}}},"403":{"description":"No entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/usage":{"get":{"summary":"Usage events for the organization's entitlements","responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/updates":{"get":{"summary":"Updates + security advisories relevant to owned entitlements","responses":{"200":{"description":"Updates","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/update-subscriptions":{"post":{"summary":"Subscribe to a product's update channel","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"string"},"channel":{"type":"string","enum":["stable","beta","security"]}},"required":["product"]}}}},"responses":{"200":{"description":"Subscription","content":{"application/json":{"schema":{"nullable":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/webhooks":{"post":{"summary":"Register a webhook endpoint","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["url","events"]}}}},"responses":{"200":{"description":"Webhook registration (secret returned once)","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/audit-events":{"get":{"summary":"Recent audit events for the organization","responses":{"200":{"description":"Audit events","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/customization-context":{"post":{"summary":"Export the customization handoff bundle for a source entitlement (fork URL + agent context file + license constraints)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entitlementId":{"type":"string"}},"required":["entitlementId"]}}}},"responses":{"200":{"description":"Handoff bundle","content":{"application/json":{"schema":{"nullable":true}}}},"403":{"description":"Not a source entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/context-search":{"post":{"summary":"Find catalog software adjacent to a project you are ALREADY working on. Send a project fingerprint (dependencies, stack, objective) instead of a query string; results are labeled fills_gap / complements / could_replace relative to what the project already does.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dependencies":{"type":"array","items":{"type":"string"},"maxItems":300},"stack":{"type":"array","items":{"type":"string"},"maxItems":30},"existingCapabilities":{"type":"array","items":{"type":"string"},"maxItems":60},"integrations":{"type":"array","items":{"type":"string"},"maxItems":40},"objective":{"type":"string","maxLength":2000},"limit":{"type":"integer","minimum":1,"maximum":25},"includeFree":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Adjacent products with relation labels","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/products/{id}/similar":{"get":{"summary":"Products semantically similar to this one (more-like-this)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Similar products","content":{"application/json":{"schema":{"nullable":true}}}}}}},"/products/{id}/agent-brief":{"get":{"summary":"Structured agent integration brief for a product (what it does, needs, licensing, cautions) — the machine-readable AGENTS.md","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent brief","content":{"application/json":{"schema":{"nullable":true}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}