{ "openapi": "3.1.0", "info": { "title": "BrandApp Playground API", "version": "1.0.0", "summary": "Server-side proxy routes the playground uses to reach a Reopt BrandApp.", "description": "Every route here is a thin server-side proxy in front of a Reopt BrandApp.\nThree credential paths exist and they are not interchangeable:\n\n- `brandappBasic` — app-scoped `clientId:clientSecret`, resolved on the server\n from the connection cookie or the environment. Never sent by the client.\n- `reoptOAuth` — the signed-in user's access token, forwarded by the route.\n User-scoped operations declare the exact scopes they need.\n- `webhookSignature` / `logoutToken` — inbound callbacks authenticated by a\n signature rather than by a caller credential.\n\nRoutes marked with an empty `security` array manage this deployment's own\nconnection state and require no credential.", "contact": { "name": "주식회사 리옵트", "email": "contact@reopt.ai", "url": "https://github.com/reopt-ai/brandapp-playground/issues" }, "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://brandapp-playground.vercel.app", "description": "This deployment" } ], "externalDocs": { "description": "Markdown documentation index for agents", "url": "https://brandapp-playground.vercel.app/llms.txt" }, "tags": [ { "name": "connection", "description": "Credential mode for this deployment." }, { "name": "health", "description": "Non-destructive probes and user visibility." }, { "name": "eav", "description": "Entity-Attribute-Value data." }, { "name": "ai", "description": "Text and image generation." }, { "name": "cms", "description": "Read-only content." }, { "name": "files", "description": "Files, folders, and storage usage." }, { "name": "plans", "description": "Plan catalog, checkout, and cancellation." }, { "name": "terms", "description": "Agreement consent." }, { "name": "webhooks", "description": "Signed inbound events." }, { "name": "auth", "description": "Session and logout callbacks." } ], "paths": { "/api/connection": { "get": { "tags": [ "connection" ], "summary": "Read the active credential mode and masked credentials.", "operationId": "getApiConnection", "security": [], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "connection" ], "summary": "Store BrandApp credentials in the sealed httpOnly cookie.", "operationId": "postApiConnection", "security": [], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "connection" ], "summary": "Clear the credential cookie and revert to the deployment default.", "operationId": "deleteApiConnection", "security": [], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health": { "get": { "tags": [ "health" ], "summary": "Stream the non-destructive probe suite as Server-Sent Events.", "operationId": "getApiHealth", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health/summary": { "get": { "tags": [ "health" ], "summary": "Return the latest probe results as a single JSON document.", "operationId": "getApiHealthSummary", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health/customer-info": { "get": { "tags": [ "health" ], "summary": "Resolve the signed-in user's session, access token, userinfo, and linked customer.", "operationId": "getApiHealthCustomer-info", "security": [ { "reoptOAuth": [ "openid", "profile", "email", "brandapp:read" ] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health/customer-info/withdraw": { "post": { "tags": [ "health" ], "summary": "Soft-withdraw the signed-in customer; the record is retained so re-linking restores it.", "operationId": "postApiHealthCustomer-infoWithdraw", "security": [ { "reoptOAuth": [ "brandapp:write" ] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/eav/{entityId}/records": { "get": { "tags": [ "eav" ], "summary": "List records for an entity.", "operationId": "getApiEavEntityIdRecords", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "eav" ], "summary": "Create a record.", "operationId": "postApiEavEntityIdRecords", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "eav" ], "summary": "Bulk-update records matching a filter.", "operationId": "patchApiEavEntityIdRecords", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/eav/{entityId}/records/{recordId}": { "patch": { "tags": [ "eav" ], "summary": "Update a single record.", "operationId": "patchApiEavEntityIdRecordsRecordId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "eav" ], "summary": "Delete a single record.", "operationId": "deleteApiEavEntityIdRecordsRecordId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/eav/{entityId}/filter": { "post": { "tags": [ "eav" ], "summary": "Apply an AttributeFilter[] built with the where() DSL.", "operationId": "postApiEavEntityIdFilter", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/eav/schema/sync": { "post": { "tags": [ "eav" ], "summary": "Run schema sync against the connected BrandApp.", "operationId": "postApiEavSchemaSync", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/chat": { "post": { "tags": [ "ai" ], "summary": "Stream a text completion over Server-Sent Events.", "operationId": "postApiAiChat", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/image": { "post": { "tags": [ "ai" ], "summary": "Generate an image and report its credit cost.", "operationId": "postApiAiImage", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/credits": { "get": { "tags": [ "ai" ], "summary": "Read the AI credit balance and status.", "operationId": "getApiAiCredits", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cms/posts": { "get": { "tags": [ "cms" ], "summary": "List published posts.", "operationId": "getApiCmsPosts", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cms/posts/{postId}": { "get": { "tags": [ "cms" ], "summary": "Fetch one post by id.", "operationId": "getApiCmsPostsPostId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cms/post-groups": { "get": { "tags": [ "cms" ], "summary": "List post groups.", "operationId": "getApiCmsPost-groups", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cms/tags": { "get": { "tags": [ "cms" ], "summary": "List the tags used in the brand scope.", "operationId": "getApiCmsTags", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/files": { "get": { "tags": [ "files" ], "summary": "List files.", "operationId": "getApiFiles", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/files/upload": { "post": { "tags": [ "files" ], "summary": "Upload a file. Bounded by PLAYGROUND_MAX_UPLOAD_BYTES.", "operationId": "postApiFilesUpload", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/files/{fileId}": { "get": { "tags": [ "files" ], "summary": "Read file metadata.", "operationId": "getApiFilesFileId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "files" ], "summary": "Rename or move a file.", "operationId": "patchApiFilesFileId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "files" ], "summary": "Delete a file.", "operationId": "deleteApiFilesFileId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/files/{fileId}/content": { "get": { "tags": [ "files" ], "summary": "Stream a file's contents for text preview.", "operationId": "getApiFilesFileIdContent", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/files/folders": { "get": { "tags": [ "files" ], "summary": "List folders.", "operationId": "getApiFilesFolders", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "files" ], "summary": "Create a folder.", "operationId": "postApiFilesFolders", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/files/folders/{folderId}": { "patch": { "tags": [ "files" ], "summary": "Rename or move a folder.", "operationId": "patchApiFilesFoldersFolderId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "files" ], "summary": "Delete a folder.", "operationId": "deleteApiFilesFoldersFolderId", "security": [ { "brandappBasic": [] } ], "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/files/usage": { "get": { "tags": [ "files" ], "summary": "Read storage usage for the connected BrandApp.", "operationId": "getApiFilesUsage", "security": [ { "brandappBasic": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/plans/checkout": { "post": { "tags": [ "plans" ], "summary": "Create a hosted checkout session for a plan.", "operationId": "postApiPlansCheckout", "security": [ { "reoptOAuth": [ "brandapp:write" ] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/plans/checkout-status": { "get": { "tags": [ "plans" ], "summary": "Poll a checkout session and the resulting entitlement.", "operationId": "getApiPlansCheckout-status", "security": [ { "reoptOAuth": [ "brandapp:read" ] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/plans/cancel": { "post": { "tags": [ "plans" ], "summary": "Cancel the signed-in customer's subscription.", "operationId": "postApiPlansCancel", "security": [ { "reoptOAuth": [ "brandapp:write" ] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/terms/me/consents": { "get": { "tags": [ "terms" ], "summary": "List the signed-in user's recorded consents.", "operationId": "getApiTermsMeConsents", "security": [ { "reoptOAuth": [ "brandapp:read" ] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "terms" ], "summary": "Record consent to an agreement.", "operationId": "postApiTermsMeConsents", "security": [ { "reoptOAuth": [ "brandapp:write" ] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/terms/me/consents/{consentId}": { "delete": { "tags": [ "terms" ], "summary": "Withdraw a recorded consent.", "operationId": "deleteApiTermsMeConsentsConsentId", "security": [ { "reoptOAuth": [ "brandapp:write" ] } ], "parameters": [ { "name": "consentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/webhooks/reopt": { "post": { "tags": [ "webhooks" ], "summary": "Receive a signed BrandApp webhook. Replays past the tolerance window return 410.", "operationId": "postApiWebhooksReopt", "security": [ { "webhookSignature": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/backchannel-logout": { "post": { "tags": [ "auth" ], "summary": "Receive an OIDC back-channel logout token and end the matching local sessions.", "operationId": "postApiAuthBackchannel-logout", "security": [ { "logoutToken": [] } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Missing or rejected credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed; see fieldErrors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure message." }, "code": { "type": "string", "description": "Stable SDK error code, when the failure came from the SDK." }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field-level messages on a 422 validation failure." }, "diagnostic": { "type": "object", "description": "Agent-readable remediation hint attached to structured SDK errors.", "properties": { "cause": { "type": "string" }, "fix": { "type": "string" }, "envVar": { "type": "string" }, "doc": { "type": "string", "format": "uri" } } } } } }, "securitySchemes": { "brandappBasic": { "type": "http", "scheme": "basic", "description": "App-scoped BrandApp Client Credentials (`clientId:clientSecret`). Grants access to every record in the BrandApp, so it is resolved and used server-side only and never reaches the browser." }, "reoptOAuth": { "type": "oauth2", "description": "An end user's Reopt OAuth access token, forwarded by the route to the BrandApp. Scoped to that user: it can read and mutate only their own customer link, consents, and subscription.", "flows": { "authorizationCode": { "authorizationUrl": "https://id.reopt.ai/api/auth/oauth2/authorize", "tokenUrl": "https://id.reopt.ai/api/auth/oauth2/token", "refreshUrl": "https://id.reopt.ai/api/auth/oauth2/token", "scopes": { "openid": "Issue an OIDC identity token.", "profile": "Read the user's profile claims.", "email": "Read the user's email address.", "offline_access": "Issue a refresh token.", "brandapp:read": "Read the user's linked BrandApp customer, consents, and plan.", "brandapp:write": "Link or withdraw the customer, record consent, and change the plan." } } } }, "reoptOidc": { "type": "openIdConnect", "openIdConnectUrl": "https://id.reopt.ai/.well-known/openid-configuration", "description": "The same user credential, described by discovery. Reopt ID is the authorization server; this deployment is only a relying party, so the authoritative endpoint list lives at the issuer, not here." }, "webhookSignature": { "type": "apiKey", "in": "header", "name": "x-reopt-signature", "description": "HMAC-SHA256 over `{timestamp}.{body}` using the BrandApp webhook secret, sent with `x-reopt-timestamp`. Deliveries older than the tolerance window (5 minutes by default) are rejected with 410." }, "logoutToken": { "type": "apiKey", "in": "header", "name": "authorization", "description": "An OIDC back-channel logout token signed by Reopt, verified against the published JWKS with Ed25519." } } } }