{"openapi":"3.1.0","info":{"title":"Renza API","version":"v1","description":"The Renza v1 API. Resource-oriented, schema-first, with a generated SDK + CLI. See product/09-api-standard.md for the full contract."},"servers":[{"url":"https://api.renza.io","description":"production"},{"url":"http://localhost:3200","description":"local development"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A Renza secret API key: `Authorization: Bearer rza_sk_live_…`."}},"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok"],"example":"ok"},"service":{"type":"string","example":"renza-api"},"version":{"type":"string","example":"v1"},"time":{"type":"string","format":"date-time","example":"2026-06-19T19:00:00.000Z"}},"required":["status","service","version","time"]},"Me":{"type":"object","properties":{"object":{"type":"string","enum":["context"],"example":"context"},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"],"example":"api_key"},"id":{"type":"string","example":"key_8KxQ…"}},"required":["type","id"]},"org":{"type":"object","properties":{"id":{"type":"string","example":"org_3Fy…"},"name":{"type":"string","example":"Paul's workspace"},"type":{"type":"string","enum":["personal","team"],"example":"personal"}},"required":["id","name","type"]},"mode":{"type":"string","enum":["live","test"],"example":"live"},"scopes":{"type":"array","items":{"type":"string"},"example":[]}},"required":["object","actor","org","mode","scopes"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","conflict_error","rate_limit_error","api_error"],"example":"invalid_request_error"},"code":{"type":"string","enum":["parameter_missing","parameter_invalid","resource_not_found","resource_already_exists","resource_unavailable","validation_failed","org_required","access_denied","plan_required","idempotency_conflict","rate_limited","internal_error"],"example":"resource_not_found"},"message":{"type":"string","example":"No deck with that id."},"param":{"type":"string","example":"id"},"request_id":{"type":"string","example":"req_8f2c4a1b"},"doc_url":{"type":"string","example":"https://docs.renza.io/errors/resource_not_found"}},"required":["type","code","message","doc_url"]}},"required":["error"]},"ApiKeyWithSecret":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"secret":{"type":"string","example":"rza_sk_live_8KxQ…Vo","description":"Shown once. Store it now."}},"required":["secret"]}]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","example":"key_8KxQ2v…"},"object":{"type":"string","enum":["api_key"]},"name":{"type":"string","example":"CI deploy key"},"prefix":{"type":"string","example":"rza_sk_live_8KxQ2v"},"last4":{"type":"string","example":"aB3z"},"mode":{"type":"string","enum":["live","test"],"example":"live"},"scopes":{"type":"array","items":{"type":"string"},"example":[]},"kind":{"type":"string","enum":["user","service"],"example":"user","description":"A user key acts as a person; a service key is a machine identity."},"acts_as":{"type":"string","nullable":true,"example":"usr_1a2b…","description":"The user a user key acts as (null for a service key)."},"created_by":{"type":"string","nullable":true,"example":"usr_1a2b…","description":"Who minted the key."},"last_used_at":{"type":"string","nullable":true,"format":"date-time","example":null},"revoked_at":{"type":"string","nullable":true,"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","name","prefix","last4","mode","scopes","kind","acts_as","created_by","last_used_at","revoked_at","created_at"]},"CreateApiKey":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"CI deploy key"},"scopes":{"type":"array","items":{"type":"string"},"example":[]},"service":{"type":"boolean","example":false,"description":"Mint a SERVICE key (a machine identity, no acting user). Default is a USER key that acts as the caller — its actions are authored as you (09 §3)."},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."}},"required":["name"]},"ApiKeyList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"DeckList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Deck"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Deck":{"type":"object","properties":{"id":{"type":"string","example":"deck_2a9f8c1b"},"object":{"type":"string","enum":["deck"]},"title":{"type":"string","example":"Q3 Board Deck"},"status":{"type":"string","example":"draft"},"current_artifact":{"type":"string","nullable":true,"example":"art_7c1b…"},"share_mode":{"type":"string","example":"private"},"external_id":{"type":"string","nullable":true,"example":"q3-board-deck"},"folder":{"type":"string","nullable":true,"example":"fld_7a2c…"},"livemode":{"type":"boolean","example":true},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."},"trashed_at":{"type":"string","nullable":true,"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","title","status","current_artifact","share_mode","external_id","folder","livemode","metadata","trashed_at","created_at","updated_at"]},"CreateDeck":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"example":"Q3 Board Deck"},"status":{"type":"string","example":"draft"},"share_mode":{"type":"string","example":"private"},"external_id":{"type":"string","minLength":1,"maxLength":200,"example":"q3-board-deck"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."}}},"UpdateDeck":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"example":"Q3 Board Deck (final)"},"status":{"type":"string","example":"published"},"share_mode":{"type":"string","example":"link"},"folder":{"type":"string","nullable":true,"example":"fld_7a2c…","description":"Move to a folder, or null for the root."},"current_artifact":{"type":"string","example":"art_7c1b…","description":"Roll the deck back to one of its own prior artifact versions."},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."},"trashed":{"type":"boolean","example":false,"description":"Set false to restore a trashed deck."}}},"DeletedDeck":{"type":"object","properties":{"id":{"type":"string","example":"deck_2a9f8c1b"},"object":{"type":"string","enum":["deck"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]},"Import":{"type":"object","properties":{"id":{"type":"string","example":"imp_5d2a…"},"object":{"type":"string","enum":["import"]},"source":{"type":"string","enum":["upload","paste","url"],"example":"paste"},"status":{"type":"string","enum":["pending","processing","succeeded","failed"],"example":"succeeded"},"deck":{"type":"string","nullable":true,"example":"deck_2a9f8c1b"},"artifact":{"type":"string","nullable":true,"example":"art_7c1b…"},"external_id":{"type":"string","nullable":true,"example":"q3-board-deck"},"error":{"type":"string","nullable":true,"example":null},"livemode":{"type":"boolean","example":true},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","source","status","deck","artifact","external_id","error","livemode","created_at","updated_at"]},"CreateImport":{"type":"object","properties":{"source":{"type":"string","enum":["upload","paste"],"example":"paste"},"html":{"type":"string","minLength":1,"example":"
Slide 1
…","description":"Single-file: the raw deck HTML. Provide this OR `files`."},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"example":"index.html"},"content_base64":{"type":"string","example":"PCFkb2N0eXBl…","description":"Base64-encoded file bytes."}},"required":["path","content_base64"]},"description":"Multi-file bundle (entry HTML + its assets); the entry is auto-detected. Provide this OR `html`. ~3 MB total cap — larger bundles use the web uploader."},"title":{"type":"string","minLength":1,"maxLength":300,"example":"Q3 Board Deck"},"external_id":{"type":"string","minLength":1,"maxLength":200,"example":"q3-board-deck","description":"Reuse + version the deck with this id (update-in-place). Omitted → the server derives a FRESH id from the title (never touching an existing deck) and returns it as `external_id`; republish with it to version the same deck at the same link."}},"required":["source"]},"ImportClaim":{"type":"object","properties":{"object":{"type":"string","enum":["import_claim"]},"deck_ids":{"type":"array","items":{"type":"string"},"example":["deck_2a9f…"],"description":"The decks created from the claimed tries."}},"required":["object","deck_ids"]},"ClaimImports":{"type":"object","properties":{"anon_token":{"type":"string","minLength":1,"example":"anon_9f3c…","description":"The client-held anon token whose anonymous imports to claim."}},"required":["anon_token"]},"ImportList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Import"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"ArtifactList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Artifact":{"type":"object","properties":{"id":{"type":"string","example":"art_7c1b…"},"object":{"type":"string","enum":["artifact"]},"deck":{"type":"string","example":"deck_2a9f8c1b"},"doc_type":{"type":"string","enum":["deck","freeform"],"example":"deck"},"slide_selector":{"type":"string","nullable":true,"example":"[data-renza-slide]"},"active_class":{"type":"string","example":"active"},"slide_count":{"type":"integer","example":12},"content_hash":{"type":"string","example":"9f8c1b2a3d4e5f60"},"self_chromed":{"type":"boolean","example":false},"self_chrome_signals":{"type":"array","items":{"type":"string"},"example":[]},"livemode":{"type":"boolean","example":true},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","deck","doc_type","slide_selector","active_class","slide_count","content_hash","self_chromed","self_chrome_signals","livemode","created_at"]},"ArtifactContent":{"type":"object","properties":{"object":{"type":"string","enum":["artifact_content"]},"artifact":{"type":"string","example":"art_7c1b…"},"deck":{"type":"string","example":"deck_2a9f8c1b"},"entry_path":{"type":"string","nullable":true,"example":"index.html","description":"Set for multi-file bundles; null for single-file."},"html":{"type":"string","example":"…","description":"The entry HTML — edit it (preserving slide anchor ids) and re-publish as a version."}},"required":["object","artifact","deck","entry_path","html"]},"SlideList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Slide"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Slide":{"type":"object","properties":{"id":{"type":"string","example":"sld_3e9f…"},"object":{"type":"string","enum":["slide"]},"artifact":{"type":"string","example":"art_7c1b…"},"index":{"type":"integer","example":0},"anchor_id":{"type":"string","example":"s1"},"title":{"type":"string","nullable":true,"example":"Title slide"}},"required":["id","object","artifact","index","anchor_id","title"]},"OrgList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Org"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Org":{"type":"object","properties":{"id":{"type":"string","example":"org_3Fy…"},"object":{"type":"string","enum":["org"]},"name":{"type":"string","example":"Paul's workspace"},"type":{"type":"string","enum":["personal","team"],"example":"personal"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","name","type","metadata","created_at","updated_at"]},"UpdateOrg":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Acme Inc."},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."}}},"MembershipList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Membership"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Membership":{"type":"object","properties":{"id":{"type":"string","example":"mem_9aB…"},"object":{"type":"string","enum":["membership"]},"user":{"type":"string","example":"usr_2c4…"},"org":{"type":"string","example":"org_3Fy…"},"role":{"type":"string","enum":["owner","admin","member"],"example":"owner"},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","user","org","role","created_at"]},"FolderList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Folder":{"type":"object","properties":{"id":{"type":"string","example":"fld_7a2c…"},"object":{"type":"string","enum":["folder"]},"name":{"type":"string","example":"Clients"},"parent":{"type":"string","nullable":true,"example":null},"livemode":{"type":"boolean","example":true},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."},"trashed_at":{"type":"string","nullable":true,"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","name","parent","livemode","metadata","trashed_at","created_at","updated_at"]},"CreateFolder":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Clients"},"parent_id":{"type":"string","nullable":true,"example":null}}},"FolderWithAncestry":{"allOf":[{"$ref":"#/components/schemas/Folder"},{"type":"object","properties":{"ancestry":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"example":[{"id":"fld_root…","name":"Clients"}],"description":"Root→folder breadcrumb."}},"required":["ancestry"]}]},"UpdateFolder":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Active clients"},"parent_id":{"type":"string","nullable":true,"example":"fld_9b…","description":"Move under this folder, or null for root."},"trashed":{"type":"boolean","example":false,"description":"Set false to restore."}}},"DeletedFolder":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["folder"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]},"Share":{"type":"object","properties":{"id":{"type":"string","example":"shr_7a2c…"},"object":{"type":"string","enum":["share"]},"token":{"type":"string","example":"X3k9...x"},"deck":{"type":"string","example":"deck_2a9f8c1b"},"mode":{"type":"string","enum":["link","public"],"example":"link"},"url":{"type":"string","example":"https://renza.io/v/X3k9…x"},"expires_at":{"type":"string","nullable":true,"format":"date-time","example":null},"revoked_at":{"type":"string","nullable":true,"format":"date-time","example":null},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","token","deck","mode","url","expires_at","revoked_at","created_at"]},"CreateShare":{"type":"object","properties":{"deck":{"type":"string","example":"deck_2a9f8c1b","description":"Deck id or external_id."},"mode":{"type":"string","enum":["link","public"],"example":"link"},"expires_in_days":{"type":"integer","minimum":1,"maximum":365,"example":30,"description":"Link stops resolving after this many days (Renza Pro)."},"password":{"type":"string","minLength":4,"maxLength":72,"description":"Viewers must enter this before the deck serves (Renza Pro). Stored hashed."}},"required":["deck"]},"ShareList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Share"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"PublicShare":{"type":"object","properties":{"object":{"type":"string","enum":["public_share"]},"mode":{"type":"string","enum":["link","public"],"example":"link"},"protected":{"type":"boolean","example":false},"deck":{"type":"object","properties":{"id":{"type":"string","example":"deck_2a9f8c1b"},"title":{"type":"string","nullable":true,"example":"Q3 Board Deck"}},"required":["id","title"]}},"required":["object","mode","protected","deck"]},"CommentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Comment":{"type":"object","properties":{"id":{"type":"string","example":"com_5d2a…"},"object":{"type":"string","enum":["comment"]},"deck":{"type":"string","example":"deck_2a9f…"},"artifact":{"type":"string","nullable":true,"example":"art_7c1b…"},"parent":{"type":"string","nullable":true,"example":null,"description":"The thread root; null for a root."},"author":{"type":"string","nullable":true,"example":"usr_1a2b…"},"slide_index":{"type":"number","nullable":true,"example":2},"anchor":{"$ref":"#/components/schemas/CommentAnchor"},"body":{"type":"string","example":"This number looks off — should it be Q3?"},"resolved":{"type":"boolean","example":false},"resolved_at":{"type":"string","nullable":true,"format":"date-time","example":"2026-06-19T10:30:00.000Z"},"resolved_by":{"type":"string","nullable":true,"example":null},"external_id":{"type":"string","nullable":true,"example":"review-note-1"},"livemode":{"type":"boolean","example":true},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","deck","artifact","parent","author","slide_index","anchor","body","resolved","resolved_at","resolved_by","external_id","livemode","metadata","created_at","updated_at"]},"CommentAnchor":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["element"]},"ref":{"type":"string","example":"h2#title","description":"Element id or structural path."},"refKind":{"type":"string","enum":["id","path"]},"x":{"type":"number","example":0.5,"description":"Offset within the element box, fraction [0,1]."},"y":{"type":"number","example":0.5}},"required":["kind","ref","refKind","x","y"]},{"type":"object","properties":{"kind":{"type":"string","enum":["point"]},"x":{"type":"number","example":0.42,"description":"Slide-relative fraction [0,1]."},"y":{"type":"number","example":0.31}},"required":["kind","x","y"]},{"nullable":true}]},"CreateComment":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000,"example":"This number looks off."},"parent":{"type":"string","example":"com_5d2a…","description":"Reply to this comment."},"deck":{"type":"string","example":"deck_2a9f…"},"artifact":{"type":"string","example":"art_7c1b…","description":"Version the anchor was made on."},"slide_index":{"type":"integer","minimum":0,"example":2},"anchor":{"$ref":"#/components/schemas/CommentAnchor"},"external_id":{"type":"string","minLength":1,"maxLength":200,"example":"review-note-1"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."}},"required":["body"]},"UpdateComment":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000},"resolved":{"type":"boolean","example":true,"description":"Resolve (true) or reopen (false)."},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{},"description":"Arbitrary key/value map; merge-on-write (§6)."}}},"DeletedComment":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["comment"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]},"GrantList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/decks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Grant"}},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":"string","nullable":true,"example":null}},"required":["object","url","data","has_more","next_cursor"]},"Grant":{"type":"object","properties":{"id":{"type":"string","example":"grt_5d2a…"},"object":{"type":"string","enum":["grant"]},"principal_type":{"type":"string","enum":["user","email","group","org"]},"principal":{"type":"string","example":"alice@acme.com"},"resource_type":{"type":"string","enum":["deck","folder"]},"resource":{"type":"string","example":"deck_2a9f…"},"role":{"type":"string","enum":["viewer","commenter","editor"]},"created_by":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-06-19T10:30:00.000Z"}},"required":["id","object","principal_type","principal","resource_type","resource","role","created_by","created_at","updated_at"]},"CreateGrant":{"type":"object","properties":{"principal_type":{"type":"string","enum":["user","email","group","org"],"example":"email"},"principal":{"type":"string","minLength":1,"maxLength":320,"example":"alice@acme.com","description":"User id, email, or group id."},"resource_type":{"type":"string","enum":["deck","folder"],"example":"deck"},"resource":{"type":"string","minLength":1,"example":"deck_2a9f…"},"role":{"type":"string","enum":["viewer","commenter","editor"],"example":"commenter"}},"required":["principal_type","principal","resource_type","resource","role"]},"DeletedGrant":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["grant"]},"deleted":{"type":"boolean","enum":[true]}},"required":["id","object","deleted"]},"CliPairingStart":{"type":"object","properties":{"device_code":{"type":"string","example":"x7Qk9v…","description":"Secret. The CLI polls with this; never shown to the human."},"user_code":{"type":"string","example":"BCDF-2345","description":"Shown in the terminal and the browser so the human can confirm they match."},"verification_uri":{"type":"string","example":"https://renza.io/cli"},"verification_uri_complete":{"type":"string","example":"https://renza.io/cli?code=BCDF2345","description":"Open this; the user_code is prefilled."},"interval":{"type":"number","example":5,"description":"Seconds to wait between polls."},"expires_in":{"type":"number","example":600,"description":"Seconds until the pairing expires."}},"required":["device_code","user_code","verification_uri","verification_uri_complete","interval","expires_in"]},"CliPairingPollResult":{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","denied","expired"],"example":"pending"},"api_key":{"type":"string","example":"rza_sk_live_…","description":"The one-time key secret — present only when status is `approved`."},"org":{"type":"string","nullable":true,"example":"org_8KxQ2v…"}},"required":["status"]},"CliPairingPoll":{"type":"object","properties":{"device_code":{"type":"string","example":"x7Qk9v…"}},"required":["device_code"]},"GuestImportResult":{"type":"object","properties":{"object":{"type":"string","enum":["guest_import"]},"id":{"type":"string","example":"gim_5d2a…"},"url":{"type":"string","example":"https://renza.io/try/gim_5d2a…","description":"The hosted, shareable deck."},"expires_at":{"type":"string","example":"2026-07-07T10:30:00Z"},"updated":{"type":"boolean","description":"True when an existing try was updated in place (matched by `external_id`)."},"external_id":{"type":"string","nullable":true,"example":"renza-intro","description":"The try's stable id (caller-chosen or server-derived). Republish with it to update in place."}},"required":["object","id","url","expires_at","updated","external_id"]},"CreateGuestImport":{"type":"object","properties":{"html":{"type":"string","minLength":1,"example":"
Slide 1
…","description":"Single-file: the raw deck HTML. Provide this OR `files`."},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"example":"index.html"},"content_base64":{"type":"string","description":"Base64-encoded file bytes."}},"required":["path","content_base64"]},"description":"Bounded multi-file bundle (entry + assets), entry auto-detected. Max 20 files / ~3 MB — sign in for larger bundles."},"anon_token":{"type":"string","minLength":1,"example":"anon_9f3c…","description":"A client-held token the import is tracked against (the claim key)."},"external_id":{"type":"string","minLength":1,"maxLength":255,"example":"renza-intro","description":"Stable id, unique per anon token. Republishing with the same one UPDATES the existing try in place — same /try link, fresh content and TTL — instead of minting a new link. Omitted → the server derives a fresh one from the deck title and returns it as `external_id`; reuse it to update in place."}},"required":["anon_token"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["system"],"summary":"Liveness probe","description":"Returns ok when the API is serving. No authentication required.","responses":{"200":{"description":"The service is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/me":{"get":{"tags":["identity"],"summary":"Get the current context","description":"Returns the actor, organization, and mode resolved from the credential. Use it to confirm a key is valid and see which org it acts on.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The resolved request context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/api_keys":{"post":{"tags":["api_keys"],"summary":"Create an API key","description":"Mints a livemode secret key for the active org. The full `secret` is returned exactly once in this response and cannot be retrieved later — store it now.","security":[{"bearerAuth":[]}],"requestBody":{"description":"The key to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKey"}}}},"responses":{"201":{"description":"The created key, including its one-time secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyWithSecret"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["api_keys"],"summary":"List API keys","description":"Lists the active org's API keys (newest first). Secrets are never returned — only `prefix` and `last4` for identification.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The org's API keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/api_keys/{id}":{"delete":{"tags":["api_keys"],"summary":"Revoke an API key","description":"Permanently revokes a key. Already-revoked or unknown keys return 404.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"key_8KxQ2v…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The revoked key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/decks":{"get":{"tags":["decks"],"summary":"List decks","description":"Lists decks in the active org, newest first. Filter by `status`; paginate with `cursor`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","example":"ZGVja18yYTlm"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at.desc","created_at.asc"],"default":"created_at.desc","example":"created_at.desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","example":"published"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["true","false"],"example":"true","description":"List the trash instead of active decks."},"required":false,"description":"List the trash instead of active decks.","name":"trashed","in":"query"},{"schema":{"type":"string","example":"fld_7a2c…","description":"Filter to a folder id, or `root` for unfiled decks."},"required":false,"description":"Filter to a folder id, or `root` for unfiled decks.","name":"folder","in":"query"}],"responses":{"200":{"description":"A page of decks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeckList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["decks"],"summary":"Create or upsert a deck","description":"Creates a deck. If `external_id` is provided and already exists in the org, the existing deck is updated instead (200); otherwise a new deck is created (201).","security":[{"bearerAuth":[]}],"requestBody":{"description":"The deck to create or upsert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeck"}}}},"responses":{"200":{"description":"The upserted (already-existing) deck.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deck"}}}},"201":{"description":"The newly created deck.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deck"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/decks/{id}":{"get":{"tags":["decks"],"summary":"Retrieve a deck","description":"Fetches a deck by Renza id or by `external_id` within the active org.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"deck_2a9f8c1b"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The deck.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deck"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["decks"],"summary":"Update a deck","description":"Partial update — only provided fields change. `metadata` merges (key→value sets, key→null deletes, {} clears all). State transitions are field updates (no verb routes).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"deck_2a9f8c1b"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"Fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDeck"}}}},"responses":{"200":{"description":"The updated deck.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deck"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["decks"],"summary":"Trash or permanently delete a deck","description":"Moves the deck to the trash (soft delete; restore with `PATCH { trashed: false }`). Pass `?permanent=true` to permanently delete an already-trashed deck and its stored content (irreversible).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"deck_2a9f8c1b"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"example":"true"},"required":false,"name":"permanent","in":"query"}],"responses":{"200":{"description":"The trashed deck, or a deletion confirmation when `?permanent=true`.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Deck"},{"$ref":"#/components/schemas/DeletedDeck"}]}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/imports":{"post":{"tags":["imports"],"summary":"Import a deck","description":"Parses the slide contract, stores the HTML, and creates a deck + artifact (+ slides). With `external_id`, re-importing adds a new artifact version to the same deck.","security":[{"bearerAuth":[]}],"requestBody":{"description":"The HTML to import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateImport"}}}},"responses":{"201":{"description":"The completed import (deck + artifact created).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["imports"],"summary":"List imports","description":"Lists imports in the active org, newest first. Filter by `status`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","example":"ZGVja18yYTlm"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at.desc","created_at.asc"],"default":"created_at.desc","example":"created_at.desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["pending","processing","succeeded","failed"],"example":"succeeded"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of imports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/imports/claim":{"post":{"tags":["imports"],"summary":"Claim anonymous imports","description":"Reattributes the anonymous imports tracked against `anon_token` into the active org as real decks (the CLI's `~/.renza` token after `renza login`). Returns the created deck ids.","security":[{"bearerAuth":[]}],"requestBody":{"description":"The anon token to claim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimImports"}}}},"responses":{"200":{"description":"The decks created from the claimed tries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportClaim"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/imports/{id}":{"get":{"tags":["imports"],"summary":"Retrieve an import","description":"Fetches an import by Renza id or by `external_id` within the active org.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"imp_5d2a…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artifacts":{"get":{"tags":["artifacts"],"summary":"List artifacts","description":"Lists artifacts in the active org, newest first. Filter to one deck with `deck`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","example":"ZGVja18yYTlm"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at.desc","created_at.asc"],"default":"created_at.desc","example":"created_at.desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","example":"deck_2a9f8c1b"},"required":false,"name":"deck","in":"query"}],"responses":{"200":{"description":"A page of artifacts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artifacts/{id}/content":{"get":{"tags":["artifacts"],"summary":"Retrieve an artifact's HTML (for editing)","description":"Returns the entry HTML as a data string for the authed owner — the read half of the BYO-AI edit round-trip. Pair with `GET /v1/slides?artifact=` for the sacred anchor ids to preserve, then re-publish as a new version. Served as JSON (never text/html), so it is not a rendered page (05).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"art_7c1b…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The artifact's entry HTML.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactContent"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artifacts/{id}":{"get":{"tags":["artifacts"],"summary":"Retrieve an artifact","description":"Fetches an artifact's metadata by id. The HTML is served only from the content origin.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"art_7c1b…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The artifact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/slides":{"get":{"tags":["slides"],"summary":"List an artifact's slides","description":"Lists the slides of one artifact in index order. The `artifact` query param is required.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"art_7c1b…"},"required":true,"name":"artifact","in":"query"}],"responses":{"200":{"description":"The artifact's slides.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlideList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orgs":{"get":{"tags":["orgs"],"summary":"List orgs","description":"Lists the orgs the credential can act on. A key is bound to one org, so this returns it.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The accessible org(s).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orgs/{id}":{"get":{"tags":["orgs"],"summary":"Retrieve an org","description":"Fetches an org by id. Only the credential's active org is accessible.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"org_3Fy…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The org.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["orgs"],"summary":"Update an org","description":"Partial update of the active org (name; `metadata` merges per §6).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"org_3Fy…"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"Fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrg"}}}},"responses":{"200":{"description":"The updated org.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/memberships":{"get":{"tags":["orgs"],"summary":"List memberships","description":"Lists the members of the credential's active org.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The active org's memberships.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/folders":{"get":{"tags":["folders"],"summary":"List folders","description":"Lists folders at one level: children of `parent` (a folder id), or the root by default. `trashed=true` lists trashed folders.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"fld_7a2c…"},"required":false,"name":"parent","in":"query"},{"schema":{"type":"string","enum":["true","false"],"example":"true"},"required":false,"name":"trashed","in":"query"}],"responses":{"200":{"description":"Folders at this level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["folders"],"summary":"Create a folder","description":"Creates a folder, optionally under `parent_id` (omit/null for the root).","security":[{"bearerAuth":[]}],"requestBody":{"description":"The folder to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFolder"}}}},"responses":{"201":{"description":"The created folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/folders/{id}":{"get":{"tags":["folders"],"summary":"Retrieve a folder","description":"Fetches a folder with its root→folder ancestry (for breadcrumbs).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"fld_7a2c…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderWithAncestry"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["folders"],"summary":"Update a folder","description":"Rename (`name`), move (`parent_id`), or restore (`trashed: false`). Moving into a descendant or exceeding max depth is rejected.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"fld_7a2c…"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"Fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFolder"}}}},"responses":{"200":{"description":"The updated folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Folder"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["folders"],"summary":"Trash or permanently delete a folder","description":"Trashes the folder and its subtree (restore with `PATCH { trashed: false }`). `?permanent=true` permanently deletes an already-trashed folder + its contents (irreversible).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"fld_7a2c…"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"example":"true"},"required":false,"name":"permanent","in":"query"}],"responses":{"200":{"description":"The trashed folder, or a deletion confirmation when `?permanent=true`.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Folder"},{"$ref":"#/components/schemas/DeletedFolder"}]}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/shares":{"post":{"tags":["shares"],"summary":"Share a deck","description":"Mints a share token (link or public) for a deck and sets the deck's share mode. Anyone with the resulting link can view — no account needed.","security":[{"bearerAuth":[]}],"requestBody":{"description":"The deck to share.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShare"}}}},"responses":{"201":{"description":"The created share.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Share"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["shares"],"summary":"List a deck's shares","description":"Lists the share tokens for a deck (newest first), including revoked ones.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"deck_2a9f8c1b"},"required":true,"name":"deck","in":"query"}],"responses":{"200":{"description":"The deck's shares.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/shares/{id}":{"delete":{"tags":["shares"],"summary":"Revoke a share","description":"Revokes a share token; its link 404s immediately. Other shares of the deck are unaffected.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"shr_7a2c…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The revoked share.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Share"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/shares/{token}":{"get":{"tags":["shares"],"summary":"Resolve a share token (public)","description":"Public, unauthenticated: resolve a share token to public-safe deck info. Returns 404 for unknown/revoked/expired tokens (no oracle). The artifact itself is served only from the content origin.","parameters":[{"schema":{"type":"string","example":"X3k9…x"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"The resolved share.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicShare"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/comments":{"get":{"tags":["comments"],"summary":"List comments","description":"Lists comments in the active org, newest first. Filter by `deck`, `slide_index`, `resolved`, or `parent`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","example":"ZGVja18yYTlm"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at.desc","created_at.asc"],"default":"created_at.desc","example":"created_at.desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","example":"deck_2a9f…"},"required":false,"name":"deck","in":"query"},{"schema":{"type":"integer","nullable":true,"example":2},"required":false,"name":"slide_index","in":"query"},{"schema":{"type":"string","enum":["true","false"],"example":"false","description":"Only open or only resolved."},"required":false,"description":"Only open or only resolved.","name":"resolved","in":"query"},{"schema":{"type":"string","example":"com_5d2a…","description":"Replies under this thread root."},"required":false,"description":"Replies under this thread root.","name":"parent","in":"query"}],"responses":{"200":{"description":"A page of comments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["comments"],"summary":"Create a comment or reply","description":"Creates a thread root (`deck` + `slide_index` + `anchor`) or a reply (`parent`). If `external_id` is provided and already exists in the org, the existing comment's body is updated instead (200).","security":[{"bearerAuth":[]}],"requestBody":{"description":"The comment to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateComment"}}}},"responses":{"200":{"description":"The upserted (already-existing) comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}},"201":{"description":"The newly created comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/comments/{id}":{"get":{"tags":["comments"],"summary":"Retrieve a comment","description":"Fetches a comment by Renza id or by `external_id` within the active org.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"com_5d2a…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["comments"],"summary":"Update a comment","description":"Partial update — only provided fields change. `resolved` resolves/reopens the thread (a field update, not a verb route). `metadata` merges (key→value sets, key→null deletes, {} clears all).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"com_5d2a…"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"Fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateComment"}}}},"responses":{"200":{"description":"The updated comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["comments"],"summary":"Delete a comment","description":"Permanently deletes a comment (irreversible). Deleting a thread root also deletes its replies.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"com_5d2a…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The deletion confirmation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedComment"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/grants":{"get":{"tags":["grants"],"summary":"List grants","description":"Lists access grants in the active org. Filter by `resource`/`resource_type` or `principal`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","example":"ZGVja18yYTlm"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["created_at.desc","created_at.asc"],"default":"created_at.desc","example":"created_at.desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","enum":["deck","folder"]},"required":false,"name":"resource_type","in":"query"},{"schema":{"type":"string","example":"deck_2a9f…"},"required":false,"name":"resource","in":"query"},{"schema":{"type":"string"},"required":false,"name":"principal","in":"query"}],"responses":{"200":{"description":"A page of grants.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantList"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["grants"],"summary":"Grant access","description":"Grants a principal a role on a resource (folder grants cascade to the subtree). If a grant for that principal+resource already exists, its role is updated (200); otherwise a grant is created (201).","security":[{"bearerAuth":[]}],"requestBody":{"description":"The access to grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGrant"}}}},"responses":{"200":{"description":"The updated grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"201":{"description":"The new grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/grants/{id}":{"get":{"tags":["grants"],"summary":"Retrieve a grant","description":"Fetches a single access grant by id within the active org.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"grt_5d2a…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["grants"],"summary":"Revoke a grant","description":"Revokes the grant (the principal loses any access it conferred).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"grt_5d2a…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The revocation confirmation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedGrant"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/auth/cli/start":{"post":{"tags":["auth"],"summary":"Begin CLI browser pairing","description":"Public. Starts a device pairing for `renza login`: returns a secret `device_code` (poll with it) and a short `user_code` + browser URL where the user approves it — minting a user key that acts as them.","responses":{"201":{"description":"The started pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CliPairingStart"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/auth/cli/poll":{"post":{"tags":["auth"],"summary":"Poll a CLI pairing","description":"Public. The CLI polls with its `device_code`. While the user hasn't acted → `pending`; once approved → `approved` with the one-time `api_key` (the pairing is then consumed); else `denied` / `expired`.","requestBody":{"description":"The device code from `start`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CliPairingPoll"}}}},"responses":{"200":{"description":"The current pairing status (and the key once approved).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CliPairingPollResult"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/imports":{"post":{"tags":["imports"],"summary":"Anonymous import (no auth)","description":"Public. Hosts a single HTML deck without an account and tracks it against the supplied `anon_token`, returning a `/try/` link. Pass the same `external_id` again to update that try in place (same link). Sign in later and claim the token's imports into a real org. Larger/multi-file imports require authentication.","requestBody":{"description":"The HTML to host anonymously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGuestImport"}}}},"responses":{"200":{"description":"An existing try, updated in place (matched by `external_id`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestImportResult"}}}},"201":{"description":"The hosted anonymous import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestImportResult"}}}},"400":{"description":"Invalid request — bad or missing parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but not permitted (or no org).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — idempotency or state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}