{"openapi":"3.1.0","info":{"title":"Room & Story agent API","version":"1.1.0","description":"Public Streamable HTTP MCP with per-account agent keys. Create a key at /agents/connect. See /agents/guide for setup, budget and retry behavior."},"servers":[{"url":"https://roomandstory.com"}],"paths":{"/api/mcp":{"post":{"operationId":"mcpRequest","summary":"Public MCP JSON-RPC request","security":[{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number"]},"method":{"type":"string","enum":["initialize","notifications/initialized","server/discover","ping","tools/list","tools/call"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC result; inspect isError for tool failures"},"202":{"description":"Notification accepted"},"401":{"description":"Missing, expired or revoked key"},"403":{"description":"Invalid browser Origin"},"503":{"description":"Temporary service failure"}}}},"/api/agents/assets/{id}":{"get":{"operationId":"downloadAgentAsset","summary":"Download a private account asset; existing watermark rules apply","security":[{"AgentKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"download","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Private image bytes"},"401":{"description":"Invalid key"},"404":{"description":"Asset absent or not owned by this account"}}}},"/api/agents":{"get":{"operationId":"getCapabilities","summary":"Read public capabilities","responses":{"200":{"description":"Supported operations and limits"}}}}},"components":{"securitySchemes":{"AgentKey":{"type":"http","scheme":"bearer","bearerFormat":"Room & Story agent key","description":"Create a key at https://roomandstory.com/agents/connect. Each key has an account scope, render allowance and expiry."}}},"x-mcp-tools":[{"name":"get_capabilities","description":"Read supported styles, rooms, formats, credit cost and connection requirements. No render is created.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"upload_image","description":"Save a private room image (base64, maximum 9 MiB). Requires the connected user to accept upload terms in Data & privacy first. Does not generate or spend credits.","inputSchema":{"type":"object","properties":{"mime":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"data":{"type":"string","description":"Raw base64 image bytes, without a data URL prefix. Maximum 9 MiB decoded."}},"required":["mime","data"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"quote_project","description":"Validate an uploaded image and design brief and quote exactly one image credit. Does not reserve credits or generate. Quote expires after 15 minutes.","inputSchema":{"type":"object","properties":{"source":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Property or project name"},"mode":{"type":"string","enum":["staging","redesign"]},"room":{"type":"string","description":"Exact room name from get_capabilities"},"style":{"type":"string","description":"Style ID from get_capabilities"},"palette":{"type":"string","description":"Palette ID from get_capabilities"},"instructions":{"type":"string","description":"Optional design instructions, at most 1500 characters"}},"required":["source","name","mode","room","style","palette"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"create_render","description":"Spend at most one existing image credit to submit the quoted design. Only call within the user’s authorized budget. Reuse the exact quote on retries to prevent duplicate charges. Never automatically request a new quote after an uncertain response.","inputSchema":{"type":"object","properties":{"quote":{"type":"string","description":"Opaque quote token returned by quote_project"},"max_credits":{"type":"integer","const":1}},"required":["quote","max_credits"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true}},{"name":"get_job","description":"Read or reconcile a saved render owned by the connected account. Poll no more often than every 15 seconds. Never regenerate a saved result.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"export_project","description":"Return the original and generated concept download links for one completed render. Optionally include a small image preview. Full-resolution downloads use the owner’s session or authenticated agent download endpoint. Does not publish or make files public.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"include_image":{"type":"boolean","default":false}},"required":["id"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}]}