{"openapi":"3.1.0","info":{"title":"Limowo Agent Command API","version":"0.2.0","description":"Typed, allowlisted Limowo commands. Public discovery is live; delegated writes remain feature-gated."},"paths":{"/api/agent/v1/commands":{"get":{"operationId":"listAgentCommands","summary":"List available commands","responses":{"200":{"description":"Runtime command catalog"}}}},"/api/agent/v1/session":{"get":{"operationId":"inspectAgentSession","summary":"Inspect the current agent session","responses":{"200":{"description":"Session descriptor"}}}},"/api/agent/v1/commands/prepare":{"post":{"operationId":"prepareAgentCommand","summary":"Validate and prepare a registered command","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareCommandRequest"}}}},"responses":{"200":{"description":"Prepared command","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedCommand"}}}},"400":{"description":"Invalid command or input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/api/agent/v1/commands/prepared/{id}":{"get":{"operationId":"getPreparedAgentCommand","summary":"Inspect a prepared command","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prepared command"},"404":{"description":"Prepared command not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"410":{"description":"Prepared command expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/api/agent/v1/commands/prepared/{id}/execute":{"post":{"operationId":"executePreparedAgentCommand","summary":"Execute an unchanged prepared command","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Command result"},"400":{"description":"Invalid command execution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"Approval or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"500":{"description":"Internal command failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/api/agent/v1/approvals/{id}":{"get":{"operationId":"getAgentCommandApproval","summary":"Inspect a pending approval","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prepared command approval state"},"404":{"description":"Prepared command not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"Approval flow mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/api/agent/v1/approvals/{id}/approve":{"post":{"operationId":"approveAgentCommand","summary":"Approve a prepared command","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Prepared command approval update"}}}},"/api/agent/v1/approvals/{id}/deny":{"post":{"operationId":"denyAgentCommand","summary":"Deny a prepared command","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Prepared command denial update"}}}}},"components":{"schemas":{"CommandDescriptor":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"integer"},"description":{"type":"string"},"requiredScopes":{"type":"array","items":{"type":"string"}},"risk":{"type":"string"},"approval":{"type":"string"},"public":{"type":"boolean"},"available":{"type":"boolean"},"supportsPreparation":{"type":"boolean"},"supportsExecution":{"type":"boolean"},"inputSchema":{"type":"object","additionalProperties":true}}},"PrepareCommandRequest":{"type":"object","required":["command","input"],"additionalProperties":false,"properties":{"command":{"type":"string"},"version":{"type":"integer","minimum":1,"default":1},"input":{"type":"object","additionalProperties":true}}},"PreparedCommand":{"type":"object","properties":{"preparedCommandId":{"type":"string"},"command":{"type":"string"},"version":{"type":"integer"},"normalizedInput":{"type":"object","additionalProperties":true},"risk":{"type":"string"},"approval":{"type":"string"},"effects":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"$ref":"#/components/schemas/AgentNextAction"}},"status":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"requestId":{"type":"string"}}},"AgentNextAction":{"type":"object","required":["id","label","route","requiredActor","risk"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"route":{"type":"string"},"requiredActor":{"type":"string","enum":["PUBLIC","AGENT","HUMAN_OWNER"]},"risk":{"type":"string","enum":["READ","DRAFT_WRITE","EXTERNAL_COMMUNICATION","FINANCIAL"]}}},"AgentError":{"type":"object","required":["code","message","fieldErrors","retryable","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"},"requestId":{"type":"string"}}},"RuntimeCommandCatalog":{"type":"array","items":{"$ref":"#/components/schemas/CommandDescriptor"},"examples":[[{"name":"business.shops.get","version":1,"description":"Read one active public Limowo business shop by its URL slug.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["slug"],"properties":{"slug":{"type":"string","minLength":3,"maxLength":80}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"business.shops.listings.search","version":1,"description":"Search active public listings belonging to one public Limowo business shop.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["slug"],"properties":{"slug":{"type":"string","minLength":3,"maxLength":80},"query":{"type":"string","maxLength":200},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1,"maximum":50}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"business.shops.search","version":1,"description":"Search active public Limowo business shops.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":120},"take":{"type":"integer","minimum":1,"maximum":50}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"category.lookup.children","version":1,"description":"Read one safe category level at a time without returning a full tree.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"parentRef":{"type":"string","minLength":1,"maxLength":240},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"category.lookup.resolve","version":1,"description":"Validate an opaque category reference and return safe display metadata.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["categoryRef"],"properties":{"categoryRef":{"type":"string","minLength":1,"maxLength":240},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"category.lookup.search","version":1,"description":"Search active approved listing categories without exposing the full taxonomy.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":120},"locale":{"type":"string","minLength":2,"maxLength":20},"parentRef":{"type":"string","minLength":1,"maxLength":240}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.draft.create","version":1,"description":"Create an agent-assisted listing draft for the represented human.","requiredScopes":["drafts:write"],"risk":"DRAFT_WRITE","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["title","priceCents"],"properties":{"title":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1500},"listingMode":{"type":"string","enum":["SALE","GIVEAWAY"]},"priceCents":{"type":"integer","minimum":0},"pickupPostalCode":{"type":"string","maxLength":20},"useAuthorPostalCode":{"type":"boolean"},"imageUrls":{"type":"array"},"categoryRef":{"type":"string","maxLength":240},"categoryQuery":{"type":"string","maxLength":120},"attributes":{"type":"array"},"storeId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.draft.validate","version":1,"description":"Validate an agent listing draft with the same checks used for human listing creation.","requiredScopes":["drafts:write"],"risk":"DRAFT_WRITE","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["draftId"],"properties":{"draftId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.publish.execute","version":1,"description":"Publish a validated agent listing draft after explicit human approval.","requiredScopes":["drafts:write"],"risk":"DRAFT_WRITE","approval":"USER_CONFIRMATION","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["draftId"],"properties":{"draftId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.publish.prepare","version":1,"description":"Prepare an exact publish payload preview for an agent listing draft.","requiredScopes":["drafts:read"],"risk":"READ","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["draftId"],"properties":{"draftId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.suggestion.from_image","version":1,"description":"Analyze one product image and return draft-ready listing suggestions without creating a listing.","requiredScopes":["drafts:write"],"risk":"READ","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["imageBase64"],"properties":{"imageBase64":{"type":"string","minLength":100,"maxLength":15000000},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.articles.get","version":1,"description":"Read one public Limowo article by stable identifier.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","minLength":1,"maxLength":100}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.articles.search","version":1,"description":"Search active native Limowo marketplace articles.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":200},"categoryRef":{"type":"string","maxLength":240},"location":{"type":"string","maxLength":100},"isFree":{"type":"boolean"},"listingMode":{"type":"string","enum":["SALE","GIVEAWAY"]},"minPriceCents":{"type":"integer","minimum":0},"maxPriceCents":{"type":"integer","minimum":0},"maxDistanceKm":{"type":"number","minimum":0,"maximum":1000},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1,"maximum":50}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.categories.list","version":1,"description":"Deprecated. Full category tree export is disabled; use category.lookup.search or category.lookup.children.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","properties":{},"additionalProperties":false},"deprecated":true,"replacement":"category.lookup.children","available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.shops.get","version":1,"description":"Deprecated. Read one active public Limowo business shop with business.shops.get.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["slug"],"properties":{"slug":{"type":"string","minLength":3,"maxLength":80}}},"deprecated":true,"replacement":"business.shops.get","available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.shops.search","version":1,"description":"Deprecated. Search active public Limowo business shops with business.shops.search.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":120},"take":{"type":"integer","minimum":1,"maximum":50}}},"deprecated":true,"replacement":"business.shops.search","available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"system.capabilities.list","version":1,"description":"List the typed commands currently exposed by Limowo.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","properties":{},"additionalProperties":false},"available":true,"supportsPreparation":true,"supportsExecution":true}]]}}},"x-limowo-commands":[{"name":"business.shops.get","version":1,"description":"Read one active public Limowo business shop by its URL slug.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["slug"],"properties":{"slug":{"type":"string","minLength":3,"maxLength":80}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"business.shops.listings.search","version":1,"description":"Search active public listings belonging to one public Limowo business shop.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["slug"],"properties":{"slug":{"type":"string","minLength":3,"maxLength":80},"query":{"type":"string","maxLength":200},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1,"maximum":50}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"business.shops.search","version":1,"description":"Search active public Limowo business shops.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":120},"take":{"type":"integer","minimum":1,"maximum":50}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"category.lookup.children","version":1,"description":"Read one safe category level at a time without returning a full tree.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"parentRef":{"type":"string","minLength":1,"maxLength":240},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"category.lookup.resolve","version":1,"description":"Validate an opaque category reference and return safe display metadata.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["categoryRef"],"properties":{"categoryRef":{"type":"string","minLength":1,"maxLength":240},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"category.lookup.search","version":1,"description":"Search active approved listing categories without exposing the full taxonomy.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":120},"locale":{"type":"string","minLength":2,"maxLength":20},"parentRef":{"type":"string","minLength":1,"maxLength":240}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.draft.create","version":1,"description":"Create an agent-assisted listing draft for the represented human.","requiredScopes":["drafts:write"],"risk":"DRAFT_WRITE","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["title","priceCents"],"properties":{"title":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1500},"listingMode":{"type":"string","enum":["SALE","GIVEAWAY"]},"priceCents":{"type":"integer","minimum":0},"pickupPostalCode":{"type":"string","maxLength":20},"useAuthorPostalCode":{"type":"boolean"},"imageUrls":{"type":"array"},"categoryRef":{"type":"string","maxLength":240},"categoryQuery":{"type":"string","maxLength":120},"attributes":{"type":"array"},"storeId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.draft.validate","version":1,"description":"Validate an agent listing draft with the same checks used for human listing creation.","requiredScopes":["drafts:write"],"risk":"DRAFT_WRITE","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["draftId"],"properties":{"draftId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.publish.execute","version":1,"description":"Publish a validated agent listing draft after explicit human approval.","requiredScopes":["drafts:write"],"risk":"DRAFT_WRITE","approval":"USER_CONFIRMATION","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["draftId"],"properties":{"draftId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.publish.prepare","version":1,"description":"Prepare an exact publish payload preview for an agent listing draft.","requiredScopes":["drafts:read"],"risk":"READ","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["draftId"],"properties":{"draftId":{"type":"string","minLength":1,"maxLength":100},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"listing.suggestion.from_image","version":1,"description":"Analyze one product image and return draft-ready listing suggestions without creating a listing.","requiredScopes":["drafts:write"],"risk":"READ","approval":"GRANT","feature":"DRAFTS","public":false,"inputSchema":{"type":"object","additionalProperties":false,"required":["imageBase64"],"properties":{"imageBase64":{"type":"string","minLength":100,"maxLength":15000000},"locale":{"type":"string","minLength":2,"maxLength":20}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.articles.get","version":1,"description":"Read one public Limowo article by stable identifier.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","minLength":1,"maxLength":100}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.articles.search","version":1,"description":"Search active native Limowo marketplace articles.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":200},"categoryRef":{"type":"string","maxLength":240},"location":{"type":"string","maxLength":100},"isFree":{"type":"boolean"},"listingMode":{"type":"string","enum":["SALE","GIVEAWAY"]},"minPriceCents":{"type":"integer","minimum":0},"maxPriceCents":{"type":"integer","minimum":0},"maxDistanceKm":{"type":"number","minimum":0,"maximum":1000},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1,"maximum":50}}},"available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.categories.list","version":1,"description":"Deprecated. Full category tree export is disabled; use category.lookup.search or category.lookup.children.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","properties":{},"additionalProperties":false},"deprecated":true,"replacement":"category.lookup.children","available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.shops.get","version":1,"description":"Deprecated. Read one active public Limowo business shop with business.shops.get.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"required":["slug"],"properties":{"slug":{"type":"string","minLength":3,"maxLength":80}}},"deprecated":true,"replacement":"business.shops.get","available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"marketplace.shops.search","version":1,"description":"Deprecated. Search active public Limowo business shops with business.shops.search.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","maxLength":120},"take":{"type":"integer","minimum":1,"maximum":50}}},"deprecated":true,"replacement":"business.shops.search","available":true,"supportsPreparation":true,"supportsExecution":true},{"name":"system.capabilities.list","version":1,"description":"List the typed commands currently exposed by Limowo.","requiredScopes":[],"risk":"READ","approval":"NONE","feature":"DISCOVERY","public":true,"inputSchema":{"type":"object","properties":{},"additionalProperties":false},"available":true,"supportsPreparation":true,"supportsExecution":true}]}