{ "openapi": "3.1.0", "info": { "title": "SupaKnock API", "description": "SupaKnock installation API for feedback, chat and administration. The same routes serve the web app, iPhone app and trusted backend integrations. Public feedback reads need no credentials; private data is filtered by the acting account and project. Cookie mutations require CSRF and the installation Origin. Administrator bearer sessions do not require CSRF. Project keys belong only on trusted servers. Customer and visitor chat credentials use X-Chat-Token and never grant administration.\n\nThe API contract is the same with SQLite, PostgreSQL and Supabase PostgreSQL. Configure the database on the server; clients never connect to installation tables. See /api-docs for integration examples. WebSocket chat is described separately in x-websockets because OpenAPI paths describe HTTP operations.", "version": "1.0.0", "license": { "name": "MIT", "identifier": "MIT" } }, "paths": { "/healthz": { "get": { "tags": [ "Health" ], "summary": "Check that the HTTP process is running", "operationId": "health_healthz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthOutput" } } } } }, "security": [], "description": "Unauthenticated process liveness check; this does not check the database." } }, "/readyz": { "get": { "tags": [ "Health" ], "summary": "Check the installation database connection", "operationId": "ready_readyz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthOutput" } } } }, "500": { "description": "The database check could not complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The PostgreSQL connection is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [], "description": "Unauthenticated database connectivity check. A successful query returns ok=true; a database error uses the standard error envelope." } }, "/api/v1/setup": { "get": { "tags": [ "Authentication" ], "summary": "Check whether initial setup is available", "operationId": "setup_state_api_v1_setup_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [], "description": "No existing session is required. Setup requires the deployment setup token and is available only before the first administrator exists. Registration creates participants only and is unavailable before setup or when registration is disabled. Browser sign-in returns feedback_session and feedback_csrf cookies plus the csrf_token in JSON." }, "post": { "tags": [ "Authentication" ], "summary": "Create the first administrator", "description": "Requires the deployment setup token. Atomically creates the first administrator and permanently disables setup.\n\nNo existing session is required. Setup requires the deployment setup token and is available only before the first administrator exists. Registration creates participants only and is unavailable before setup or when registration is disabled. Browser sign-in returns feedback_session and feedback_csrf cookies plus the csrf_token in JSON.", "operationId": "setup_api_v1_setup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupInput" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ] } }, "/api/v1/auth/register": { "post": { "tags": [ "Authentication" ], "summary": "Create a participant account", "description": "Creates a participant. Email is a login identifier, not verified.\n\nNo existing session is required. Setup requires the deployment setup token and is available only before the first administrator exists. Registration creates participants only and is unavailable before setup or when registration is disabled. Browser sign-in returns feedback_session and feedback_csrf cookies plus the csrf_token in JSON.", "operationId": "register_api_v1_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountInput" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ] } }, "/api/v1/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Sign in with a browser session", "operationId": "login_api_v1_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "No existing session is required. Setup requires the deployment setup token and is available only before the first administrator exists. Registration creates participants only and is unavailable before setup or when registration is disabled. Browser sign-in returns feedback_session and feedback_csrf cookies plus the csrf_token in JSON." } }, "/api/v1/auth/me": { "get": { "tags": [ "Authentication" ], "summary": "Read the signed-in account", "operationId": "me_api_v1_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "description": "A local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. Project and chat credentials do not authenticate a local account." } }, "/api/v1/auth/native/login": { "post": { "tags": [ "Authentication" ], "summary": "Sign in as an administrator with a bearer session", "operationId": "native_login_api_v1_auth_native_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeSessionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "Administrator email and password required. Returns a revocable ns_ bearer session without a browser cookie. Use expires_at; the duration is installation-configurable (seven days by default). Omit existing Authorization and feedback_session credentials. Participant accounts cannot use this login." } }, "/api/v1/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Revoke the current account session", "operationId": "logout_api_v1_auth_logout_post", "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "A local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. Project and chat credentials do not authenticate a local account.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/auth/password": { "post": { "tags": [ "Authentication" ], "summary": "Change a password and revoke all account sessions", "description": "Changes the password and revokes every existing session, including this one.\n\nA local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. Project and chat credentials do not authenticate a local account.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "password_api_v1_auth_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordInput" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ] } }, "/api/v1/admin/accounts": { "post": { "tags": [ "Administration" ], "summary": "Create another administrator", "operationId": "add_admin_api_v1_admin_accounts_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountInput" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/admin/account-activity": { "get": { "tags": [ "Administration" ], "summary": "List successful account creation and sign-in activity", "description": "Native administrators only. Durable successful signup/setup, account creation and login history, newest first with stable ID ordering. IPs are observed connection addresses, not identity proof. Session expiry does not erase history. Optional user_id scopes the list to one account.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "account_activity_api_v1_admin_account_activity_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "User Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_AccountActivityOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/admin/push": { "get": { "tags": [ "Push" ], "summary": "Read push relay settings", "operationId": "push_settings_api_v1_admin_push_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nSupaKnock\u2019s optional iPhone push relay is https://relay.supaknock.com. Call this settings endpoint on your own installation, not on the relay. Feedback and chat also use your installation. The server enrolls with the relay and keeps its credential encrypted; clients never receive it." }, "put": { "tags": [ "Push" ], "summary": "Configure the optional push relay", "operationId": "push_configure_api_v1_admin_push_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nSupaKnock\u2019s optional iPhone push relay is https://relay.supaknock.com. Call this settings endpoint on your own installation, not on the relay. Feedback and chat also use your installation. The server enrolls with the relay and keeps its credential encrypted; clients never receive it.\n\nTo enable push, send {\"enabled\":true,\"relay_url\":\"https://relay.supaknock.com\"}. Use the HTTPS origin without /api/v1. Push is off by default. You may choose a compatible self-hosted relay before enrollment; the enrolled origin cannot be changed through this setting.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/admin/push/rotate": { "post": { "tags": [ "Push" ], "summary": "Rotate the installation's push relay credential", "operationId": "push_rotate_api_v1_admin_push_rotate_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/admin/push/deliveries": { "get": { "tags": [ "Push" ], "summary": "List push delivery attempts", "operationId": "push_deliveries_api_v1_admin_push_deliveries_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_PushDeliveryOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." } }, "/api/v1/admin/push/deliveries/{delivery_id}/retry": { "post": { "tags": [ "Push" ], "summary": "Retry a push delivery", "operationId": "push_retry_api_v1_admin_push_deliveries__delivery_id__retry_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Delivery Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/admin/devices": { "get": { "tags": [ "Push" ], "summary": "List registered push devices", "operationId": "devices_api_v1_admin_devices_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicesOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials." } }, "/api/v1/admin/devices/{device_id}": { "put": { "tags": [ "Push" ], "summary": "Register or update a push device", "operationId": "register_device_api_v1_admin_devices__device_id__put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Device Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." }, "delete": { "tags": [ "Push" ], "summary": "Remove a push device", "operationId": "remove_device_api_v1_admin_devices__device_id__delete", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Device Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/admin/dashboard": { "get": { "tags": [ "Administration" ], "summary": "Read administrator dashboard counts", "operationId": "dashboard_api_v1_admin_dashboard_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials." } }, "/api/v1/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects", "operationId": "projects_api_v1_projects_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "archive", "in": "query", "required": false, "schema": { "enum": [ "active", "archived", "all" ], "type": "string", "default": "active", "title": "Archive" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_ProjectOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrators can list the installation directory. A project credential with read or manage permission sees only its own project. Visitors and regular accounts cannot list projects; use a creator-supplied direct project or board link.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." }, "post": { "tags": [ "Projects" ], "summary": "Create a project", "operationId": "create_project_api_v1_projects_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}": { "get": { "tags": [ "Projects" ], "summary": "Read a project", "operationId": "project_api_v1_projects__project__get", "security": [ {}, { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Anonymous public read. A supplied project credential needs read or manage permission for the resource\u2019s project. Unpublished requests are visible only to their creator or a manager; unauthorized detail reads return 404. Archived resources and archive filters other than active require administrator access." }, "patch": { "tags": [ "Projects" ], "summary": "Edit a project", "operationId": "update_project_api_v1_projects__project__patch", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEdit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/archive": { "put": { "tags": [ "Projects" ], "summary": "Archive or restore a project", "description": "Native administrators only. Versioned archive/restore; preserves history and pauses new activity.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "archive_project_api_v1_projects__project__archive_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/boards": { "get": { "tags": [ "Boards" ], "summary": "List a project's boards", "operationId": "boards_api_v1_projects__project__boards_get", "security": [ {}, { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "archive", "in": "query", "required": false, "schema": { "enum": [ "active", "archived", "all" ], "type": "string", "default": "active", "title": "Archive" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_BoardOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Anonymous public read. A supplied project credential needs read or manage permission for the resource\u2019s project. Unpublished requests are visible only to their creator or a manager; unauthorized detail reads return 404. Archived resources and archive filters other than active require administrator access.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." }, "post": { "tags": [ "Boards" ], "summary": "Create a board", "operationId": "create_board_api_v1_projects__project__boards_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feedback__outputs__BoardOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/boards/{board}": { "get": { "tags": [ "Boards" ], "summary": "Read a board", "operationId": "board_api_v1_boards__board__get", "security": [ {}, { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "schema": { "type": "string", "title": "Board" }, "description": "Board UUID, returned when listing or creating boards. A board identifier alone is not a global reference." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feedback__outputs__BoardOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Anonymous public read. A supplied project credential needs read or manage permission for the resource\u2019s project. Unpublished requests are visible only to their creator or a manager; unauthorized detail reads return 404. Archived resources and archive filters other than active require administrator access." }, "patch": { "tags": [ "Boards" ], "summary": "Edit a board", "operationId": "update_board_api_v1_boards__board__patch", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "schema": { "type": "string", "title": "Board" }, "description": "Board UUID, returned when listing or creating boards. A board identifier alone is not a global reference." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceEdit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feedback__outputs__BoardOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/boards/{board}/archive": { "put": { "tags": [ "Boards" ], "summary": "Archive or restore a board", "description": "Native administrators only. Versioned archive/restore. Restore the parent project before restoring a board.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "archive_board_api_v1_boards__board__archive_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "schema": { "type": "string", "title": "Board" }, "description": "Board UUID, returned when listing or creating boards. A board identifier alone is not a global reference." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feedback__outputs__BoardOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/boards/{board}/requests": { "get": { "tags": [ "Requests" ], "summary": "List a board's visible requests", "operationId": "board_requests_api_v1_boards__board__requests_get", "security": [ {}, { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "schema": { "type": "string", "title": "Board" }, "description": "Board UUID, returned when listing or creating boards. A board identifier alone is not a global reference." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "under_consideration", "planned", "in_progress", "shipped" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "order", "in": "query", "required": false, "schema": { "enum": [ "newest", "popular" ], "type": "string", "default": "newest", "title": "Order" } }, { "name": "external_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ], "description": "Opaque project-scoped participant ID. Requires a participate credential; never a login credential.", "title": "External User Id" }, "description": "Exact opaque ID verified by your backend, with a participate project credential. Preserve case, whitespace and Unicode; the ID alone grants no access." }, { "name": "moderation", "in": "query", "required": false, "schema": { "enum": [ "accepted", "pending", "rejected", "all" ], "type": "string", "default": "accepted", "title": "Moderation" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_RequestOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Anonymous public read. A supplied project credential needs read or manage permission for the resource\u2019s project. Unpublished requests are visible only to their creator or a manager; unauthorized detail reads return 404. Archived resources and archive filters other than active require administrator access.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." }, "post": { "tags": [ "Requests" ], "summary": "Submit a request for moderation", "operationId": "submit_api_v1_boards__board__requests_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "schema": { "type": "string", "title": "Board" }, "description": "Board UUID, returned when listing or creating boards. A board identifier alone is not a global reference." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Submission" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "A local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. A trusted project backend may instead use an fb_ bearer credential with participate permission and the verified external_user_id. The ID is opaque, project-scoped and case-sensitive: preserve it exactly, including whitespace and Unicode. It is never a credential and does not link accounts across projects. Internal user IDs supplied by a client cannot select an acting participant.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/me/requests": { "get": { "tags": [ "Requests" ], "summary": "List the acting participant's requests", "description": "Native account submissions across projects. Project credentials require external_user_id and participate; resolution is automatic.\n\nA local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. A trusted project backend may instead use an fb_ bearer credential with participate permission and the verified external_user_id. The ID is opaque, project-scoped and case-sensitive: preserve it exactly, including whitespace and Unicode. It is never a credential and does not link accounts across projects. Internal user IDs supplied by a client cannot select an acting participant.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "own_requests_api_v1_me_requests_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "external_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ], "description": "Opaque project-scoped participant ID. Requires a participate credential; never a login credential.", "title": "External User Id" }, "description": "Exact opaque ID verified by your backend, with a participate project credential. Preserve case, whitespace and Unicode; the ID alone grants no access." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_RequestOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/moderation": { "get": { "tags": [ "Moderation" ], "summary": "List requests awaiting moderation", "description": "Installation queue for admins; project queue for manage credentials. Pending by default.\n\nNative administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "moderation_api_v1_moderation_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, { "name": "state", "in": "query", "required": false, "schema": { "enum": [ "pending", "rejected", "accepted" ], "type": "string", "default": "pending", "title": "State" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_RequestOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/requests/{request_id}": { "get": { "tags": [ "Requests" ], "summary": "Read a visible request", "operationId": "detail_api_v1_requests__request_id__get", "security": [ {}, { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "name": "external_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ], "description": "Opaque project-scoped participant ID. Requires a participate credential; never a login credential.", "title": "External User Id" }, "description": "Exact opaque ID verified by your backend, with a participate project credential. Preserve case, whitespace and Unicode; the ID alone grants no access." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Anonymous public read. A supplied project credential needs read or manage permission for the resource\u2019s project. Unpublished requests are visible only to their creator or a manager; unauthorized detail reads return 404. Archived resources and archive filters other than active require administrator access." }, "patch": { "tags": [ "Requests" ], "summary": "Edit or resubmit your request", "operationId": "edit_api_v1_requests__request_id__patch", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatorEdit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "A local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. A trusted project backend may instead use an fb_ bearer credential with participate permission and the verified external_user_id. The ID is opaque, project-scoped and case-sensitive: preserve it exactly, including whitespace and Unicode. It is never a credential and does not link accounts across projects. Internal user IDs supplied by a client cannot select an acting participant.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nCreator changes are allowed only before the request has ever been accepted. Acceptance remains permanent even if moderation changes later. Editing a rejected request resubmits it for moderation." }, "delete": { "tags": [ "Requests" ], "summary": "Delete your request before acceptance", "operationId": "delete_api_v1_requests__request_id__delete", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "name": "version", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "title": "Version" } }, { "name": "external_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ], "description": "Opaque project-scoped participant ID. Requires a participate credential; never a login credential.", "title": "External User Id" }, "description": "Exact opaque ID verified by your backend, with a participate project credential. Preserve case, whitespace and Unicode; the ID alone grants no access." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "A local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. A trusted project backend may instead use an fb_ bearer credential with participate permission and the verified external_user_id. The ID is opaque, project-scoped and case-sensitive: preserve it exactly, including whitespace and Unicode. It is never a credential and does not link accounts across projects. Internal user IDs supplied by a client cannot select an acting participant.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nCreator changes are allowed only before the request has ever been accepted. Acceptance remains permanent even if moderation changes later. Editing a rejected request resubmits it for moderation." } }, "/api/v1/requests/{request_id}/content": { "patch": { "tags": [ "Moderation" ], "summary": "Edit request content as a manager", "operationId": "admin_edit_api_v1_requests__request_id__content_patch", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminEdit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/requests/{request_id}/accept": { "post": { "tags": [ "Moderation" ], "summary": "Accept a request", "operationId": "accept_api_v1_requests__request_id__accept_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/requests/{request_id}/reject": { "post": { "tags": [ "Moderation" ], "summary": "Reject a request", "operationId": "reject_api_v1_requests__request_id__reject_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rejection" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/requests/{request_id}/status": { "put": { "tags": [ "Moderation" ], "summary": "Set a request's lifecycle status", "operationId": "status_api_v1_requests__request_id__status_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lifecycle" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/requests/{request_id}/vote": { "put": { "tags": [ "Voting" ], "summary": "Set or remove your vote", "description": "A local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. A trusted project backend may instead use an fb_ bearer credential with participate permission and the verified external_user_id. The ID is opaque, project-scoped and case-sensitive: preserve it exactly, including whitespace and Unicode. It is never a credential and does not link accounts across projects. Internal user IDs supplied by a client cannot select an acting participant.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nOnly accepted requests can be voted on. PUT sets present=true or present=false; it is not a toggle. Repeating the same value does not add votes or duplicate effects.", "operationId": "vote_api_v1_requests__request_id__vote_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vote" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "tags": [ "Voting" ], "summary": "Read your current vote", "operationId": "vote_state_api_v1_requests__request_id__vote_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "name": "external_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ], "description": "Opaque project-scoped participant ID. Requires a participate credential; never a login credential.", "title": "External User Id" }, "description": "Exact opaque ID verified by your backend, with a participate project credential. Preserve case, whitespace and Unicode; the ID alone grants no access." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "A local participant or administrator feedback_session cookie, or an administrator ns_ bearer session. A trusted project backend may instead use an fb_ bearer credential with participate permission and the verified external_user_id. The ID is opaque, project-scoped and case-sensitive: preserve it exactly, including whitespace and Unicode. It is never a credential and does not link accounts across projects. Internal user IDs supplied by a client cannot select an acting participant." } }, "/api/v1/requests/{request_id}/history": { "get": { "tags": [ "Requests" ], "summary": "List visible request history", "description": "Public reads expose acceptance and status history only. Owners/managers see private history.\n\nAnonymous public read. A supplied project credential needs read or manage permission for the resource\u2019s project. Unpublished requests are visible only to their creator or a manager; unauthorized detail reads return 404. Archived resources and archive filters other than active require administrator access.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "history_api_v1_requests__request_id__history_get", "security": [ {}, { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "name": "external_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ], "description": "Opaque project-scoped participant ID. Requires a participate credential; never a login credential.", "title": "External User Id" }, "description": "Exact opaque ID verified by your backend, with a participate project credential. Preserve case, whitespace and Unicode; the ID alone grants no access." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_EventOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/requests/{request_id}/audience": { "get": { "tags": [ "Voting" ], "summary": "List the request's creator and current voters", "description": "Native administrator, or an fb_ project credential with audience:read permission for this project. This private list deduplicates the creator and current voters; it is not the audience at the time of an earlier event.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "audience_api_v1_requests__request_id__audience_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_IdentityOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/keys": { "get": { "tags": [ "Credentials" ], "summary": "List project credentials without their secrets", "operationId": "keys_api_v1_projects__project__keys_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_KeyOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." }, "post": { "tags": [ "Credentials" ], "summary": "Create a project credential", "description": "Admin only. Secret is shown once; store on a trusted backend.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "create_key_api_v1_projects__project__keys_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewKeyOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/keys/{key_id}": { "delete": { "tags": [ "Credentials" ], "summary": "Revoke a project credential", "operationId": "revoke_key_api_v1_projects__project__keys__key_id__delete", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/webhook": { "get": { "tags": [ "Webhooks" ], "summary": "Read webhook settings", "operationId": "webhook_api_v1_projects__project__webhook_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project." }, "put": { "tags": [ "Webhooks" ], "summary": "Configure a webhook or rotate its signing secret", "description": "Creates or rotates a secret, returned only on creation/rotation. Existing jobs retain their encrypted signing snapshot.\n\nNative administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nThe events enum is the subscription allowlist. chat.support_mode_changed exists as an internal event but cannot currently be selected through these v1 settings. Existing queued jobs retain their saved destination, payload and signing secret after settings change.", "operationId": "update_webhook_api_v1_projects__project__webhook_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/webhook/test": { "post": { "tags": [ "Webhooks" ], "summary": "Queue a test webhook delivery", "operationId": "test_webhook_api_v1_projects__project__webhook_test_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "operationId": "deliveries_api_v1_projects__project__deliveries_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "failed", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Failed" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageOutput_DeliveryOutput_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." } }, "/api/v1/projects/{project}/deliveries/{delivery_id}": { "get": { "tags": [ "Webhooks" ], "summary": "Inspect a webhook delivery and its saved payload", "operationId": "delivery_api_v1_projects__project__deliveries__delivery_id__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Delivery Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project." } }, "/api/v1/projects/{project}/deliveries/{delivery_id}/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Retry a webhook delivery with its saved payload", "operationId": "retry_delivery_api_v1_projects__project__deliveries__delivery_id__retry_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Delivery Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Native administrator, or an fb_ project credential with manage permission. The resource must belong to that credential\u2019s project.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/chat/projects/{project}/config": { "get": { "tags": [ "Chat" ], "summary": "Read public chat availability and display settings", "description": "Public widget configuration. Requires an exact enabled website Origin. No credentials or identities returned.\n\nPublic website chat requires chat enabled and an exact allowed Origin. Same-origin configuration reads may use Sec-Fetch-Site: same-origin. Session creation accepts no account or project credentials; its cv_ visitor token is secret and scoped to one conversation and website origin.", "operationId": "public_config_api_v1_chat_projects__project__config_get", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatConfigOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [] } }, "/api/v1/chat/projects/{project}/sessions": { "post": { "tags": [ "Chat" ], "summary": "Start an anonymous website conversation", "description": "Create a new 30-day visitor session and conversation. X-Chat-Token authorizes subsequent operations. Call only on deliberate chat use.\n\nPublic website chat requires chat enabled and an exact allowed Origin. Same-origin configuration reads may use Sec-Fetch-Site: same-origin. Session creation accepts no account or project credentials; its cv_ visitor token is secret and scoped to one conversation and website origin.", "operationId": "create_session_api_v1_chat_projects__project__sessions_post", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitorSessionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [] } }, "/api/v1/chat/projects/{project}/customer-sessions": { "post": { "tags": [ "Chat" ], "summary": "Issue or renew customer chat access", "description": "Use a local account session, or a trusted backend project key with participate permission and a verified external_user_id. Preserve the project-scoped ID exactly; it is never a credential. Project-key requests must omit Origin. Account sessions must omit external_user_id. Chat credentials cannot establish identity. For browser clients, send an allowed origin in the JSON body; local accounts may also use PUBLIC_BASE_URL. Native clients omit that field. Only project keys may supply display_name. The returned cc_ credential lasts one hour. Renew with the same verified identity to retain conversations and read positions. Revoking the issuing key or account session invalidates its derived credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "customer_session_api_v1_chat_projects__project__customer_sessions_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSessionInput" }, "examples": { "externalBrowser": { "summary": "Trusted backend verifies the signed-in website user", "value": { "external_user_id": "app-user-123", "client_type": "browser", "origin": "https://app.example.com", "display_name": "Jordan" } }, "externalNative": { "summary": "Trusted backend gives its native client customer access without a browser Origin", "value": { "external_user_id": "app-user-123", "client_type": "native", "display_name": "Jordan" } }, "nativeAccount": { "summary": "SupaKnock participant exchanges its cookie session and CSRF token", "value": { "client_type": "browser", "origin": "https://box.example.com" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSessionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/projects/{project}/customer-sessions/revoke": { "post": { "tags": [ "Chat" ], "summary": "Revoke all chat credentials for a customer", "description": "Use a local account session, or a trusted backend project key with participate permission and a verified external_user_id. Preserve the project-scoped ID exactly; it is never a credential. Project-key requests must omit Origin. Account sessions must omit external_user_id. Chat credentials cannot establish identity. Revokes every chat credential for this customer in this project; durable conversations and read positions remain.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "revoke_customer_sessions_api_v1_chat_projects__project__customer_sessions_revoke_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] }, { "ProjectBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRevokeInput" } } } }, "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations": { "get": { "tags": [ "Chat" ], "summary": "List your conversations", "description": "List only the acting customer\u2019s conversations in their credential\u2019s project, including empty conversations. Newest activity first, then stable ID; results can move when messages arrive.\n\nAn owning cc_ customer credential is required. Listing also accepts a cv_ visitor credential for its single conversation. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "customer_conversations_api_v1_chat_conversations_get", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "open", "closed" ], "type": "string" }, { "type": "null" } ], "title": "State" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "Chat" ], "summary": "Start a customer conversation", "description": "An owning cc_ customer credential is required. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nGenerate client_conversation_id once and reuse it if the response is lost. The customer owns the returned conversation across renewed credentials.", "operationId": "create_conversation_api_v1_chat_conversations_post", "security": [ { "ChatCustomer": [] } ], "parameters": [ { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/session": { "delete": { "tags": [ "Chat" ], "summary": "Revoke the current customer chat credential", "description": "An owning cc_ customer credential is required. Revokes this credential and its tickets/sockets. Other device credentials and durable history remain intact. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.", "operationId": "revoke_customer_session_api_v1_chat_session_delete", "security": [ { "ChatCustomer": [] } ], "parameters": [ { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations/{conversation_id}": { "get": { "tags": [ "Chat" ], "summary": "Read a conversation you can access", "operationId": "conversation_api_v1_chat_conversations__conversation_id__get", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Owning cc_ customer, cv_ visitor, or native administrator. Direct project credentials and participant account cookies must first exchange for customer chat access. Each operation, ticket and reconnect rechecks ownership, project, expiry, revocation and issuing authority. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie." } }, "/api/v1/chat/conversations/{conversation_id}/support-mode": { "put": { "tags": [ "Chat" ], "summary": "Change a conversation's AI or human support mode", "description": "Explicit versioned AI or human-support choice. Customers can request AI or wait for a human; only native administrators can take over. Changing mode fences unfinished AI replies.\n\nOwning cc_ customer, cv_ visitor, or native administrator. Direct project credentials and participant account cookies must first exchange for customer chat access. Each operation, ticket and reconnect rechecks ownership, project, expiry, revocation and issuing authority. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nUse the current mode_version, which is separate from conversation version. Customers can choose ai or waiting_human; only administrators can select human. Current AI readiness is rechecked before AI resumes.", "operationId": "support_mode_api_v1_chat_conversations__conversation_id__support_mode_put", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportModeInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations/{conversation_id}/messages": { "get": { "tags": [ "Chat" ], "summary": "Read messages after a conversation sequence", "operationId": "messages_api_v1_chat_conversations__conversation_id__messages_get", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2147483647, "minimum": 0, "default": 0, "title": "After" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Owning cc_ customer, cv_ visitor, or native administrator. Direct project credentials and participant account cookies must first exchange for customer chat access. Each operation, ticket and reconnect rechecks ownership, project, expiry, revocation and issuing authority. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nReturns messages in increasing sequence after the supplied value. Continue with next_sequence while has_more is true. Sequence numbers belong to one conversation; deduplicate by message ID when reconnecting." }, "post": { "tags": [ "Chat" ], "summary": "Send a message with an idempotent client ID", "description": "Returns after the message, immutable event and applicable webhook/push jobs commit together. Notification payloads exclude the message body.\n\nOwning cc_ customer, cv_ visitor, or native administrator. Direct project credentials and participant account cookies must first exchange for customer chat access. Each operation, ticket and reconnect rechecks ownership, project, expiry, revocation and issuing authority. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nGenerate client_message_id once for each new message and reuse it on retries. An identical retry returns the committed message; reusing the ID with changed content returns 409. Customer idempotence survives chat-token renewal. Optional follow_up_email is private, unverified and saved separately; it is excluded from AI context, events and notifications.", "operationId": "send_api_v1_chat_conversations__conversation_id__messages_post", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations/{conversation_id}/read": { "post": { "tags": [ "Chat" ], "summary": "Advance your conversation read position", "operationId": "read_api_v1_chat_conversations__conversation_id__read_post", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Owning cc_ customer, cv_ visitor, or native administrator. Direct project credentials and participant account cookies must first exchange for customer chat access. Each operation, ticket and reconnect rechecks ownership, project, expiry, revocation and issuing authority. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nRead positions only advance and are bounded to committed messages. Each administrator has a separate conversation read position; customer positions survive credential renewal. This does not change the shared notification inbox." } }, "/api/v1/chat/conversations/{conversation_id}/session": { "delete": { "tags": [ "Chat" ], "summary": "Revoke an anonymous visitor's chat credential", "operationId": "revoke_api_v1_chat_conversations__conversation_id__session_delete", "security": [ { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Owning cv_ visitor credential or native administrator. Authenticated customers revoke their current credential with DELETE /api/v1/chat/session. History is retained. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/chat/tickets": { "post": { "tags": [ "Chat" ], "summary": "Issue a single-use WebSocket ticket", "description": "Owning cc_ customer, cv_ visitor, or native administrator. Direct project credentials and participant account cookies must first exchange for customer chat access. Each operation, ticket and reconnect rechecks ownership, project, expiry, revocation and issuing authority. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nThe ct_ ticket expires after 60 seconds and can be used once. Connect to /api/v1/chat/ws and send it in the first JSON frame within five seconds. Never put the ticket or a chat token in the URL. The WebSocket contract is documented in x-websockets.", "operationId": "ticket_api_v1_chat_tickets_post", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/admin/chat/business-hours": { "get": { "tags": [ "Chat administration" ], "summary": "Read shared business hours", "operationId": "account_hours_api_v1_admin_chat_business_hours_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoursSettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nBusiness hours describe expected availability, not live presence or a promised reply time. They never prevent sending a message. Project overrides take precedence over the shared schedule." }, "put": { "tags": [ "Chat administration" ], "summary": "Save shared business hours", "operationId": "save_account_hours_api_v1_admin_chat_business_hours_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoursEdit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoursSettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nBusiness hours describe expected availability, not live presence or a promised reply time. They never prevent sending a message. Project overrides take precedence over the shared schedule." } }, "/api/v1/admin/chat/projects/{project}/business-hours": { "get": { "tags": [ "Chat administration" ], "summary": "Read a project's business hours override", "operationId": "project_hours_api_v1_admin_chat_projects__project__business_hours_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoursSettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nBusiness hours describe expected availability, not live presence or a promised reply time. They never prevent sending a message. Project overrides take precedence over the shared schedule." }, "put": { "tags": [ "Chat administration" ], "summary": "Save or clear a project's business hours override", "operationId": "save_project_hours_api_v1_admin_chat_projects__project__business_hours_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoursEdit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoursSettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nBusiness hours describe expected availability, not live presence or a promised reply time. They never prevent sending a message. Project overrides take precedence over the shared schedule." } }, "/api/v1/chat/conversations/{conversation_id}/contact/remove": { "post": { "tags": [ "Chat" ], "summary": "Remove a conversation's private follow-up email", "description": "Owner or native administrator removes the separate follow-up email using its current version. Does not remove messages or historical backups.\n\nOwning cc_ customer, cv_ visitor, or native administrator. Direct project credentials and participant account cookies must first exchange for customer chat access. Each operation, ticket and reconnect rechecks ownership, project, expiry, revocation and issuing authority. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nSupply the conversation contact_version as version. Removes the current optional contact, without changing messages or deleting historical backups.", "operationId": "clear_contact_api_v1_chat_conversations__conversation_id__contact_remove_post", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] }, { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactClearInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/admin/chat/projects/{project}": { "get": { "tags": [ "Chat administration" ], "summary": "Read a project's chat settings", "operationId": "settings_api_v1_admin_chat_projects__project__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials." }, "put": { "tags": [ "Chat administration" ], "summary": "Enable chat and configure allowed website origins", "operationId": "configure_api_v1_admin_chat_projects__project__put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSettingsInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/admin/chat/conversations": { "get": { "tags": [ "Chat administration" ], "summary": "List the administrator chat inbox", "operationId": "inbox_api_v1_admin_chat_conversations_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "open", "closed" ], "type": "string" }, { "type": "null" } ], "title": "State" } }, { "name": "project", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." } }, "/api/v1/admin/chat/conversations/{conversation_id}": { "get": { "tags": [ "Chat administration" ], "summary": "Read a conversation as an administrator", "operationId": "admin_conversation_api_v1_admin_chat_conversations__conversation_id__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials." }, "patch": { "tags": [ "Chat administration" ], "summary": "Open or close a conversation", "operationId": "state_api_v1_admin_chat_conversations__conversation_id__patch", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/chat/conversations/{conversation_id}/proposals": { "get": { "tags": [ "Chat reports" ], "summary": "List your feedback drafts from this conversation", "description": "Review private drafts owned by this chat customer. Reading never submits a request.\n\nOwning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "proposals_api_v1_chat_conversations__conversation_id__proposals_get", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations/{conversation_id}/proposals/{proposal_id}": { "get": { "tags": [ "Chat reports" ], "summary": "Read a feedback draft before submission", "operationId": "proposal_api_v1_chat_conversations__conversation_id__proposals__proposal_id__get", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Proposal Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Owning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie." }, "put": { "tags": [ "Chat reports" ], "summary": "Edit a feedback draft", "description": "Edit the exact private draft. Changes advance its version and invalidate the previous confirmation hash.\n\nOwning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.", "operationId": "edit_proposal_api_v1_chat_conversations__conversation_id__proposals__proposal_id__put", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Proposal Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 400 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations/{conversation_id}/proposals/{proposal_id}/cancel": { "post": { "tags": [ "Chat reports" ], "summary": "Cancel a feedback draft", "operationId": "cancel_proposal_api_v1_chat_conversations__conversation_id__proposals__proposal_id__cancel_post", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Proposal Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Owning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie." } }, "/api/v1/chat/conversations/{conversation_id}/proposals/{proposal_id}/confirm": { "post": { "tags": [ "Chat reports" ], "summary": "Confirm the exact feedback draft for submission", "description": "Explicitly confirm the displayed draft version and hash. The customer must see its destination, visibility and tracking notice first. This creates one pending request atomically; repeating the same client request ID returns its receipt. Guest creation requires a separately enabled policy and the original website chat credential.\n\nOwning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.", "operationId": "confirm_api_v1_chat_conversations__conversation_id__proposals__proposal_id__confirm_post", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Proposal Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations/{conversation_id}/reports": { "get": { "tags": [ "Chat reports" ], "summary": "List feedback submitted from your conversation", "description": "Private receipts remain available to the owning current chat credential after new report creation is disabled.\n\nOwning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "reports_api_v1_chat_conversations__conversation_id__reports_get", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/chat/conversations/{conversation_id}/reports/{report_id}": { "get": { "tags": [ "Chat reports" ], "summary": "Read a submitted feedback receipt", "operationId": "report_api_v1_chat_conversations__conversation_id__reports__report_id__get", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Report Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Owning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie." }, "put": { "tags": [ "Chat reports" ], "summary": "Edit submitted feedback before acceptance", "description": "Edit an owned report before its first acceptance. Prior acceptance permanently locks creator edits even if moderation later changes.\n\nOwning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.", "operationId": "edit_report_api_v1_chat_conversations__conversation_id__reports__report_id__put", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Report Id" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 400 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Chat reports" ], "summary": "Delete submitted feedback before acceptance", "description": "Delete an owned report only before its first acceptance, retaining its private durable receipt.\n\nOwning cc_ customer or cv_ visitor credential only; administrators cannot confirm feedback on this customer surface. New drafts and confirmation recheck AI, the specific tool and support mode. Guest submission also requires explicit guest-report permission. Existing report ownership remains usable after creation settings change while the owning credential is valid. Acceptance permanently locks creator edits and deletion. Browser chat credentials require their exact bound Origin; same-origin HTTP requests may use Sec-Fetch-Site: same-origin to select the installation origin. Native customer credentials omit Origin. Never combine X-Chat-Token with Authorization or a feedback_session cookie.", "operationId": "delete_report_api_v1_chat_conversations__conversation_id__reports__report_id__delete", "security": [ { "ChatCustomer": [] }, { "ChatVisitor": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Report Id" } }, { "name": "version", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "title": "Version" } }, { "name": "X-Chat-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "X-Chat-Token" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required for visitor-session creation and cross-origin browser chat; must match the configured and credential-bound website origin. Same-origin chat HTTP reads/writes may infer PUBLIC_BASE_URL from Sec-Fetch-Site: same-origin. Native customer tokens and project-key customer exchanges must omit Origin. Administrator/account cookies require an explicit PUBLIC_BASE_URL Origin on mutations." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 32 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/admin/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List the shared administrator notification inbox", "description": "List the shared administrator inbox newest first, with a consistent unread count and sequence watermark.\n\nEvery administrator sees the same read state across all projects. Opening\nthis list does not mark anything read. Request titles are immutable event\nsnapshots; customer message bodies and identities are never included.\nDeleted resources keep their notifications with resource_available=false.\nPagination is by offset; newly arriving notifications can move items.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "notifications_api_v1_admin_notifications_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Unread Only" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/admin/notifications/summary": { "get": { "tags": [ "Notifications" ], "summary": "Read the shared unread count and sequence watermark", "description": "Read the installation-wide unread count and latest committed notification sequence.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.", "operationId": "summary_api_v1_admin_notifications_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSummaryOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ] } }, "/api/v1/admin/notifications/{notification_id}/read": { "put": { "tags": [ "Notifications" ], "summary": "Mark a notification read or unread for all administrators", "description": "Set read or unread for every administrator. Repeating the same write is idempotent.\n\nExplicit concurrent read/unread changes use the last committed write.\nConversation read positions and push preferences are independent.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "set_read_api_v1_admin_notifications__notification_id__read_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "notification_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Notification Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationReadInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/admin/notifications/read-all": { "post": { "tags": [ "Notifications" ], "summary": "Mark notifications read through a displayed watermark", "description": "Mark all notifications at or below the displayed sequence watermark read for every administrator.\n\nThis operation is idempotent. Notifications committed above that watermark\nremain unread, including arrivals after the displayed page was fetched.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials cannot create projects, administer accounts, archive resources or manage credentials.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "read_all_api_v1_admin_notifications_read_all_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationReadAllInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSummaryOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ] } }, "/api/v1/ai/decision-providers": { "get": { "tags": [ "AI administration" ], "summary": "List supported topic-decision providers", "operationId": "providers_api_v1_ai_decision_providers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DecisionProviderOutput" }, "type": "array", "title": "Response Providers Api V1 Ai Decision Providers Get" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." } }, "/api/v1/projects/{project}/ai/topics": { "get": { "tags": [ "AI administration" ], "summary": "Read topic-decision settings", "operationId": "settings_api_v1_projects__project__ai_topics_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." }, "put": { "tags": [ "AI administration" ], "summary": "Save topic-decision settings", "description": "Independent default-off policy. Requires exact decision capability to enable. Scope changes fence late work; personality grants no authority.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "save_api_v1_projects__project__ai_topics_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicWrite" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/topics/decisions": { "get": { "tags": [ "AI administration" ], "summary": "List topic-decision results", "description": "Native-admin-only decision metadata. Excludes messages, context, scope, credentials and key labels.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "decisions_api_v1_projects__project__ai_topics_decisions_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionHistoryOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/topics/keys": { "post": { "tags": [ "AI administration" ], "summary": "Add an AI key for topic decisions", "operationId": "add_api_v1_projects__project__ai_topics_keys_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionKeyCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/ai/topics/keys/{key_id}/remove": { "post": { "tags": [ "AI administration" ], "summary": "Remove a project's topic-decision key binding", "operationId": "remove_api_v1_projects__project__ai_topics_keys__key_id__remove_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/ai/topics/keys/{key_id}/models/refresh": { "post": { "tags": [ "AI administration" ], "summary": "Refresh a topic-decision key's available models", "operationId": "refresh_api_v1_projects__project__ai_topics_keys__key_id__models_refresh_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/ai/topics/keys/{key_id}/probe": { "post": { "tags": [ "AI administration" ], "summary": "Probe a key and model for topic decisions", "description": "Explicit synthetic typed capability probe. Budgeted before dispatch. Unverified gateway transport fails before billing; catalogue membership is insufficient.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "probe_api_v1_projects__project__ai_topics_keys__key_id__probe_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionTestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/topics/keys/{key_id}/test": { "post": { "tags": [ "AI administration" ], "summary": "Test a topic decision with supplied context", "description": "Decision-only test of saved scope and synthetic context. No retrieval, generation or tools; never enables the gate.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "test_api_v1_projects__project__ai_topics_keys__key_id__test_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionTest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionTestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/ai/keys": { "get": { "tags": [ "AI administration" ], "summary": "List the installation's AI credential library", "description": "Installation-wide native-admin credential library. Safe metadata and affected projects only; secrets never returned.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.", "operationId": "read_api_v1_ai_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeysOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ] }, "post": { "tags": [ "AI administration" ], "summary": "Add an AI credential to the installation library", "description": "Add an encrypted account credential with explicit provider roles. No project binding or opt-in is created.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "add_api_v1_ai_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeysOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ] } }, "/api/v1/ai/keys/{key_id}": { "put": { "tags": [ "AI administration" ], "summary": "Edit an installation AI credential and its allowed roles", "description": "Edit, pause/resume or replace a shared key. Fences every bound project. Replacement clears all model/role evidence.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "update_api_v1_ai_keys__key_id__put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeysOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "AI administration" ], "summary": "Delete an AI credential and detach every project binding", "operationId": "delete_api_v1_ai_keys__key_id__delete", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeysOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/ai/keys/{key_id}/retry": { "post": { "tags": [ "AI administration" ], "summary": "Retry an installation AI credential", "description": "Explicitly reset the shared account cooldown. Capability and permanent blocks remain; recovery stays fenced.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "retry_api_v1_ai_keys__key_id__retry_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeysOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/ai/keys/{key_id}/models/refresh": { "post": { "tags": [ "AI administration" ], "summary": "Refresh an installation AI credential's model catalogue", "description": "Explicitly refresh this credential\u2019s role-specific models. Does not verify capabilities or enable any project.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "refresh_api_v1_ai_keys__key_id__models_refresh_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyModels" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeysOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/keys/selection": { "put": { "tags": [ "AI administration" ], "summary": "Select account keys for a project's AI replies", "description": "Explicit generation key bindings. Detachment never destroys account credentials. Exact-model verification still required.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "generation_api_v1_projects__project__ai_keys_selection_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectKeySelection" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/topics/keys/selection": { "put": { "tags": [ "AI administration" ], "summary": "Select account keys for a project's topic decisions", "description": "Explicit decision key bindings. Unavailable credentials never switch an enabled topic gate off.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "decisions_api_v1_projects__project__ai_topics_keys_selection_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectKeySelection" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/ai/providers": { "get": { "tags": [ "AI administration" ], "summary": "List supported AI reply providers", "operationId": "providers_api_v1_ai_providers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AIProviderOutput" }, "type": "array", "title": "Response Providers Api V1 Ai Providers Get" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." } }, "/api/v1/projects/{project}/ai": { "get": { "tags": [ "AI administration" ], "summary": "Read a project's AI support settings", "operationId": "settings_api_v1_projects__project__ai_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AISettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." }, "put": { "tags": [ "AI administration" ], "summary": "Save a project's AI support settings", "description": "Save the complete versioned configuration. Changing provider clears the model, catalogue and capability evidence, and clears the old key unless a replacement is explicitly supplied. Disable AI before changing provider, then refresh its models and verify the new exact selection. Every permission is explicit; saving does not contact the provider or enable permissions implicitly.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nA provider change detaches the old project selections; it does not delete credentials from the installation library. Add or select keys for the new provider explicitly.", "operationId": "save_api_v1_projects__project__ai_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AISettingsWrite" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AISettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 400 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/usage": { "get": { "tags": [ "AI administration" ], "summary": "Read a project's AI usage and quota status", "description": "Read today\u2019s UTC usage without generation. Reserved tokens are conservative allowances, not billed cost. Reported counts include only completed usage reports; uncertain calls remain reserved.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.", "operationId": "usage_api_v1_projects__project__ai_usage_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIUsageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/models/refresh": { "post": { "tags": [ "AI administration" ], "summary": "Refresh available models for the configured provider", "description": "Explicitly contact the saved provider to refresh exact model IDs. Catalogue membership does not verify access or capabilities.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "refresh_api_v1_projects__project__ai_models_refresh_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIProviderAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AISettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/model/probe": { "post": { "tags": [ "AI administration" ], "summary": "Probe the configured AI reply model", "description": "Explicitly run one short synthetic text request, or three requests when tools=true, using the saved key and selected model. May incur provider usage. Sends no customer content and executes no application tools.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "probe_api_v1_projects__project__ai_model_probe_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIProbeInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AISettingsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/keys": { "get": { "tags": [ "AI administration" ], "summary": "List AI reply keys available to a project", "description": "Read up to 99 named provider keys and safe health metadata. No secret, prefix or suffix is returned; no network I/O occurs.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.", "operationId": "keys_api_v1_projects__project__ai_keys_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "tags": [ "AI administration" ], "summary": "Add an AI reply key and bind it to this project", "description": "Add an encrypted key for the selected provider. Exact-model capability probes remain explicit; a new key never resets its account cooldown.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "add_key_api_v1_projects__project__ai_keys_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/keys/{key_id}": { "put": { "tags": [ "AI administration" ], "summary": "Edit an AI reply key through a project binding", "description": "Edit metadata, pause/resume or replace a key. Rechecks settings/key versions and fences existing AI work. Replacement requires new model verification.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "update_key_api_v1_projects__project__ai_keys__key_id__put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "AI administration" ], "summary": "Delete a shared AI reply credential through a project binding", "operationId": "delete_key_api_v1_projects__project__ai_keys__key_id__delete", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nDeletes the shared credential and its secret, affecting every bound project. To detach it only from this project, use PUT /api/v1/projects/{project}/ai/keys/selection with the remaining key IDs instead." } }, "/api/v1/projects/{project}/ai/keys/{key_id}/retry": { "post": { "tags": [ "AI administration" ], "summary": "Retry a project's AI reply key", "description": "Clear this provider-account cooldown across its shared keys. No network call or capability grant occurs; invalid/payment-blocked keys still need repair and a successful explicit probe.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "retry_key_api_v1_projects__project__ai_keys__key_id__retry_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/keys/{key_id}/models/refresh": { "post": { "tags": [ "AI administration" ], "summary": "Refresh models for one AI reply key", "operationId": "key_models_api_v1_projects__project__ai_keys__key_id__models_refresh_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyAction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/ai/keys/{key_id}/model/probe": { "post": { "tags": [ "AI administration" ], "summary": "Probe one AI reply key and model", "description": "Explicitly probe this key on the saved exact model: one text call or three text/tool/continuation calls. No support tool executes. May consume provider quota; all current credential/configuration and health fences are rechecked.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "key_probe_api_v1_projects__project__ai_keys__key_id__model_probe_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyProbe" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIKeyPoolOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/feedback-destinations": { "get": { "tags": [ "AI administration" ], "summary": "List boards available to AI feedback tools", "operationId": "destinations_api_v1_projects__project__ai_feedback_destinations_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIFeedbackDestinationsOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." } }, "/api/v1/ai/runtime": { "get": { "tags": [ "AI administration" ], "summary": "Read local embedding model installation status", "operationId": "status_api_v1_ai_runtime_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." } }, "/api/v1/ai/runtime/download": { "post": { "tags": [ "AI administration" ], "summary": "Start downloading the pinned embedding model", "description": "Explicitly download the pinned EmbeddingGemma model. Accept its license in your own Hugging Face account first. The access token is encrypted for the duration of this operation and never returned.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "download_api_v1_ai_runtime_download_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeDownload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ] } }, "/api/v1/ai/runtime/cancel": { "post": { "tags": [ "AI administration" ], "summary": "Cancel the embedding model download", "operationId": "cancel_api_v1_ai_runtime_cancel_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeAction" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/ai/runtime/remove": { "post": { "tags": [ "AI administration" ], "summary": "Remove downloaded embedding model files", "description": "Disable AI and remove local model files. Knowledge documents remain stored. Removal cannot be cancelled after it starts.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "remove_api_v1_ai_runtime_remove_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeAction" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ] } }, "/api/v1/projects/{project}/ai/knowledge/library": { "get": { "tags": [ "AI knowledge" ], "summary": "List original and generated knowledge", "description": "Search original articles and website pages. Only native administrators may read this private library.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "library_api_v1_projects__project__ai_knowledge_library_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "default": "", "title": "Query" } }, { "name": "source_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Source Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/library/{item_id}": { "get": { "tags": [ "AI knowledge" ], "summary": "Read one knowledge library item", "operationId": "library_item_api_v1_projects__project__ai_knowledge_library__item_id__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Item Id" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryContentOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." } }, "/api/v1/projects/{project}/ai/knowledge/sources": { "get": { "tags": [ "AI knowledge" ], "summary": "List knowledge sources", "description": "Inspect project knowledge, explicit approval and actual indexing state. No source text or secrets are listed.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "sources_api_v1_projects__project__ai_knowledge_sources_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSourcePageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}": { "get": { "tags": [ "AI knowledge" ], "summary": "Read a knowledge source", "operationId": "source_api_v1_projects__project__ai_knowledge_sources__source_id__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSourceOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." }, "patch": { "tags": [ "AI knowledge" ], "summary": "Change a knowledge source's retrieval approval", "description": "Set explicit active and approval flags. Only active, approved and fully indexed content is eligible for customer answers. A changed flag invalidates prior worker authority.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "change_source_api_v1_projects__project__ai_knowledge_sources__source_id__patch", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceStateInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSourceOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "AI knowledge" ], "summary": "Delete a knowledge source", "description": "Remove this source from answers immediately and cancel its unfinished work. Preserve private original history; stale workers cannot resurrect it.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "delete_source_api_v1_projects__project__ai_knowledge_sources__source_id__delete", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "name": "version", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "title": "Version" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSourceOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/markdown": { "post": { "tags": [ "AI knowledge" ], "summary": "Import Markdown as a knowledge source", "description": "Save one Markdown original and its indexing job atomically. New sources are unapproved. Importing never downloads a model or claims that indexing has completed; a client import ID makes retries idempotent.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "import_markdown_api_v1_projects__project__ai_knowledge_markdown_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownImportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 400 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/markdown": { "put": { "tags": [ "AI knowledge" ], "summary": "Replace a Markdown knowledge source", "description": "Versioned replacement preserves original history and the last completed index. Older unfinished imports are cancelled, and a retry cannot revive them.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "replace_markdown_api_v1_projects__project__ai_knowledge_sources__source_id__markdown_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownReplacementInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownImportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 400 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/documents": { "get": { "tags": [ "AI knowledge" ], "summary": "List a source's original documents", "description": "Read original revision metadata without document bodies, newest first.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "documents_api_v1_projects__project__ai_knowledge_sources__source_id__documents_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/documents/{document_id}": { "get": { "tags": [ "AI knowledge" ], "summary": "Read an original knowledge document", "description": "Read the exact private original as a JSON string. The content is untrusted Markdown and is never executed or rendered as HTML by this API.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.", "operationId": "document_api_v1_projects__project__ai_knowledge_sources__source_id__documents__document_id__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Document Id" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/websites": { "post": { "tags": [ "AI knowledge" ], "summary": "Start importing a website as a knowledge source", "description": "Queue an explicit public website crawl. New sources are unapproved. The import ID makes retries idempotent; reading settings never starts a crawl.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "import_website_api_v1_projects__project__ai_knowledge_websites_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteInput" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteImportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/website": { "put": { "tags": [ "AI knowledge" ], "summary": "Refresh a website knowledge source", "description": "Refresh a versioned website source. The configured page cap is successful bounded completion, reported as stop_reason=page_limit. Unusable individual URLs are skipped; usable pages are published. Imports with no usable pages, fatal resource failures or cancellation retain the previous original and index.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "refresh_website_api_v1_projects__project__ai_knowledge_sources__source_id__website_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteReplacementInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteImportOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/crawls": { "get": { "tags": [ "AI knowledge" ], "summary": "List website import runs", "description": "Inspect bounded crawl history without source bodies.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor.", "operationId": "runs_api_v1_projects__project__ai_knowledge_sources__source_id__crawls_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRunPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/crawls/{run_id}": { "get": { "tags": [ "AI knowledge" ], "summary": "Read a website import run", "description": "Inspect the current attempt's page outcomes and extracted private originals. Source content is untrusted text, never executable HTML or instructions.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.", "operationId": "run_api_v1_projects__project__ai_knowledge_sources__source_id__crawls__run_id__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRunDetailOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/crawls/{run_id}/cancel": { "post": { "tags": [ "AI knowledge" ], "summary": "Cancel a website import run", "description": "Cancel unfinished crawl work with a version fence; a stale worker cannot publish after cancellation.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "cancel_api_v1_projects__project__ai_knowledge_sources__source_id__crawls__run_id__cancel_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlCancelInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRunDetailOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/previews": { "post": { "tags": [ "AI authoring" ], "summary": "Preview an AI reply with the current project settings", "description": "Queue an explicit grounded preview with every assistant tool disabled. It may use provider quota while project AI is off; it never creates a customer message or enables a setting.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "preview_api_v1_projects__project__ai_previews_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewInput" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRunOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sources/{source_id}/sections/generate": { "post": { "tags": [ "AI authoring" ], "summary": "Start generating knowledge sections from a source", "description": "Queue reviewable drafts from all indexed passages in the source, or selected website pages, in recoverable batches. Coverage is explicit. Drafts stay private until separately approved as an independent article; existing sources are never overwritten.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "sections_api_v1_projects__project__ai_knowledge_sources__source_id__sections_generate_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Source Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionsInput" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRunOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/authoring-runs": { "get": { "tags": [ "AI authoring" ], "summary": "List AI authoring runs", "operationId": "runs_api_v1_projects__project__ai_authoring_runs_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "preview", "sections" ], "type": "string" }, { "type": "null" } ], "title": "Kind" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRunPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." } }, "/api/v1/projects/{project}/ai/authoring-runs/{run_id}": { "get": { "tags": [ "AI authoring" ], "summary": "Read an AI authoring run", "description": "Inspect durable progress, result, original citations and staleness without provider credentials or worker leases.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.", "operationId": "run_api_v1_projects__project__ai_authoring_runs__run_id__get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRunOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/authoring-runs/{run_id}/cancel": { "post": { "tags": [ "AI authoring" ], "summary": "Cancel an AI authoring run", "description": "Fence unfinished work immediately. Cancellation does not promise a refund for an already dispatched provider request.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "cancel_api_v1_projects__project__ai_authoring_runs__run_id__cancel_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRunOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/authoring-runs/{run_id}/retry": { "post": { "tags": [ "AI authoring" ], "summary": "Retry an AI authoring run", "description": "Explicitly resume unfinished section batches. Saved drafts and paid receipts remain; changed settings or evidence require a new run.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "retry_api_v1_projects__project__ai_authoring_runs__run_id__retry_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryInput" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRunOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sections": { "get": { "tags": [ "AI authoring" ], "summary": "List generated knowledge sections", "operationId": "drafts_api_v1_projects__project__ai_knowledge_sections_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "default": "", "title": "Query" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" }, "description": "Maximum number of items to return. Use the documented default and bounds below." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of matching items to skip; offset pagination does not freeze the result set." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionPageOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nOffset pagination returns items, limit, offset and has_more. Keep filters unchanged and advance offset by the number of returned items while has_more is true. Concurrent inserts or edits can move rows between pages; this is not a snapshot cursor." } }, "/api/v1/projects/{project}/ai/knowledge/sections/{section_id}/approve": { "post": { "tags": [ "AI authoring" ], "summary": "Approve a generated section for retrieval", "description": "Explicitly adopt the reviewed saved draft as an approved original. Idempotent per draft version; local indexing follows. Existing sources are not overridden.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "publish_api_v1_projects__project__ai_knowledge_sections__section_id__approve_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Section Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSourceOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/knowledge/sections/{section_id}": { "put": { "tags": [ "AI authoring" ], "summary": "Edit a generated knowledge section", "description": "Version an internal draft, retaining source provenance and immutable edit history. Draft edits never modify originals or embeddings.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "edit_api_v1_projects__project__ai_knowledge_sections__section_id__put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Section Id" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "AI authoring" ], "summary": "Delete a generated knowledge section", "description": "Remove an internal draft with a versioned tombstone while preserving its history.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "delete_api_v1_projects__project__ai_knowledge_sections__section_id__delete", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Section Id" } }, { "name": "version", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "title": "Version" } }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/projects/{project}/ai/personality": { "get": { "tags": [ "AI authoring" ], "summary": "Read the project's AI personality instructions", "operationId": "personality_api_v1_projects__project__ai_personality_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalityOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions." }, "put": { "tags": [ "AI authoring" ], "summary": "Save the project's AI personality instructions", "description": "Save soul.md as versioned project text. Changing personality fences old generation; saving performs no provider request or tool action.\n\nAdministrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project and chat credentials and participant accounts cannot administer AI. Reading settings does not download models or generate content. Provider requests, model downloads and generation require explicit administrator actions.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.", "operationId": "save_personality_api_v1_projects__project__ai_personality_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalityInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalityOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 400 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The AI provider returned an invalid model catalogue or decision response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/admin/connected-apps": { "get": { "tags": [ "Connected apps" ], "summary": "List connected-app configuration for active projects", "operationId": "connections_api_v1_admin_connected_apps_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedConnectionListOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients." } }, "/api/v1/admin/connected-apps/preferences": { "get": { "tags": [ "Connected apps" ], "summary": "Read the connected-app display timezone", "operationId": "preferences_api_v1_admin_connected_apps_preferences_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedPreferencesOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients." }, "put": { "tags": [ "Connected apps" ], "summary": "Save the connected-app display timezone", "operationId": "preferences_save_api_v1_admin_connected_apps_preferences_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preferences" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedPreferencesOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Storage or a required service is temporarily unavailable; retry idempotent operations after recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/app-data/connection": { "get": { "tags": [ "Connected apps" ], "summary": "Read a project's connected-app configuration", "operationId": "connection_api_v1_projects__project__app_data_connection_get", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Optional on this administrator read. If present, it must equal the installation PUBLIC_BASE_URL." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedConnectionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients." }, "put": { "tags": [ "Connected apps" ], "summary": "Save a connected-app URL and encrypted credential", "operationId": "save_api_v1_projects__project__app_data_connection_put", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Save" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedConnectionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nUse version=0 for an unconfigured connection. Saving disables the connection until it is tested and enabled again. Changing the URL requires a new app-issued token. Saved tokens are encrypted and never returned." } }, "/api/v1/projects/{project}/app-data/connection/test": { "post": { "tags": [ "Connected apps" ], "summary": "Test a connection and return its review receipt", "operationId": "test_api_v1_projects__project__app_data_connection_test_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedTestOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nFetches the remote manifest without enabling the connection. The signed review receipt expires after five minutes and is bound to the administrator session, project and connection version." } }, "/api/v1/projects/{project}/app-data/connection/enable": { "post": { "tags": [ "Connected apps" ], "summary": "Enable a tested connection after review", "operationId": "enable_api_v1_projects__project__app_data_connection_enable_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enable" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedConnectionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nSend a fresh test receipt, the same connection version, and only reviewed link_origins from its manifest. support_linked explicitly permits exact-ID lookups of existing local support records. One remote app identity can bind to only one project." } }, "/api/v1/projects/{project}/app-data/connection/disable": { "post": { "tags": [ "Connected apps" ], "summary": "Disable a connected app", "operationId": "disable_api_v1_projects__project__app_data_connection_disable_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedConnectionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/app-data/connection/remove": { "post": { "tags": [ "Connected apps" ], "summary": "Remove connection credentials while retaining app identity", "operationId": "remove_api_v1_projects__project__app_data_connection_remove_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedConnectionOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nRemoves the URL and encrypted token, but preserves the established app identity binding. It does not allow this project to be silently rebound to another app." } }, "/api/v1/projects/{project}/app-data/summary/query": { "post": { "tags": [ "Connected apps" ], "summary": "Read current account counts from a connected app", "operationId": "summary_api_v1_projects__project__app_data_summary_query_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryRead" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadOutput_Summary_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "499": { "description": "The client disconnected before the read completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/app-data/users/query": { "post": { "tags": [ "Connected apps" ], "summary": "Read a page of users from a connected app", "operationId": "users_api_v1_projects__project__app_data_users_query_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRead" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadOutput_UserPage_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "499": { "description": "The client disconnected before the read completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nStart without continuation. For the next page, keep version and query unchanged, leave query.cursor unset, and send the returned outer continuation. Do not forward data.next_cursor yourself. An expired or changed browse session returns 409; restart from the first page. User rows sort by joined_at then exact ID bytes, descending; activity rows sort by occurred_at then exact ID bytes, descending." } }, "/api/v1/projects/{project}/app-data/profile/query": { "post": { "tags": [ "Connected apps" ], "summary": "Read one connected-app user's profile", "operationId": "profile_api_v1_projects__project__app_data_profile_query_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRead" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadOutput_Profile_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "499": { "description": "The client disconnected before the read completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens." } }, "/api/v1/projects/{project}/app-data/activity/query": { "post": { "tags": [ "Connected apps" ], "summary": "Read a page of activity from a connected app", "operationId": "activity_api_v1_projects__project__app_data_activity_query_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityRead" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadOutput_ActivityPage_" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "499": { "description": "The client disconnected before the read completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nStart without continuation. For the next page, keep version and query unchanged, leave query.cursor unset, and send the returned outer continuation. Do not forward data.next_cursor yourself. An expired or changed browse session returns 409; restart from the first page. User rows sort by joined_at then exact ID bytes, descending; activity rows sort by occurred_at then exact ID bytes, descending." } }, "/api/v1/projects/{project}/app-data/related/query": { "post": { "tags": [ "Connected apps" ], "summary": "Find local feedback and chat for an exact connected-app user ID", "operationId": "related_api_v1_projects__project__app_data_related_query_post", "security": [ { "APIKeyCookie": [] }, { "NativeBearer": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string", "title": "Project" }, "description": "Project UUID or its unique identifier, such as my-app." }, { "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" }, "description": "Required only with a feedback_session cookie. Send the csrf_token returned at sign-in (also available in feedback_csrf)." }, { "in": "header", "name": "Origin", "required": false, "schema": { "type": "string" }, "description": "Required with cookie authentication on mutations and must equal PUBLIC_BASE_URL. If sent on any non-chat mutation, it must equal PUBLIC_BASE_URL, even with a bearer credential." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Related" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedRelatedOutput" } } } }, "400": { "description": "Invalid input, malformed JSON or conflicting authentication transports; validation details may appear in error.fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Required credentials are missing, invalid, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient permission, an invalid Origin or a missing/invalid cookie CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The resource is missing or concealed from this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The supplied version is stale or the requested action conflicts with current state; refresh before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "The JSON body exceeds 96 KiB; individual field limits also apply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The request rate or operation quota was exceeded; some rate limits return Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "When present, seconds to wait before another attempt.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "The operation could not be completed; internal details and credentials are not returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The connected app or local read capacity is busy, or storage is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "The connected app failed or returned an invalid protocol response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "504": { "description": "The connected app did not respond before the bounded timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Administrator account required (browser session or native bearer token). Use an administrator feedback_session cookie or ns_ bearer session. Participant accounts cannot use this operation. Project credentials, participant accounts and chat credentials cannot access connection settings or data. Query POSTs are read-only, but cookie clients still require Origin and X-CSRF-Token. Remote data is fetched on demand without a persistent cache. App-issued credentials never reach clients.\n\nCookie-authenticated requests require Origin equal to PUBLIC_BASE_URL and X-CSRF-Token from sign-in. Bearer sessions and project credentials do not use CSRF tokens.\n\nReads local support records only. The connection must be enabled at the supplied version, and support_linked must be enabled for results. user_id must exactly equal the existing project external ID. limit and offset apply independently to the requests and conversations arrays; has_more is true if either has another page. This operation never creates or links an identity." } } }, "components": { "schemas": { "AIFeedbackDestinationsOutput": { "properties": { "feature": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Feature" }, "bug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bug" } }, "type": "object", "required": [ "feature", "bug" ], "title": "AIFeedbackDestinationsOutput" }, "AIKeyAction": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 0.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version" ], "title": "AIKeyAction" }, "AIKeyCreate": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "label": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Label" }, "quota_group": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Quota Group", "description": "Exact provider-account label shared across this installation. Keys in one account share limits.", "default": "Default account" }, "key": { "type": "string", "maxLength": 4096, "minLength": 1, "format": "password", "title": "Key", "writeOnly": true } }, "additionalProperties": false, "type": "object", "required": [ "version", "label", "key" ], "title": "AIKeyCreate" }, "AIKeyOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "label": { "type": "string", "title": "Label" }, "quota_group": { "type": "string", "title": "Quota Group" }, "quota_group_id": { "type": "string", "title": "Quota Group Id" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "enabled": { "type": "boolean", "title": "Enabled" }, "is_default": { "type": "boolean", "title": "Is Default" }, "status": { "type": "string", "title": "Status" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "retry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Retry At" }, "has_key": { "type": "boolean", "title": "Has Key" }, "catalogue_count": { "type": "integer", "title": "Catalogue Count" }, "model_available": { "type": "boolean", "title": "Model Available" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" }, "capabilities_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Capabilities Model" }, "eligible": { "type": "boolean", "title": "Eligible" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "label", "quota_group", "quota_group_id", "version", "enabled", "is_default", "status", "reason", "retry_at", "has_key", "catalogue_count", "model_available", "capabilities", "capabilities_model", "eligible", "created_at", "updated_at" ], "title": "AIKeyOutput" }, "AIKeyPoolOutput": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "provider": { "type": "string", "title": "Provider" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "credential_version": { "type": "integer", "title": "Credential Version" }, "maximum_keys": { "type": "integer", "title": "Maximum Keys" }, "selected_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Selected Model" }, "catalogue": { "items": { "type": "string" }, "type": "array", "title": "Catalogue" }, "verified_key_count": { "type": "integer", "title": "Verified Key Count" }, "available_key_count": { "type": "integer", "title": "Available Key Count" }, "keys": { "items": { "$ref": "#/components/schemas/AIKeyOutput" }, "type": "array", "title": "Keys" }, "groups": { "items": { "$ref": "#/components/schemas/AIQuotaGroupOutput" }, "type": "array", "title": "Groups" } }, "type": "object", "required": [ "project_id", "provider", "version", "credential_version", "maximum_keys", "selected_model", "catalogue", "verified_key_count", "available_key_count", "keys", "groups" ], "title": "AIKeyPoolOutput" }, "AIKeyProbe": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 0.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." }, "tools": { "type": "boolean", "title": "Tools", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version" ], "title": "AIKeyProbe" }, "AIKeyUpdate": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 0.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." }, "label": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Label" }, "quota_group": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Quota Group" }, "enabled": { "type": "boolean", "title": "Enabled" }, "key": { "anyOf": [ { "type": "string", "maxLength": 4096, "minLength": 1, "format": "password", "writeOnly": true }, { "type": "null" } ], "title": "Key", "description": "Omit to preserve this key. A supplied non-null value replaces it and clears its verification." } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version", "label", "quota_group", "enabled" ], "title": "AIKeyUpdate" }, "AIProbeInput": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "tools": { "type": "boolean", "title": "Tools", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "AIProbeInput" }, "AIProviderAction": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "AIProviderAction" }, "AIProviderOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "AIProviderOutput" }, "AIQuotaGroupOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "label": { "type": "string", "title": "Label" }, "status": { "type": "string", "title": "Status" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "retry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Retry At" }, "health_epoch": { "type": "integer", "title": "Health Epoch" } }, "type": "object", "required": [ "id", "label", "status", "reason", "retry_at", "health_epoch" ], "title": "AIQuotaGroupOutput" }, "AIReadinessOutput": { "properties": { "ready": { "type": "boolean", "title": "Ready" }, "issues": { "items": { "type": "string" }, "type": "array", "title": "Issues" } }, "type": "object", "required": [ "ready", "issues" ], "title": "AIReadinessOutput" }, "AISettingsInput": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "allow_guest_reports": { "type": "boolean", "title": "Allow Guest Reports" }, "provider": { "type": "string", "enum": [ "kodekey", "gemini", "mistral", "groq" ], "maxLength": 64, "minLength": 1, "title": "Provider", "description": "An application-reviewed provider adapter. Runtime validation uses the same registry." }, "model": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Model" }, "tools": { "$ref": "#/components/schemas/AIToolsInput" }, "soul": { "type": "string", "maxLength": 20000, "title": "Soul" }, "feature_board_id": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Feature Board Id" }, "bug_board_id": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Bug Board Id" }, "feedback_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Feedback Url" }, "feature_feedback_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Feature Feedback Url" }, "bug_feedback_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Bug Feedback Url" }, "daily_request_limit": { "type": "integer", "maximum": 100000.0, "minimum": 1.0, "title": "Daily Request Limit" }, "daily_token_limit": { "type": "integer", "maximum": 100000000.0, "minimum": 1.0, "title": "Daily Token Limit" }, "max_output_tokens": { "type": "integer", "maximum": 8192.0, "minimum": 1.0, "title": "Max Output Tokens" }, "max_tool_rounds": { "type": "integer", "maximum": 8.0, "minimum": 1.0, "title": "Max Tool Rounds" } }, "additionalProperties": false, "type": "object", "required": [ "enabled", "allow_guest_reports", "provider", "model", "tools", "soul", "feature_board_id", "bug_board_id", "feedback_url", "feature_feedback_url", "bug_feedback_url", "daily_request_limit", "daily_token_limit", "max_output_tokens", "max_tool_rounds" ], "title": "AISettingsInput" }, "AISettingsOutput": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "credential_version": { "type": "integer", "title": "Credential Version" }, "settings": { "$ref": "#/components/schemas/AISettingsInput" }, "has_key": { "type": "boolean", "title": "Has Key" }, "catalogue": { "items": { "type": "string" }, "type": "array", "title": "Catalogue" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "readiness": { "$ref": "#/components/schemas/AIReadinessOutput" } }, "type": "object", "required": [ "project_id", "version", "credential_version", "settings", "has_key", "catalogue", "capabilities", "updated_at", "readiness" ], "title": "AISettingsOutput" }, "AISettingsWrite": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "settings": { "$ref": "#/components/schemas/AISettingsInput" }, "key": { "anyOf": [ { "type": "string", "maxLength": 4096, "minLength": 1, "format": "password", "writeOnly": true }, { "type": "null" } ], "title": "Key", "description": "Omit to preserve the saved key only when the provider is unchanged. Changing provider clears an omitted key and the selected model. Use null to remove the key or supply a replacement explicitly. Never returned." } }, "additionalProperties": false, "type": "object", "required": [ "version", "settings" ], "title": "AISettingsWrite" }, "AIToolsInput": { "properties": { "search_knowledge": { "type": "boolean", "title": "Search Knowledge" }, "support_link": { "type": "boolean", "title": "Support Link" }, "request_human": { "type": "boolean", "title": "Request Human" }, "create_feature_request": { "type": "boolean", "title": "Create Feature Request" }, "create_bug_report": { "type": "boolean", "title": "Create Bug Report" } }, "additionalProperties": false, "type": "object", "required": [ "search_knowledge", "support_link", "request_human", "create_feature_request", "create_bug_report" ], "title": "AIToolsInput" }, "AIUsageOutput": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "day": { "type": "string", "title": "Day" }, "reserved_requests": { "type": "integer", "title": "Reserved Requests" }, "reserved_tokens": { "type": "integer", "title": "Reserved Tokens" }, "reported_input_tokens": { "type": "integer", "title": "Reported Input Tokens" }, "reported_output_tokens": { "type": "integer", "title": "Reported Output Tokens" } }, "type": "object", "required": [ "project_id", "day", "reserved_requests", "reserved_tokens", "reported_input_tokens", "reported_output_tokens" ], "title": "AIUsageOutput" }, "AccountActivityOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "user_id": { "type": "string", "title": "User Id" }, "event_type": { "type": "string", "enum": [ "signup", "login", "account_created", "setup" ], "title": "Event Type" }, "transport": { "anyOf": [ { "type": "string", "enum": [ "cookie", "native" ] }, { "type": "null" } ], "title": "Transport" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip Address" }, "occurred_at": { "type": "string", "title": "Occurred At" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "email": { "type": "string", "title": "Email" }, "role": { "type": "string", "enum": [ "participant", "admin" ], "title": "Role" } }, "type": "object", "required": [ "id", "user_id", "event_type", "transport", "ip_address", "occurred_at", "display_name", "email", "role" ], "title": "AccountActivityOutput" }, "AccountInput": { "properties": { "email": { "type": "string", "maxLength": 254, "minLength": 3, "title": "Email" }, "password": { "type": "string", "maxLength": 128, "minLength": 12, "title": "Password" }, "display_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Display Name" } }, "additionalProperties": false, "type": "object", "required": [ "email", "password" ], "title": "AccountInput" }, "AccountKeyAction": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 1.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version" ], "title": "AccountKeyAction" }, "AccountKeyCreate": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "provider": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Provider" }, "purpose": { "type": "string", "enum": [ "generation", "decision", "both" ], "title": "Purpose" }, "label": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Label" }, "quota_group": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Quota Group", "default": "Default account" }, "key": { "type": "string", "maxLength": 4096, "minLength": 1, "format": "password", "title": "Key", "writeOnly": true }, "account_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Account Id" } }, "additionalProperties": false, "type": "object", "required": [ "version", "provider", "purpose", "label", "key" ], "title": "AccountKeyCreate" }, "AccountKeyModels": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 1.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." }, "role": { "type": "string", "enum": [ "generation", "decision" ], "title": "Role" } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version", "role" ], "title": "AccountKeyModels" }, "AccountKeyOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "provider": { "type": "string", "title": "Provider" }, "label": { "type": "string", "title": "Label" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "purpose": { "type": "string", "enum": [ "generation", "decision", "both" ], "title": "Purpose" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "quota_group": { "type": "string", "title": "Quota Group" }, "enabled": { "type": "boolean", "title": "Enabled" }, "has_key": { "type": "boolean", "title": "Has Key" }, "projects": { "items": { "$ref": "#/components/schemas/BoundProject" }, "type": "array", "title": "Projects" }, "catalogue": { "items": { "type": "string" }, "type": "array", "title": "Catalogue" }, "decision_catalogue": { "items": { "type": "string" }, "type": "array", "title": "Decision Catalogue" }, "verified_models": { "items": { "$ref": "#/components/schemas/VerifiedModel" }, "type": "array", "title": "Verified Models" }, "status": { "type": "string", "title": "Status" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "retry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Retry At" } }, "type": "object", "required": [ "id", "provider", "label", "version", "purpose", "created_at", "updated_at", "quota_group", "enabled", "has_key", "projects", "catalogue", "decision_catalogue", "verified_models", "status", "reason", "retry_at" ], "title": "AccountKeyOutput" }, "AccountKeyUpdate": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 1.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." }, "purpose": { "anyOf": [ { "type": "string", "enum": [ "generation", "decision", "both" ] }, { "type": "null" } ], "title": "Purpose" }, "label": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Label" }, "quota_group": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Quota Group" }, "enabled": { "type": "boolean", "title": "Enabled" }, "key": { "anyOf": [ { "type": "string", "maxLength": 4096, "minLength": 1, "format": "password", "writeOnly": true }, { "type": "null" } ], "title": "Key" }, "account_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Account Id" } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version", "label", "quota_group", "enabled" ], "title": "AccountKeyUpdate" }, "AccountKeysOutput": { "properties": { "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "maximum_keys": { "type": "integer", "title": "Maximum Keys" }, "keys": { "items": { "$ref": "#/components/schemas/AccountKeyOutput" }, "type": "array", "title": "Keys" } }, "type": "object", "required": [ "version", "maximum_keys", "keys" ], "title": "AccountKeysOutput" }, "Activity": { "properties": { "id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Id" }, "occurred_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Occurred At" }, "type": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Type" }, "title": { "type": "string", "maxLength": 200, "title": "Title" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Description" }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "User Id" }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Url" } }, "type": "object", "required": [ "id", "occurred_at", "type", "title" ], "title": "Activity" }, "ActivityPage": { "properties": { "protocol": { "$ref": "#/components/schemas/Protocol" }, "app_instance_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "App Instance Id" }, "observed_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Observed At" }, "items": { "items": { "$ref": "#/components/schemas/Activity" }, "type": "array", "maxItems": 100, "title": "Items" }, "snapshot": { "type": "string", "maxLength": 8192, "minLength": 1, "title": "Snapshot" }, "expires_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Expires At" }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192, "minLength": 1 }, { "type": "null" } ], "title": "Next Cursor" }, "coverage": { "$ref": "#/components/schemas/Coverage" } }, "type": "object", "required": [ "protocol", "app_instance_id", "observed_at", "items", "snapshot", "expires_at", "next_cursor", "coverage" ], "title": "ActivityPage" }, "ActivityQuery": { "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "From" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Until" }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "default": 50 }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "User Id" }, "cursor": { "anyOf": [ { "type": "string", "maxLength": 8192, "minLength": 1 }, { "type": "null" } ], "title": "Cursor", "description": "Leave unset when calling SupaKnock. Send the outer continuation from the previous response instead; raw upstream cursors are rejected." } }, "additionalProperties": false, "type": "object", "required": [ "from", "until" ], "title": "ActivityQuery" }, "ActivityRead": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "query": { "$ref": "#/components/schemas/ActivityQuery" }, "continuation": { "anyOf": [ { "type": "string", "maxLength": 16384, "minLength": 1 }, { "type": "null" } ], "title": "Continuation", "description": "Opaque outer continuation returned by the previous SupaKnock response. Keep the query and connection version unchanged; expired or changed sessions return 409." } }, "additionalProperties": false, "type": "object", "required": [ "version", "query" ], "title": "ActivityRead" }, "AdminEdit": { "properties": { "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title" }, "description": { "type": "string", "maxLength": 20000, "title": "Description", "default": "" }, "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "title", "version" ], "title": "AdminEdit" }, "ArchiveInput": { "properties": { "archived": { "type": "boolean", "title": "Archived" }, "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "archived", "version" ], "title": "ArchiveInput" }, "AuthoringRunOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "project_id": { "type": "string", "title": "Project Id" }, "kind": { "type": "string", "enum": [ "preview", "sections" ], "title": "Kind" }, "config_version": { "type": "integer", "title": "Config Version" }, "knowledge_version": { "type": "integer", "title": "Knowledge Version" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Id" }, "source_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Source Version" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "partial", "failed", "cancelled" ], "title": "Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "created_at": { "type": "string", "title": "Created At" }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finished At" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/PreviewResultOutput" }, { "$ref": "#/components/schemas/SectionsResultOutput" }, { "type": "null" } ], "title": "Result" }, "sections": { "items": { "$ref": "#/components/schemas/SectionOutput" }, "type": "array", "title": "Sections" }, "section_count": { "type": "integer", "title": "Section Count", "default": 0 }, "citations": { "items": { "$ref": "#/components/schemas/CitationOutput" }, "type": "array", "title": "Citations" }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/CoverageOutput" }, { "type": "null" } ] }, "stale": { "type": "boolean", "title": "Stale" } }, "type": "object", "required": [ "id", "project_id", "kind", "config_version", "knowledge_version", "source_id", "source_version", "query", "status", "error", "version", "created_at", "finished_at", "result", "sections", "citations", "coverage", "stale" ], "title": "AuthoringRunOutput" }, "AuthoringRunPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AuthoringRunOutput" }, "type": "array", "title": "Items" }, "has_more": { "type": "boolean", "title": "Has More" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "items", "has_more", "limit", "offset" ], "title": "AuthoringRunPageOutput" }, "BoundProject": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "role": { "type": "string", "enum": [ "generation", "decision" ], "title": "Role" } }, "type": "object", "required": [ "id", "name", "role" ], "title": "BoundProject" }, "ChatConfigOutput": { "properties": { "project": { "type": "string", "title": "Project" }, "name": { "type": "string", "title": "Name" }, "enabled": { "type": "boolean", "title": "Enabled" }, "ai_available": { "type": "boolean", "title": "Ai Available", "default": false }, "response_time": { "$ref": "#/components/schemas/ResponseLabelOutput" }, "business_hours": { "$ref": "#/components/schemas/HoursAvailability" } }, "type": "object", "required": [ "project", "name", "enabled", "response_time", "business_hours" ], "title": "ChatConfigOutput" }, "ChatReportSummary": { "properties": { "request_id": { "type": "string", "title": "Request Id" }, "title": { "type": "string", "title": "Title" }, "kind": { "type": "string", "enum": [ "feature", "bug" ], "title": "Kind" }, "moderation": { "anyOf": [ { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, { "type": "null" } ], "title": "Moderation" }, "status": { "anyOf": [ { "type": "string", "enum": [ "under_consideration", "planned", "in_progress", "shipped" ] }, { "type": "null" } ], "title": "Status" }, "deleted": { "type": "boolean", "title": "Deleted" }, "guest": { "type": "boolean", "title": "Guest" } }, "type": "object", "required": [ "request_id", "title", "kind", "moderation", "status", "deleted", "guest" ], "title": "ChatReportSummary" }, "ChatSettingsInput": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "origins": { "items": { "type": "string" }, "type": "array", "maxItems": 20, "title": "Origins" }, "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "enabled", "origins", "version" ], "title": "ChatSettingsInput" }, "ChatSettingsOutput": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "project_identifier": { "type": "string", "title": "Project Identifier" }, "project_name": { "type": "string", "title": "Project Name" }, "enabled": { "type": "boolean", "title": "Enabled" }, "origins": { "items": { "type": "string" }, "type": "array", "title": "Origins" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "response_time": { "anyOf": [ { "$ref": "#/components/schemas/ResponseMetricOutput" }, { "type": "null" } ] } }, "type": "object", "required": [ "project_id", "project_identifier", "project_name", "enabled", "origins", "version" ], "title": "ChatSettingsOutput" }, "CitationOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "source_id": { "type": "string", "title": "Source Id" }, "revision_id": { "type": "string", "title": "Revision Id" }, "kind": { "type": "string", "enum": [ "markdown", "website" ], "title": "Kind" }, "title": { "type": "string", "title": "Title" }, "excerpt": { "type": "string", "title": "Excerpt" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "type": "object", "required": [ "id", "source_id", "revision_id", "kind", "title", "excerpt", "url" ], "title": "CitationOutput" }, "ConfirmationInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "draft_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "title": "Draft Hash" }, "client_request_id": { "type": "string", "format": "uuid", "title": "Client Request Id" } }, "additionalProperties": false, "type": "object", "required": [ "version", "draft_hash", "client_request_id" ], "title": "ConfirmationInput" }, "ContactClearInput": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "ContactClearInput" }, "ConversationInput": { "properties": { "client_conversation_id": { "type": "string", "format": "uuid", "title": "Client Conversation Id", "description": "Generate one UUID per new conversation and reuse it if the response is lost." } }, "additionalProperties": false, "type": "object", "required": [ "client_conversation_id" ], "title": "ConversationInput" }, "ConversationOutput": { "properties": { "project_archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Archived At" }, "id": { "type": "string", "title": "Id" }, "project_id": { "type": "string", "title": "Project Id" }, "project_identifier": { "type": "string", "title": "Project Identifier" }, "project_name": { "type": "string", "title": "Project Name" }, "state": { "type": "string", "enum": [ "open", "closed" ], "title": "State" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "last_sequence": { "type": "integer", "title": "Last Sequence" }, "support_mode": { "type": "string", "enum": [ "ai", "waiting_human", "human" ], "title": "Support Mode", "default": "human" }, "mode_version": { "type": "integer", "title": "Mode Version", "default": 1, "description": "Current support-mode version; independent of the conversation version. A stale value returns 409." }, "ai_status": { "anyOf": [ { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, { "type": "null" } ], "title": "Ai Status" }, "unread_count": { "type": "integer", "title": "Unread Count" }, "follow_up_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Follow Up Email", "description": "Unverified follow-up contact; conversation owner and native administrators only." }, "contact_version": { "type": "integer", "title": "Contact Version", "default": 0, "description": "Current version of the separately stored follow-up contact. Use this value when clearing the contact." }, "customer": { "$ref": "#/components/schemas/CustomerOutput" }, "initial_ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Ip Address", "description": "First connection address; native administrators only." }, "last_customer_ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Customer Ip Address", "description": "Latest new customer message connection address; native administrators only. Admin replies and idempotent retries do not change it." }, "ai_available": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ai Available", "description": "Current explicit AI readiness; native administrators only." }, "reports": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChatReportSummary" }, "type": "array" }, { "type": "null" } ], "title": "Reports", "description": "Newest 20 submitted feedback summaries for this conversation; native administrators only. No customer credential or guest owner identity." }, "report_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Report Count", "description": "Total durable submitted feedback receipts, including deleted requests; native administrators only." } }, "type": "object", "required": [ "id", "project_id", "project_identifier", "project_name", "state", "version", "created_at", "updated_at", "last_sequence", "unread_count", "customer" ], "title": "ConversationOutput" }, "ConversationPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ConversationOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "ConversationPageOutput" }, "Coverage": { "properties": { "available_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$" }, { "type": "null" } ], "title": "Available From" }, "complete": { "type": "boolean", "title": "Complete" } }, "type": "object", "required": [ "complete" ], "title": "Coverage" }, "CoverageOutput": { "properties": { "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" }, "page_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Page Ids" }, "selected_passages": { "type": "integer", "title": "Selected Passages" }, "total_passages": { "type": "integer", "title": "Total Passages" }, "batch_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Batch Size" }, "total_batches": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Batches" }, "completed_batches": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed Batches" }, "completed_passages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed Passages" } }, "type": "object", "required": [ "selected_passages", "total_passages" ], "title": "CoverageOutput" }, "CrawlCancelInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "CrawlCancelInput" }, "CrawlConfigInput": { "properties": { "seed_url": { "type": "string", "maxLength": 2048, "minLength": 1, "title": "Seed Url" }, "approved_origins": { "items": { "type": "string" }, "type": "array", "maxItems": 5, "minItems": 1, "title": "Approved Origins", "description": "Explicit HTTP(S) origins. Subdomains and changed schemes are separate origins." }, "include_paths": { "items": { "type": "string" }, "type": "array", "maxItems": 20, "minItems": 1, "title": "Include Paths" }, "exclude_paths": { "items": { "type": "string" }, "type": "array", "maxItems": 20, "title": "Exclude Paths" }, "max_pages": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Max Pages", "default": 20 }, "max_depth": { "type": "integer", "maximum": 5.0, "minimum": 0.0, "title": "Max Depth", "default": 3 } }, "additionalProperties": false, "type": "object", "required": [ "seed_url", "approved_origins" ], "title": "CrawlConfigInput" }, "CrawlPageOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "attempt": { "type": "integer", "title": "Attempt" }, "url": { "type": "string", "title": "Url" }, "title": { "type": "string", "title": "Title" }, "content": { "type": "string", "title": "Content" }, "content_hash": { "type": "string", "title": "Content Hash" }, "status": { "type": "string", "enum": [ "fetched", "skipped", "failed" ], "title": "Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "attempt", "url", "title", "content", "content_hash", "status", "error", "created_at" ], "title": "CrawlPageOutput" }, "CrawlRunDetailOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "project_id": { "type": "string", "title": "Project Id" }, "source_id": { "type": "string", "title": "Source Id" }, "source_version": { "type": "integer", "title": "Source Version" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "config": { "$ref": "#/components/schemas/CrawlConfigInput" }, "created_at": { "type": "string", "title": "Created At" }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finished At" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "title": "Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "attempt_count": { "type": "integer", "title": "Attempt Count" }, "stop_reason": { "anyOf": [ { "type": "string", "const": "page_limit" }, { "type": "null" } ], "title": "Stop Reason" }, "fetched_count": { "type": "integer", "title": "Fetched Count" }, "skipped_count": { "type": "integer", "title": "Skipped Count" }, "failed_count": { "type": "integer", "title": "Failed Count" }, "pages": { "items": { "$ref": "#/components/schemas/CrawlPageOutput" }, "type": "array", "title": "Pages" } }, "type": "object", "required": [ "id", "project_id", "source_id", "source_version", "version", "config", "created_at", "finished_at", "document_id", "status", "error", "attempt_count", "stop_reason", "fetched_count", "skipped_count", "failed_count", "pages" ], "title": "CrawlRunDetailOutput" }, "CrawlRunOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "project_id": { "type": "string", "title": "Project Id" }, "source_id": { "type": "string", "title": "Source Id" }, "source_version": { "type": "integer", "title": "Source Version" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "config": { "$ref": "#/components/schemas/CrawlConfigInput" }, "created_at": { "type": "string", "title": "Created At" }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finished At" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "title": "Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "attempt_count": { "type": "integer", "title": "Attempt Count" }, "stop_reason": { "anyOf": [ { "type": "string", "const": "page_limit" }, { "type": "null" } ], "title": "Stop Reason" }, "fetched_count": { "type": "integer", "title": "Fetched Count" }, "skipped_count": { "type": "integer", "title": "Skipped Count" }, "failed_count": { "type": "integer", "title": "Failed Count" } }, "type": "object", "required": [ "id", "project_id", "source_id", "source_version", "version", "config", "created_at", "finished_at", "document_id", "status", "error", "attempt_count", "stop_reason", "fetched_count", "skipped_count", "failed_count" ], "title": "CrawlRunOutput" }, "CrawlRunPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CrawlRunOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "CrawlRunPageOutput" }, "CreatorEdit": { "properties": { "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title" }, "description": { "type": "string", "maxLength": 20000, "title": "Description", "default": "" }, "external_user_id": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "External User Id", "description": "Exact project-scoped ID verified by a trusted backend. Preserve case, whitespace and Unicode. It is not a credential and never links accounts across projects." }, "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "title", "version" ], "title": "CreatorEdit" }, "CustomerOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "kind": { "type": "string", "enum": [ "anonymous", "external", "native" ], "title": "Kind" }, "display_name": { "type": "string", "title": "Display Name" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "Exact project-scoped ID verified by a trusted backend. Preserve case, whitespace and Unicode. It is not a credential and never links accounts across projects." } }, "type": "object", "required": [ "id", "kind", "display_name" ], "title": "CustomerOutput" }, "CustomerRevokeInput": { "properties": { "external_user_id": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "External User Id", "description": "Exact project-scoped ID verified by a trusted backend. Preserve case, whitespace and Unicode. It is not a credential and never links accounts across projects." } }, "additionalProperties": false, "type": "object", "title": "CustomerRevokeInput" }, "CustomerSessionInput": { "properties": { "external_user_id": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "External User Id", "description": "Exact project-scoped ID verified by a trusted backend. Preserve case, whitespace and Unicode. It is not a credential and never links accounts across projects." }, "client_type": { "type": "string", "enum": [ "browser", "native" ], "title": "Client Type" }, "origin": { "anyOf": [ { "type": "string", "maxLength": 2048, "minLength": 1 }, { "type": "null" } ], "title": "Origin", "description": "Required with client_type=browser and omitted with client_type=native. Must be an allowed website origin; local account sessions may also use PUBLIC_BASE_URL. This JSON field is distinct from the request Origin header." }, "display_name": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Display Name", "description": "Optional only for project-key exchanges. Local account sessions use the account display name and must omit this field." } }, "additionalProperties": false, "type": "object", "required": [ "client_type" ], "title": "CustomerSessionInput" }, "CustomerSessionOutput": { "properties": { "token": { "type": "string", "title": "Token" }, "expires_at": { "type": "string", "title": "Expires At" }, "customer": { "$ref": "#/components/schemas/CustomerOutput" } }, "type": "object", "required": [ "token", "expires_at", "customer" ], "title": "CustomerSessionOutput" }, "DashboardOutput": { "properties": { "pending_requests": { "type": "integer", "title": "Pending Requests" }, "failed_deliveries": { "type": "integer", "title": "Failed Deliveries" } }, "type": "object", "required": [ "pending_requests", "failed_deliveries" ], "title": "DashboardOutput" }, "DecisionContext": { "properties": { "sender_role": { "type": "string", "enum": [ "customer", "ai", "admin", "visitor" ], "title": "Sender Role" }, "body": { "type": "string", "maxLength": 16000, "title": "Body" } }, "additionalProperties": false, "type": "object", "required": [ "sender_role", "body" ], "title": "DecisionContext" }, "DecisionHistoryItem": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "attempt": { "type": "integer", "title": "Attempt" }, "policy_version": { "type": "integer", "title": "Policy Version" }, "preset_version": { "type": "string", "title": "Preset Version" }, "outcome": { "type": "string", "title": "Outcome" }, "probability": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Probability" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "job_id", "attempt", "policy_version", "preset_version", "outcome", "probability", "model", "error", "created_at" ], "title": "DecisionHistoryItem" }, "DecisionHistoryOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DecisionHistoryItem" }, "type": "array", "title": "Items" }, "has_more": { "type": "boolean", "title": "Has More" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "items", "has_more", "limit", "offset" ], "title": "DecisionHistoryOutput" }, "DecisionKeyAction": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 1.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version" ], "title": "DecisionKeyAction" }, "DecisionKeyCreate": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "label": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Label" }, "quota_group": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Quota Group", "default": "Default account" }, "key": { "anyOf": [ { "type": "string", "maxLength": 4096, "minLength": 1, "format": "password", "writeOnly": true }, { "type": "null" } ], "title": "Key" }, "reuse_key_id": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Reuse Key Id" }, "account_id": { "anyOf": [ { "type": "string", "maxLength": 32, "minLength": 32, "pattern": "^[0-9a-f]{32}$" }, { "type": "null" } ], "title": "Account Id" } }, "additionalProperties": false, "type": "object", "required": [ "version", "label" ], "title": "DecisionKeyCreate" }, "DecisionKeyOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "label": { "type": "string", "title": "Label" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "quota_group": { "type": "string", "title": "Quota Group" }, "enabled": { "type": "boolean", "title": "Enabled" }, "has_key": { "type": "boolean", "title": "Has Key" }, "shared_with_generation": { "type": "boolean", "title": "Shared With Generation" }, "catalogue": { "items": { "type": "string" }, "type": "array", "title": "Catalogue" }, "verified": { "type": "boolean", "title": "Verified" }, "retry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Retry At" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "required": [ "id", "label", "version", "quota_group", "enabled", "has_key", "shared_with_generation", "catalogue", "verified", "retry_at", "reason" ], "title": "DecisionKeyOutput" }, "DecisionProviderOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "available": { "type": "boolean", "title": "Available" }, "status": { "type": "string", "title": "Status" }, "requires_account_id": { "type": "boolean", "title": "Requires Account Id" } }, "type": "object", "required": [ "id", "name", "available", "status", "requires_account_id" ], "title": "DecisionProviderOutput" }, "DecisionTest": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "key_version": { "type": "integer", "minimum": 1.0, "title": "Key Version", "description": "Current version of this AI credential. Refresh the key after a 409 conflict." }, "question": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Question" }, "history": { "items": { "$ref": "#/components/schemas/DecisionContext" }, "type": "array", "maxItems": 4, "title": "History" } }, "additionalProperties": false, "type": "object", "required": [ "version", "key_version", "question" ], "title": "DecisionTest" }, "DecisionTestOutput": { "properties": { "outcome": { "type": "string", "enum": [ "allow", "refuse", "clarify", "unavailable" ], "title": "Outcome" }, "probability": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Probability" }, "model": { "type": "string", "title": "Model" }, "preset": { "type": "string", "enum": [ "balanced", "strict" ], "title": "Preset" }, "preset_version": { "type": "string", "title": "Preset Version" }, "reply": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reply" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "outcome", "probability", "model", "preset", "preset_version", "reply", "error" ], "title": "DecisionTestOutput" }, "DeliveryOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "event_id": { "type": "string", "title": "Event Id" }, "destination": { "type": "string", "title": "Destination" }, "state": { "type": "string", "enum": [ "queued", "delivering", "succeeded", "failed" ], "title": "State" }, "attempt_count": { "type": "integer", "title": "Attempt Count" }, "next_attempt_at": { "type": "string", "title": "Next Attempt At" }, "last_attempt_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Attempt At" }, "last_http_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Http Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "delivered_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Delivered At" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload" } }, "type": "object", "required": [ "id", "event_id", "destination", "state", "attempt_count", "next_attempt_at", "last_attempt_at", "last_http_status", "error", "delivered_at" ], "title": "DeliveryOutput" }, "Detail": { "properties": { "key": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Key" }, "label": { "type": "string", "maxLength": 200, "title": "Label" }, "type": { "type": "string", "enum": [ "text", "number", "boolean", "timestamp", "badge", "link" ], "title": "Type" }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "title": "Value" } }, "type": "object", "required": [ "key", "label", "type", "value" ], "title": "Detail" }, "DeviceInput": { "properties": { "token": { "type": "string", "pattern": "^[0-9a-f]{64,200}$", "title": "Token" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ], "title": "Environment" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "default": "iPhone" }, "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "request_notifications": { "type": "boolean", "title": "Request Notifications", "default": true }, "chat_notifications": { "type": "boolean", "title": "Chat Notifications", "default": true } }, "additionalProperties": false, "type": "object", "required": [ "token", "environment" ], "title": "DeviceInput" }, "DeviceOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ], "title": "Environment" }, "enabled": { "type": "boolean", "title": "Enabled" }, "request_notifications": { "type": "boolean", "title": "Request Notifications" }, "chat_notifications": { "type": "boolean", "title": "Chat Notifications" }, "generation": { "type": "integer", "title": "Generation" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "name", "environment", "enabled", "request_notifications", "chat_notifications", "generation", "updated_at" ], "title": "DeviceOutput" }, "DevicesOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DeviceOutput" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "DevicesOutput" }, "DocumentContentOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "source_id": { "type": "string", "title": "Source Id" }, "project_id": { "type": "string", "title": "Project Id" }, "source_version": { "type": "integer", "title": "Source Version" }, "revision_number": { "type": "integer", "title": "Revision Number" }, "filename": { "type": "string", "title": "Filename" }, "title": { "type": "string", "title": "Title" }, "content_hash": { "type": "string", "title": "Content Hash" }, "byte_count": { "type": "integer", "title": "Byte Count" }, "created_at": { "type": "string", "title": "Created At" }, "content": { "type": "string", "title": "Content" } }, "type": "object", "required": [ "id", "source_id", "project_id", "source_version", "revision_number", "filename", "title", "content_hash", "byte_count", "created_at", "content" ], "title": "DocumentContentOutput" }, "DocumentOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "source_id": { "type": "string", "title": "Source Id" }, "project_id": { "type": "string", "title": "Project Id" }, "source_version": { "type": "integer", "title": "Source Version" }, "revision_number": { "type": "integer", "title": "Revision Number" }, "filename": { "type": "string", "title": "Filename" }, "title": { "type": "string", "title": "Title" }, "content_hash": { "type": "string", "title": "Content Hash" }, "byte_count": { "type": "integer", "title": "Byte Count" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "source_id", "project_id", "source_version", "revision_number", "filename", "title", "content_hash", "byte_count", "created_at" ], "title": "DocumentOutput" }, "DocumentPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DocumentOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "DocumentPageOutput" }, "DraftInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title" }, "description": { "type": "string", "maxLength": 20000, "title": "Description" } }, "additionalProperties": false, "type": "object", "required": [ "version", "title", "description" ], "title": "DraftInput" }, "DraftSectionOutput": { "properties": { "kind": { "type": "string", "enum": [ "section", "faq" ], "title": "Kind" }, "title": { "type": "string", "title": "Title" }, "body": { "type": "string", "title": "Body" }, "category": { "type": "string", "title": "Category" }, "citation_ids": { "items": { "type": "string" }, "type": "array", "title": "Citation Ids" } }, "type": "object", "required": [ "kind", "title", "body", "category", "citation_ids" ], "title": "DraftSectionOutput" }, "Edit": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "Edit" }, "Enable": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "receipt": { "type": "string", "maxLength": 16384, "minLength": 1, "title": "Receipt" }, "link_origins": { "items": { "type": "string" }, "type": "array", "maxItems": 8, "title": "Link Origins", "default": [] }, "support_linked": { "type": "boolean", "title": "Support Linked", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "version", "receipt" ], "title": "Enable" }, "EventOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "title": "Type" }, "occurred_at": { "type": "string", "title": "Occurred At" }, "schema_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Schema Version" }, "project": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Project" }, "board": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Board" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "request": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Request" }, "previous": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Previous" }, "actor": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Actor" }, "creator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Creator" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "previous_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Status" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip Address", "description": "Connection address for this action. Native administrators only; never included in webhook payloads." } }, "type": "object", "required": [ "id", "type", "occurred_at" ], "title": "EventOutput" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HoursAvailability": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "source": { "type": "string", "enum": [ "account", "project" ], "title": "Source" }, "timezone": { "type": "string", "title": "Timezone" }, "days": { "items": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" }, "type": "array", "title": "Days" }, "is_open": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Open" }, "next_open_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Open At" }, "collect_email": { "type": "boolean", "title": "Collect Email" }, "observed_at": { "type": "string", "title": "Observed At" } }, "type": "object", "required": [ "enabled", "source", "timezone", "days", "is_open", "next_open_at", "collect_email", "observed_at" ], "title": "HoursAvailability" }, "HoursEdit": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "mode": { "type": "string", "enum": [ "inherit", "override", "off" ], "title": "Mode", "default": "override" }, "schedule": { "$ref": "#/components/schemas/WeeklyHours" } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "HoursEdit" }, "HoursSettingsOutput": { "properties": { "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "mode": { "type": "string", "enum": [ "inherit", "override", "off" ], "title": "Mode" }, "schedule": { "$ref": "#/components/schemas/WeeklyHours" }, "effective": { "$ref": "#/components/schemas/WeeklyHours" }, "source": { "type": "string", "enum": [ "account", "project" ], "title": "Source" } }, "type": "object", "required": [ "version", "mode", "schedule", "effective", "source" ], "title": "HoursSettingsOutput" }, "IdentityOutput": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "external_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External User Id", "description": "Exact project-scoped ID verified by a trusted backend. Preserve case, whitespace and Unicode. It is not a credential and never links accounts across projects." }, "creator": { "type": "boolean", "title": "Creator" } }, "type": "object", "required": [ "user_id", "external_user_id", "creator" ], "title": "IdentityOutput" }, "Interval": { "properties": { "start": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "title": "Start" }, "end": { "type": "string", "pattern": "^(?:(?:[01][0-9]|2[0-3]):[0-5][0-9]|24:00)$", "title": "End" } }, "additionalProperties": false, "type": "object", "required": [ "start", "end" ], "title": "Interval" }, "KeyInput": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name" }, "permissions": { "items": { "type": "string", "enum": [ "read", "participate", "audience:read", "manage" ] }, "type": "array", "maxItems": 4, "minItems": 1, "title": "Permissions" } }, "additionalProperties": false, "type": "object", "required": [ "name", "permissions" ], "title": "KeyInput" }, "KeyOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "prefix": { "type": "string", "title": "Prefix" }, "permissions": { "items": { "type": "string", "enum": [ "read", "participate", "audience:read", "manage" ] }, "type": "array", "title": "Permissions" }, "created_at": { "type": "string", "title": "Created At" }, "revoked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked At" } }, "type": "object", "required": [ "id", "name", "prefix", "permissions", "created_at", "revoked_at" ], "title": "KeyOutput" }, "KnowledgeJobOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "title": "State" }, "attempt_count": { "type": "integer", "title": "Attempt Count" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "state", "attempt_count", "error", "created_at", "updated_at" ], "title": "KnowledgeJobOutput" }, "KnowledgeSourceOutput": { "properties": { "index_ready": { "type": "boolean", "title": "Index Ready" }, "id": { "type": "string", "title": "Id" }, "project_id": { "type": "string", "title": "Project Id" }, "kind": { "type": "string", "enum": [ "markdown", "website" ], "title": "Kind" }, "name": { "type": "string", "title": "Name" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "active": { "type": "boolean", "title": "Active" }, "approved": { "type": "boolean", "title": "Approved" }, "active_revision_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Active Revision Id" }, "latest_document": { "anyOf": [ { "$ref": "#/components/schemas/DocumentOutput" }, { "type": "null" } ] }, "index_status": { "type": "string", "enum": [ "empty", "pending", "indexing", "indexed", "failed", "cancelled", "inactive", "deleted" ], "title": "Index Status" }, "index_stale": { "type": "boolean", "title": "Index Stale" }, "job": { "anyOf": [ { "$ref": "#/components/schemas/KnowledgeJobOutput" }, { "type": "null" } ] }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "deleted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deleted At" } }, "type": "object", "required": [ "index_ready", "id", "project_id", "kind", "name", "location", "version", "active", "approved", "active_revision_id", "latest_document", "index_status", "index_stale", "job", "created_at", "updated_at", "deleted_at" ], "title": "KnowledgeSourceOutput" }, "KnowledgeSourcePageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/KnowledgeSourceOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "KnowledgeSourcePageOutput" }, "LibraryContentOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "source_id": { "type": "string", "title": "Source Id" }, "source_name": { "type": "string", "title": "Source Name" }, "kind": { "type": "string", "enum": [ "markdown", "website" ], "title": "Kind" }, "title": { "type": "string", "title": "Title" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "created_at": { "type": "string", "title": "Created At" }, "ready": { "type": "boolean", "title": "Ready" }, "status": { "type": "string", "title": "Status" }, "excerpt": { "type": "string", "title": "Excerpt" }, "content": { "type": "string", "title": "Content" } }, "type": "object", "required": [ "id", "source_id", "source_name", "kind", "title", "url", "created_at", "ready", "status", "excerpt", "content" ], "title": "LibraryContentOutput" }, "LibraryItemOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "source_id": { "type": "string", "title": "Source Id" }, "source_name": { "type": "string", "title": "Source Name" }, "kind": { "type": "string", "enum": [ "markdown", "website" ], "title": "Kind" }, "title": { "type": "string", "title": "Title" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "created_at": { "type": "string", "title": "Created At" }, "ready": { "type": "boolean", "title": "Ready" }, "status": { "type": "string", "title": "Status" }, "excerpt": { "type": "string", "title": "Excerpt" } }, "type": "object", "required": [ "id", "source_id", "source_name", "kind", "title", "url", "created_at", "ready", "status", "excerpt" ], "title": "LibraryItemOutput" }, "LibraryPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/LibraryItemOutput" }, "type": "array", "title": "Items" }, "has_more": { "type": "boolean", "title": "Has More" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "items", "has_more", "limit", "offset" ], "title": "LibraryPageOutput" }, "Lifecycle": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "status": { "type": "string", "enum": [ "under_consideration", "planned", "in_progress", "shipped" ], "title": "Status" } }, "additionalProperties": false, "type": "object", "required": [ "version", "status" ], "title": "Lifecycle" }, "LoginInput": { "properties": { "email": { "type": "string", "maxLength": 254, "minLength": 3, "title": "Email" }, "password": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Password" } }, "additionalProperties": false, "type": "object", "required": [ "email", "password" ], "title": "LoginInput" }, "Lookup": { "properties": { "user_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "User Id" } }, "additionalProperties": false, "type": "object", "required": [ "user_id" ], "title": "Lookup" }, "MarkdownImportOutput": { "properties": { "source": { "$ref": "#/components/schemas/KnowledgeSourceOutput" }, "document": { "$ref": "#/components/schemas/DocumentOutput" } }, "type": "object", "required": [ "source", "document" ], "title": "MarkdownImportOutput" }, "MarkdownInput": { "properties": { "client_import_id": { "type": "string", "format": "uuid", "title": "Client Import Id" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Filename", "description": "A display filename ending in .md or .markdown, without directories." }, "name": { "type": "string", "maxLength": 300, "minLength": 1, "title": "Name" }, "content": { "type": "string", "maxLength": 65536, "minLength": 1, "title": "Content", "description": "Exact UTF-8 Markdown, limited to 64 KiB after encoding. Imported as untrusted source content, never as agent instructions." } }, "additionalProperties": false, "type": "object", "required": [ "client_import_id", "filename", "name", "content" ], "title": "MarkdownInput" }, "MarkdownReplacementInput": { "properties": { "client_import_id": { "type": "string", "format": "uuid", "title": "Client Import Id" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Filename", "description": "A display filename ending in .md or .markdown, without directories." }, "name": { "type": "string", "maxLength": 300, "minLength": 1, "title": "Name" }, "content": { "type": "string", "maxLength": 65536, "minLength": 1, "title": "Content", "description": "Exact UTF-8 Markdown, limited to 64 KiB after encoding. Imported as untrusted source content, never as agent instructions." }, "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "client_import_id", "filename", "name", "content", "version" ], "title": "MarkdownReplacementInput" }, "MessageInput": { "properties": { "client_message_id": { "type": "string", "format": "uuid", "title": "Client Message Id", "description": "Generate one UUID per new message and reuse it on retries, including after credential renewal. Different content with the same ID returns 409." }, "body": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Body" }, "follow_up_email": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ], "title": "Follow Up Email", "description": "Optional unverified address for manual human follow-up. Stored separately from messages; never sent to AI or notification payloads." } }, "additionalProperties": false, "type": "object", "required": [ "client_message_id", "body" ], "title": "MessageInput" }, "MessageOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "conversation_id": { "type": "string", "title": "Conversation Id" }, "sequence": { "type": "integer", "title": "Sequence" }, "client_message_id": { "type": "string", "title": "Client Message Id", "description": "Generate one UUID per new message and reuse it on retries, including after credential renewal. Different content with the same ID returns 409." }, "sender": { "type": "string", "enum": [ "visitor", "admin", "ai" ], "title": "Sender" }, "sender_role": { "type": "string", "enum": [ "customer", "admin", "ai" ], "title": "Sender Role" }, "body": { "type": "string", "title": "Body" }, "created_at": { "type": "string", "title": "Created At" }, "citations": { "items": { "$ref": "#/components/schemas/CitationOutput" }, "type": "array", "title": "Citations" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip Address", "description": "Sender connection address; native administrators only. Never included in notifications or webhooks." } }, "type": "object", "required": [ "id", "conversation_id", "sequence", "client_message_id", "sender", "sender_role", "body", "created_at" ], "title": "MessageOutput" }, "MessagePageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/MessageOutput" }, "type": "array", "title": "Items" }, "has_more": { "type": "boolean", "title": "Has More" }, "next_sequence": { "type": "integer", "title": "Next Sequence" } }, "type": "object", "required": [ "items", "has_more", "next_sequence" ], "title": "MessagePageOutput" }, "Metric": { "properties": { "count": { "anyOf": [ { "type": "integer", "maximum": 9007199254740991.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Count" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "unsupported", "history_incomplete" ] }, { "type": "null" } ], "title": "Reason" } }, "type": "object", "required": [ "count" ], "title": "Metric" }, "NativeSessionOutput": { "properties": { "user": { "$ref": "#/components/schemas/UserOutput" }, "token": { "type": "string", "title": "Token" }, "expires_at": { "type": "string", "title": "Expires At" }, "installation_id": { "type": "string", "title": "Installation Id" } }, "type": "object", "required": [ "user", "token", "expires_at", "installation_id" ], "title": "NativeSessionOutput" }, "NewAccounts": { "properties": { "count": { "anyOf": [ { "type": "integer", "maximum": 9007199254740991.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Count" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "unsupported", "history_incomplete" ] }, { "type": "null" } ], "title": "Reason" }, "basis": { "type": "string", "enum": [ "current_accounts", "signup_events" ], "title": "Basis" }, "complete": { "type": "boolean", "title": "Complete" }, "available_from": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$" }, { "type": "null" } ], "title": "Available From" } }, "type": "object", "required": [ "count", "basis", "complete" ], "title": "NewAccounts" }, "NewKeyOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "secret": { "type": "string", "title": "Secret" }, "prefix": { "type": "string", "title": "Prefix" }, "permissions": { "items": { "type": "string", "enum": [ "read", "participate", "audience:read", "manage" ] }, "type": "array", "title": "Permissions" } }, "type": "object", "required": [ "id", "secret", "prefix", "permissions" ], "title": "NewKeyOutput" }, "NotificationOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "sequence": { "type": "integer", "title": "Sequence" }, "type": { "type": "string", "enum": [ "request.created", "request.resubmitted", "chat.message_created", "chat.support_mode_changed" ], "title": "Type" }, "project_id": { "type": "string", "title": "Project Id" }, "project_name": { "type": "string", "title": "Project Name" }, "title": { "type": "string", "title": "Title" }, "created_at": { "type": "string", "title": "Created At" }, "read_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Read At" }, "resource_kind": { "type": "string", "enum": [ "request", "conversation" ], "title": "Resource Kind" }, "resource_id": { "type": "string", "title": "Resource Id" }, "url": { "type": "string", "title": "Url" }, "resource_available": { "type": "boolean", "title": "Resource Available" } }, "type": "object", "required": [ "id", "sequence", "type", "project_id", "project_name", "title", "created_at", "read_at", "resource_kind", "resource_id", "url", "resource_available" ], "title": "NotificationOutput" }, "NotificationPageOutput": { "properties": { "unread_count": { "type": "integer", "title": "Unread Count" }, "through_sequence": { "type": "integer", "title": "Through Sequence" }, "items": { "items": { "$ref": "#/components/schemas/NotificationOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "unread_count", "through_sequence", "items", "limit", "offset", "has_more" ], "title": "NotificationPageOutput" }, "NotificationReadAllInput": { "properties": { "through_sequence": { "type": "integer", "maximum": 9.223372036854776e+18, "minimum": 0.0, "title": "Through Sequence", "description": "Use the through_sequence returned by the displayed inbox or summary. Later arrivals stay unread." } }, "additionalProperties": false, "type": "object", "required": [ "through_sequence" ], "title": "NotificationReadAllInput" }, "NotificationReadInput": { "properties": { "read": { "type": "boolean", "title": "Read" } }, "additionalProperties": false, "type": "object", "required": [ "read" ], "title": "NotificationReadInput" }, "NotificationSummaryOutput": { "properties": { "unread_count": { "type": "integer", "title": "Unread Count" }, "through_sequence": { "type": "integer", "title": "Through Sequence" } }, "type": "object", "required": [ "unread_count", "through_sequence" ], "title": "NotificationSummaryOutput" }, "PageOutput_AccountActivityOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AccountActivityOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[AccountActivityOutput]" }, "PageOutput_BoardOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/feedback__outputs__BoardOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[BoardOutput]" }, "PageOutput_DeliveryOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DeliveryOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[DeliveryOutput]" }, "PageOutput_EventOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/EventOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[EventOutput]" }, "PageOutput_IdentityOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/IdentityOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[IdentityOutput]" }, "PageOutput_KeyOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/KeyOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[KeyOutput]" }, "PageOutput_ProjectOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProjectOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[ProjectOutput]" }, "PageOutput_PushDeliveryOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PushDeliveryOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[PushDeliveryOutput]" }, "PageOutput_RequestOutput_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RequestOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "PageOutput[RequestOutput]" }, "PasswordInput": { "properties": { "current_password": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Current Password" }, "new_password": { "type": "string", "maxLength": 128, "minLength": 12, "title": "New Password" } }, "additionalProperties": false, "type": "object", "required": [ "current_password", "new_password" ], "title": "PasswordInput" }, "PersonalityInput": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "filename": { "type": "string", "const": "soul.md", "title": "Filename", "default": "soul.md" }, "content": { "type": "string", "maxLength": 20000, "title": "Content", "description": "UTF-8 personality Markdown. This controls presentation only, never evidence requirements or tool permissions." } }, "additionalProperties": false, "type": "object", "required": [ "version", "content" ], "title": "PersonalityInput" }, "PersonalityOutput": { "properties": { "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "filename": { "type": "string", "const": "soul.md", "title": "Filename" }, "content": { "type": "string", "title": "Content" } }, "type": "object", "required": [ "version", "filename", "content" ], "title": "PersonalityOutput" }, "Preferences": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "timezone": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Timezone" } }, "additionalProperties": false, "type": "object", "required": [ "version", "timezone" ], "title": "Preferences" }, "PreviewInput": { "properties": { "client_request_id": { "type": "string", "format": "uuid", "title": "Client Request Id" }, "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Current project AI configuration version." }, "question": { "type": "string", "maxLength": 1000, "minLength": 1, "title": "Question" } }, "additionalProperties": false, "type": "object", "required": [ "client_request_id", "version", "question" ], "title": "PreviewInput" }, "PreviewResultOutput": { "properties": { "body": { "type": "string", "title": "Body" }, "citation_ids": { "items": { "type": "string" }, "type": "array", "title": "Citation Ids" }, "knowledge_version": { "type": "integer", "title": "Knowledge Version" }, "status": { "type": "string", "enum": [ "answered", "insufficient", "refuse", "clarify", "greeting", "unavailable" ], "title": "Status" } }, "type": "object", "required": [ "body", "citation_ids", "knowledge_version", "status" ], "title": "PreviewResultOutput" }, "Profile": { "properties": { "protocol": { "$ref": "#/components/schemas/Protocol" }, "app_instance_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "App Instance Id" }, "observed_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Observed At" }, "user": { "$ref": "#/components/schemas/User" }, "details": { "items": { "$ref": "#/components/schemas/Detail" }, "type": "array", "maxItems": 12, "title": "Details", "default": [] }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Url" } }, "type": "object", "required": [ "protocol", "app_instance_id", "observed_at", "user" ], "title": "Profile" }, "ProfileRead": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "query": { "$ref": "#/components/schemas/Lookup" } }, "additionalProperties": false, "type": "object", "required": [ "version", "query" ], "title": "ProfileRead" }, "ProjectKeySelection": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "library_version": { "type": "integer", "minimum": 0.0, "title": "Library Version", "description": "Current version of the installation AI credential library; required alongside the project settings version for binding changes." }, "key_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 99, "title": "Key Ids" } }, "additionalProperties": false, "type": "object", "required": [ "version", "library_version", "key_ids" ], "title": "ProjectKeySelection" }, "ProjectOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "identifier": { "type": "string", "title": "Identifier" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Archived At" } }, "type": "object", "required": [ "id", "identifier", "name", "description", "created_at", "updated_at", "version" ], "title": "ProjectOutput" }, "ProposalOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "conversation_id": { "type": "string", "title": "Conversation Id" }, "message_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Message Sequence", "description": "Owning chat message position for inline review; never a credential." }, "kind": { "type": "string", "enum": [ "feature", "bug" ], "title": "Kind" }, "board": { "$ref": "#/components/schemas/feedback__ai_reports_api__BoardOutput" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "draft_hash": { "type": "string", "title": "Draft Hash" }, "state": { "type": "string", "enum": [ "pending", "confirmed", "cancelled" ], "title": "State" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "can_confirm": { "type": "boolean", "title": "Can Confirm" }, "can_edit": { "type": "boolean", "title": "Can Edit" }, "guest": { "type": "boolean", "title": "Guest" }, "feedback_url": { "type": "string", "title": "Feedback Url" }, "tracking_notice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tracking Notice" }, "report_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Id" }, "copy_text": { "type": "string", "title": "Copy Text" } }, "type": "object", "required": [ "id", "conversation_id", "kind", "board", "title", "description", "version", "draft_hash", "state", "expires_at", "can_confirm", "can_edit", "guest", "feedback_url", "tracking_notice", "report_id", "copy_text" ], "title": "ProposalOutput" }, "ProposalPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProposalOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "ProposalPageOutput" }, "Protocol": { "properties": { "major": { "type": "integer", "const": 1, "title": "Major", "default": 1 }, "minor": { "type": "integer", "minimum": 0.0, "title": "Minor", "default": 0 } }, "type": "object", "title": "Protocol" }, "PushDeliveryOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "event_id": { "type": "string", "title": "Event Id" }, "kind": { "type": "string", "enum": [ "request.created", "chat.message" ], "title": "Kind" }, "resource_id": { "type": "string", "title": "Resource Id" }, "device_id": { "type": "string", "title": "Device Id" }, "state": { "type": "string", "enum": [ "queued", "sending", "awaiting", "succeeded", "failed", "cancelled", "expired" ], "title": "State" }, "attempt_count": { "type": "integer", "title": "Attempt Count" }, "retry_count": { "type": "integer", "title": "Retry Count" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "created_at": { "type": "string", "title": "Created At" }, "expires_at": { "type": "string", "title": "Expires At" } }, "type": "object", "required": [ "id", "event_id", "kind", "resource_id", "device_id", "state", "attempt_count", "retry_count", "error", "created_at", "expires_at" ], "title": "PushDeliveryOutput" }, "PushInput": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "relay_url": { "type": "string", "maxLength": 2048, "title": "Relay Url", "description": "HTTPS origin of the optional push relay, without /api/v1. SupaKnock provides https://relay.supaknock.com. Choose the origin before enrollment; enrolled installations cannot switch relays through this setting.", "default": "https://relay.supaknock.com" } }, "additionalProperties": false, "type": "object", "required": [ "enabled" ], "title": "PushInput" }, "PushOutput": { "properties": { "installation_id": { "type": "string", "title": "Installation Id" }, "enabled": { "type": "boolean", "title": "Enabled" }, "connected": { "type": "boolean", "title": "Connected" }, "relay_url": { "type": "string", "title": "Relay Url" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error" } }, "type": "object", "required": [ "installation_id", "enabled", "connected", "relay_url", "last_error" ], "title": "PushOutput" }, "Range": { "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "From" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Until" } }, "additionalProperties": false, "type": "object", "required": [ "from", "until" ], "title": "Range" }, "ReadInput": { "properties": { "sequence": { "type": "integer", "maximum": 2147483647.0, "minimum": 0.0, "title": "Sequence" } }, "additionalProperties": false, "type": "object", "required": [ "sequence" ], "title": "ReadInput" }, "ReadOutput": { "properties": { "read_sequence": { "type": "integer", "title": "Read Sequence" } }, "type": "object", "required": [ "read_sequence" ], "title": "ReadOutput" }, "ReadOutput_ActivityPage_": { "properties": { "data": { "$ref": "#/components/schemas/ActivityPage" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "project_id": { "type": "string", "title": "Project Id" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" }, "user_filters": { "items": { "type": "string" }, "type": "array", "title": "User Filters" }, "continuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continuation" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "additionalProperties": false, "type": "object", "required": [ "data", "version", "project_id", "capabilities", "user_filters", "continuation" ], "title": "ReadOutput[ActivityPage]" }, "ReadOutput_Profile_": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "project_id": { "type": "string", "title": "Project Id" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" }, "user_filters": { "items": { "type": "string" }, "type": "array", "title": "User Filters" }, "continuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continuation" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "additionalProperties": false, "type": "object", "required": [ "data", "version", "project_id", "capabilities", "user_filters", "continuation" ], "title": "ReadOutput[Profile]" }, "ReadOutput_Summary_": { "properties": { "data": { "$ref": "#/components/schemas/Summary" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "project_id": { "type": "string", "title": "Project Id" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" }, "user_filters": { "items": { "type": "string" }, "type": "array", "title": "User Filters" }, "continuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continuation" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "additionalProperties": false, "type": "object", "required": [ "data", "version", "project_id", "capabilities", "user_filters", "continuation" ], "title": "ReadOutput[Summary]" }, "ReadOutput_UserPage_": { "properties": { "data": { "$ref": "#/components/schemas/UserPage" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "project_id": { "type": "string", "title": "Project Id" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" }, "user_filters": { "items": { "type": "string" }, "type": "array", "title": "User Filters" }, "continuation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continuation" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "additionalProperties": false, "type": "object", "required": [ "data", "version", "project_id", "capabilities", "user_filters", "continuation" ], "title": "ReadOutput[UserPage]" }, "Rejection": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Reason" } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "Rejection" }, "Related": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "user_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "User Id" }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "default": 25 }, "offset": { "type": "integer", "maximum": 1000000.0, "minimum": 0.0, "title": "Offset", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "version", "user_id" ], "title": "Related" }, "ReportOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "conversation_id": { "type": "string", "title": "Conversation Id" }, "message_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Message Sequence", "description": "Original chat position, retained after submission and status changes." }, "request_id": { "type": "string", "title": "Request Id" }, "kind": { "type": "string", "enum": [ "feature", "bug" ], "title": "Kind" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "moderation": { "anyOf": [ { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, { "type": "null" } ], "title": "Moderation" }, "status": { "anyOf": [ { "type": "string", "enum": [ "under_consideration", "planned", "in_progress", "shipped" ] }, { "type": "null" } ], "title": "Status" }, "accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accepted At", "description": "Time of first acceptance. Never cleared or replaced; once set, creator editing and deletion stay locked." }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "deleted": { "type": "boolean", "title": "Deleted" }, "guest": { "type": "boolean", "title": "Guest" }, "can_edit": { "type": "boolean", "title": "Can Edit" }, "can_delete": { "type": "boolean", "title": "Can Delete" }, "feedback_url": { "type": "string", "title": "Feedback Url" }, "public_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Public Url" }, "tracking_notice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tracking Notice" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "conversation_id", "request_id", "kind", "title", "description", "moderation", "status", "accepted_at", "version", "deleted", "guest", "can_edit", "can_delete", "feedback_url", "public_url", "tracking_notice", "created_at" ], "title": "ReportOutput" }, "ReportPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ReportOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "ReportPageOutput" }, "RequestOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "board_id": { "type": "string", "title": "Board Id" }, "project_id": { "type": "string", "title": "Project Id" }, "project_identifier": { "type": "string", "title": "Project Identifier" }, "project_name": { "type": "string", "title": "Project Name" }, "board_name": { "type": "string", "title": "Board Name" }, "board_identifier": { "type": "string", "title": "Board Identifier" }, "title": { "type": "string", "title": "Title" }, "description": { "type": "string", "title": "Description" }, "status": { "anyOf": [ { "type": "string", "enum": [ "under_consideration", "planned", "in_progress", "shipped" ] }, { "type": "null" } ], "title": "Status" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "vote_count": { "type": "integer", "title": "Vote Count" }, "voted": { "type": "boolean", "title": "Voted" }, "creator_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Creator Name" }, "owned": { "type": "boolean", "title": "Owned" }, "can_edit": { "type": "boolean", "title": "Can Edit" }, "archived": { "type": "boolean", "title": "Archived", "default": false }, "moderation": { "anyOf": [ { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, { "type": "null" } ], "title": "Moderation" }, "rejection_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rejection Reason" }, "accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accepted At", "description": "Time of first acceptance. Never cleared or replaced; once set, creator editing and deletion stay locked." }, "submitted_ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Submitted Ip Address", "description": "Connection address recorded at submission. Native administrators only; omitted for all other callers. Older records may be null." } }, "type": "object", "required": [ "id", "board_id", "project_id", "project_identifier", "project_name", "board_name", "board_identifier", "title", "description", "status", "created_at", "updated_at", "version", "vote_count", "voted", "creator_name", "owned", "can_edit" ], "title": "RequestOutput" }, "ResourceEdit": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name" }, "description": { "type": "string", "maxLength": 20000, "title": "Description", "default": "" }, "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "name", "version" ], "title": "ResourceEdit" }, "ResourceInput": { "properties": { "identifier": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,59}$", "title": "Identifier" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name" }, "description": { "type": "string", "maxLength": 20000, "title": "Description", "default": "" } }, "additionalProperties": false, "type": "object", "required": [ "identifier", "name" ], "title": "ResourceInput" }, "ResponseLabelOutput": { "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" } }, "type": "object", "required": [ "label" ], "title": "ResponseLabelOutput" }, "ResponseMetricOutput": { "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "median_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Median Seconds" }, "answered_count": { "type": "integer", "title": "Answered Count" }, "unanswered_count": { "type": "integer", "title": "Unanswered Count" }, "window_days": { "type": "integer", "title": "Window Days" }, "minimum_answered": { "type": "integer", "title": "Minimum Answered" }, "recent_reply": { "type": "boolean", "title": "Recent Reply" } }, "type": "object", "required": [ "label", "median_seconds", "answered_count", "unanswered_count", "window_days", "minimum_answered", "recent_reply" ], "title": "ResponseMetricOutput" }, "RetryInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "client_request_id": { "type": "string", "format": "uuid", "title": "Client Request Id" } }, "additionalProperties": false, "type": "object", "required": [ "version", "client_request_id" ], "title": "RetryInput" }, "RetryOutput": { "properties": { "queued": { "type": "boolean", "title": "Queued" } }, "type": "object", "required": [ "queued" ], "title": "RetryOutput" }, "RuntimeAction": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "RuntimeAction" }, "RuntimeDownload": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "token": { "type": "string", "maxLength": 2048, "minLength": 1, "format": "password", "title": "Token", "writeOnly": true } }, "additionalProperties": false, "type": "object", "required": [ "version", "token" ], "title": "RuntimeDownload" }, "RuntimeOutput": { "properties": { "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "state": { "type": "string", "enum": [ "not_downloaded", "downloading", "verifying", "ready", "removing", "failed" ], "title": "State" }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Id" }, "action": { "anyOf": [ { "type": "string", "enum": [ "download", "remove" ] }, { "type": "null" } ], "title": "Action" }, "progress_bytes": { "type": "integer", "title": "Progress Bytes" }, "total_bytes": { "type": "integer", "title": "Total Bytes" }, "attempt_count": { "type": "integer", "title": "Attempt Count" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "active_cache_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Active Cache Id" }, "active_manifest": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Active Manifest" }, "model_id": { "type": "string", "title": "Model Id" }, "download_bytes": { "type": "integer", "title": "Download Bytes" }, "license_url": { "type": "string", "title": "License Url" } }, "type": "object", "required": [ "version", "state", "operation_id", "action", "progress_bytes", "total_bytes", "attempt_count", "error", "updated_at", "active_cache_id", "active_manifest", "model_id", "download_bytes", "license_url" ], "title": "RuntimeOutput" }, "Save": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "base_url": { "type": "string", "maxLength": 2048, "minLength": 1, "title": "Base Url" }, "token": { "anyOf": [ { "type": "string", "maxLength": 4096, "minLength": 1 }, { "type": "null" } ], "title": "Token" } }, "additionalProperties": false, "type": "object", "required": [ "version", "base_url" ], "title": "Save" }, "SectionInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title" }, "body": { "type": "string", "maxLength": 4000, "minLength": 1, "title": "Body" }, "category": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Category" }, "citation_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 6, "minItems": 1, "title": "Citation Ids" } }, "additionalProperties": false, "type": "object", "required": [ "version", "title", "body", "category", "citation_ids" ], "title": "SectionInput" }, "SectionOutput": { "properties": { "kind": { "type": "string", "enum": [ "section", "faq" ], "title": "Kind" }, "title": { "type": "string", "title": "Title" }, "body": { "type": "string", "title": "Body" }, "category": { "type": "string", "title": "Category" }, "citation_ids": { "items": { "type": "string" }, "type": "array", "title": "Citation Ids" }, "id": { "type": "string", "title": "Id" }, "run_id": { "type": "string", "title": "Run Id" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "stale": { "type": "boolean", "title": "Stale" }, "deleted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deleted At" }, "published_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published Source Id" }, "citations": { "items": { "$ref": "#/components/schemas/CitationOutput" }, "type": "array", "title": "Citations" } }, "type": "object", "required": [ "kind", "title", "body", "category", "citation_ids", "id", "run_id", "version", "stale", "deleted_at", "citations" ], "title": "SectionOutput" }, "SectionPageOutput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SectionOutput" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "limit", "offset", "has_more" ], "title": "SectionPageOutput" }, "SectionsInput": { "properties": { "client_request_id": { "type": "string", "format": "uuid", "title": "Client Request Id" }, "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "source_version": { "type": "integer", "minimum": 1.0, "title": "Source Version" }, "page_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 50, "minItems": 1 }, { "type": "null" } ], "title": "Page Ids" } }, "additionalProperties": false, "type": "object", "required": [ "client_request_id", "version", "source_version" ], "title": "SectionsInput" }, "SectionsResultOutput": { "properties": { "sections": { "items": { "$ref": "#/components/schemas/DraftSectionOutput" }, "type": "array", "title": "Sections" }, "knowledge_version": { "type": "integer", "title": "Knowledge Version" } }, "type": "object", "required": [ "sections", "knowledge_version" ], "title": "SectionsResultOutput" }, "SessionOutput": { "properties": { "user": { "$ref": "#/components/schemas/UserOutput" }, "csrf_token": { "type": "string", "title": "Csrf Token" } }, "type": "object", "required": [ "user", "csrf_token" ], "title": "SessionOutput" }, "SetupInput": { "properties": { "email": { "type": "string", "maxLength": 254, "minLength": 3, "title": "Email" }, "password": { "type": "string", "maxLength": 128, "minLength": 12, "title": "Password" }, "display_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Display Name" }, "setup_token": { "type": "string", "maxLength": 256, "minLength": 24, "title": "Setup Token" } }, "additionalProperties": false, "type": "object", "required": [ "email", "password", "setup_token" ], "title": "SetupInput" }, "SetupOutput": { "properties": { "available": { "type": "boolean", "title": "Available" }, "registration_enabled": { "type": "boolean", "title": "Registration Enabled" } }, "type": "object", "required": [ "available", "registration_enabled" ], "title": "SetupOutput" }, "SourceStateInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "active": { "type": "boolean", "title": "Active" }, "approved": { "type": "boolean", "title": "Approved" } }, "additionalProperties": false, "type": "object", "required": [ "version", "active", "approved" ], "title": "SourceStateInput" }, "StateInput": { "properties": { "state": { "type": "string", "enum": [ "open", "closed" ], "title": "State" }, "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "state", "version" ], "title": "StateInput" }, "Submission": { "properties": { "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title" }, "description": { "type": "string", "maxLength": 20000, "title": "Description", "default": "" }, "external_user_id": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "External User Id", "description": "Exact project-scoped ID verified by a trusted backend. Preserve case, whitespace and Unicode. It is not a credential and never links accounts across projects." } }, "additionalProperties": false, "type": "object", "required": [ "title" ], "title": "Submission" }, "Summary": { "properties": { "protocol": { "$ref": "#/components/schemas/Protocol" }, "app_instance_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "App Instance Id" }, "observed_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Observed At" }, "interval": { "$ref": "#/components/schemas/Range" }, "total_accounts": { "$ref": "#/components/schemas/Metric" }, "new_accounts": { "$ref": "#/components/schemas/NewAccounts" } }, "type": "object", "required": [ "protocol", "app_instance_id", "observed_at", "interval", "total_accounts", "new_accounts" ], "title": "Summary" }, "SummaryRead": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "query": { "$ref": "#/components/schemas/Range" } }, "additionalProperties": false, "type": "object", "required": [ "version", "query" ], "title": "SummaryRead" }, "SupportModeInput": { "properties": { "mode": { "type": "string", "enum": [ "ai", "waiting_human", "human" ], "title": "Mode" }, "mode_version": { "type": "integer", "minimum": 1.0, "title": "Mode Version", "description": "Current support-mode version; independent of the conversation version. A stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "mode", "mode_version" ], "title": "SupportModeInput" }, "TestOutput": { "properties": { "event_id": { "type": "string", "title": "Event Id" } }, "type": "object", "required": [ "event_id" ], "title": "TestOutput" }, "TicketInput": { "properties": { "conversation_id": { "type": "string", "format": "uuid", "title": "Conversation Id" } }, "additionalProperties": false, "type": "object", "required": [ "conversation_id" ], "title": "TicketInput" }, "TicketOutput": { "properties": { "ticket": { "type": "string", "title": "Ticket" }, "expires_at": { "type": "string", "title": "Expires At" } }, "type": "object", "required": [ "ticket", "expires_at" ], "title": "TicketOutput" }, "TopicOutput": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "policy": { "$ref": "#/components/schemas/TopicPolicy" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "keys": { "items": { "$ref": "#/components/schemas/DecisionKeyOutput" }, "type": "array", "title": "Keys" }, "preset_version": { "type": "string", "title": "Preset Version" }, "maximum_keys": { "type": "integer", "title": "Maximum Keys" } }, "type": "object", "required": [ "project_id", "version", "policy", "updated_at", "keys", "preset_version", "maximum_keys" ], "title": "TopicOutput" }, "TopicPolicy": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "provider": { "type": "string", "enum": [ "kodekey", "cloudflare" ], "maxLength": 64, "minLength": 1, "title": "Provider" }, "model": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Model" }, "scope": { "type": "string", "maxLength": 4000, "title": "Scope" }, "public_summary": { "type": "string", "maxLength": 240, "title": "Public Summary" }, "allowed_examples": { "items": { "type": "string" }, "type": "array", "maxItems": 10, "title": "Allowed Examples" }, "disallowed_examples": { "items": { "type": "string" }, "type": "array", "maxItems": 10, "title": "Disallowed Examples" }, "preset": { "type": "string", "enum": [ "balanced", "strict" ], "title": "Preset" }, "refusal_messages": { "items": { "type": "string" }, "type": "array", "maxItems": 5, "title": "Refusal Messages" } }, "additionalProperties": false, "type": "object", "required": [ "enabled", "provider", "model", "scope", "public_summary", "allowed_examples", "disallowed_examples", "preset", "refusal_messages" ], "title": "TopicPolicy" }, "TopicWrite": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "policy": { "$ref": "#/components/schemas/TopicPolicy" } }, "additionalProperties": false, "type": "object", "required": [ "version", "policy" ], "title": "TopicWrite" }, "User": { "properties": { "id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Id" }, "display_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Display Name" }, "email": { "anyOf": [ { "type": "string", "maxLength": 320 }, { "type": "null" } ], "title": "Email" }, "phone_number": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Phone Number" }, "joined_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Joined At" }, "status": { "type": "string", "enum": [ "active", "disabled", "unknown" ], "title": "Status", "default": "unknown" }, "plan": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Plan" }, "last_active_at": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$" }, { "type": "null" } ], "title": "Last Active At" } }, "type": "object", "required": [ "id", "joined_at" ], "title": "User" }, "UserOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "role": { "type": "string", "enum": [ "participant", "admin" ], "title": "Role" } }, "type": "object", "required": [ "id", "role" ], "title": "UserOutput" }, "UserPage": { "properties": { "protocol": { "$ref": "#/components/schemas/Protocol" }, "app_instance_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "App Instance Id" }, "observed_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Observed At" }, "items": { "items": { "$ref": "#/components/schemas/User" }, "type": "array", "maxItems": 100, "title": "Items" }, "scan_until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Scan Until" }, "expires_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Expires At" }, "next_cursor": { "anyOf": [ { "type": "string", "maxLength": 8192, "minLength": 1 }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "protocol", "app_instance_id", "observed_at", "items", "scan_until", "expires_at", "next_cursor" ], "title": "UserPage" }, "UserQuery": { "properties": { "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "default": 50 }, "query": { "type": "string", "maxLength": 200, "title": "Query", "default": "" }, "joined": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ] }, "cursor": { "anyOf": [ { "type": "string", "maxLength": 8192, "minLength": 1 }, { "type": "null" } ], "title": "Cursor", "description": "Leave unset when calling SupaKnock. Send the outer continuation from the previous response instead; raw upstream cursors are rejected." } }, "additionalProperties": false, "type": "object", "title": "UserQuery" }, "UserRead": { "properties": { "version": { "type": "integer", "minimum": 0.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "query": { "$ref": "#/components/schemas/UserQuery" }, "continuation": { "anyOf": [ { "type": "string", "maxLength": 16384, "minLength": 1 }, { "type": "null" } ], "title": "Continuation", "description": "Opaque outer continuation returned by the previous SupaKnock response. Keep the query and connection version unchanged; expired or changed sessions return 409." } }, "additionalProperties": false, "type": "object", "required": [ "version", "query" ], "title": "UserRead" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifiedModel": { "properties": { "role": { "type": "string", "enum": [ "generation", "decision" ], "title": "Role" }, "model": { "type": "string", "title": "Model" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" } }, "type": "object", "required": [ "role", "model", "capabilities" ], "title": "VerifiedModel" }, "VersionInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "version" ], "title": "VersionInput" }, "VisitorSessionOutput": { "properties": { "token": { "type": "string", "title": "Token" }, "expires_at": { "type": "string", "title": "Expires At" }, "conversation": { "$ref": "#/components/schemas/ConversationOutput" } }, "type": "object", "required": [ "token", "expires_at", "conversation" ], "title": "VisitorSessionOutput" }, "Vote": { "properties": { "present": { "type": "boolean", "title": "Present" }, "external_user_id": { "anyOf": [ { "type": "string", "maxLength": 512, "minLength": 1 }, { "type": "null" } ], "title": "External User Id", "description": "Exact project-scoped ID verified by a trusted backend. Preserve case, whitespace and Unicode. It is not a credential and never links accounts across projects." } }, "additionalProperties": false, "type": "object", "required": [ "present" ], "title": "Vote" }, "VoteOutput": { "properties": { "vote_count": { "type": "integer", "title": "Vote Count" }, "voted": { "type": "boolean", "title": "Voted" } }, "type": "object", "required": [ "vote_count", "voted" ], "title": "VoteOutput" }, "WebhookInput": { "properties": { "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Url" }, "enabled": { "type": "boolean", "title": "Enabled" }, "events": { "items": { "type": "string", "enum": [ "request.created", "request.updated", "request.resubmitted", "request.accepted", "request.rejected", "request.status_changed", "request.deleted", "chat.message_created" ] }, "type": "array", "maxItems": 8, "title": "Events", "description": "Explicit subscription allowlist. chat.support_mode_changed is an internal event but is not currently accepted by this v1 settings endpoint." }, "rotate_secret": { "type": "boolean", "title": "Rotate Secret", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "version", "enabled", "events" ], "title": "WebhookInput" }, "WebhookOutput": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "enabled": { "type": "boolean", "title": "Enabled" }, "events": { "items": { "type": "string" }, "type": "array", "title": "Events" }, "has_secret": { "type": "boolean", "title": "Has Secret" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret" } }, "type": "object", "required": [ "url", "enabled", "events", "has_secret", "version" ], "title": "WebhookOutput" }, "WebsiteImportOutput": { "properties": { "source": { "$ref": "#/components/schemas/KnowledgeSourceOutput" }, "run": { "$ref": "#/components/schemas/CrawlRunDetailOutput" } }, "type": "object", "required": [ "source", "run" ], "title": "WebsiteImportOutput" }, "WebsiteInput": { "properties": { "client_import_id": { "type": "string", "format": "uuid", "title": "Client Import Id" }, "name": { "type": "string", "maxLength": 300, "minLength": 1, "title": "Name" }, "config": { "$ref": "#/components/schemas/CrawlConfigInput" } }, "additionalProperties": false, "type": "object", "required": [ "client_import_id", "name", "config" ], "title": "WebsiteInput" }, "WebsiteReplacementInput": { "properties": { "client_import_id": { "type": "string", "format": "uuid", "title": "Client Import Id" }, "name": { "type": "string", "maxLength": 300, "minLength": 1, "title": "Name" }, "config": { "$ref": "#/components/schemas/CrawlConfigInput" }, "version": { "type": "integer", "minimum": 1.0, "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "client_import_id", "name", "config", "version" ], "title": "WebsiteReplacementInput" }, "WeeklyHours": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "default": false }, "timezone": { "type": "string", "maxLength": 100, "title": "Timezone", "default": "UTC" }, "days": { "items": { "items": { "$ref": "#/components/schemas/Interval" }, "type": "array" }, "type": "array", "maxItems": 7, "minItems": 7, "title": "Days" }, "collect_email": { "type": "boolean", "title": "Collect Email", "default": false } }, "additionalProperties": false, "type": "object", "title": "WeeklyHours" }, "feedback__ai_reports_api__BoardOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "BoardOutput" }, "feedback__outputs__BoardOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "identifier": { "type": "string", "title": "Identifier" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "version": { "type": "integer", "title": "Version", "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Archived At" }, "project_id": { "type": "string", "title": "Project Id" }, "project_archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Archived At" } }, "type": "object", "required": [ "id", "identifier", "name", "description", "created_at", "updated_at", "version", "project_id" ], "title": "BoardOutput" }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Safe explanation for the caller; never a raw internal exception." }, "fields": { "type": "array", "description": "Optional validation issues; rejected values are not echoed.", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "HealthOutput": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "ConnectedConnectionOutput": { "type": "object", "required": [ "project_id", "project_name", "version", "connection_id", "base_url", "has_token", "enabled", "app_instance_id", "link_origins", "support_linked" ], "properties": { "project_id": { "type": "string" }, "project_name": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "description": "Optimistic concurrency version; zero before configuration." }, "connection_id": { "type": [ "string", "null" ] }, "base_url": { "type": [ "string", "null" ] }, "has_token": { "type": "boolean" }, "enabled": { "type": "boolean" }, "app_instance_id": { "type": [ "string", "null" ] }, "link_origins": { "type": "array", "items": { "type": "string" } }, "support_linked": { "type": "boolean" } } }, "ConnectedConnectionListOutput": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectedConnectionOutput" } } } }, "ConnectedPreferencesOutput": { "type": "object", "required": [ "version", "timezone" ], "properties": { "version": { "type": "integer", "minimum": 0, "description": "Version of this resource or configuration. On writes, send the current value from its latest read; a stale value returns 409." }, "timezone": { "type": "string", "description": "IANA display timezone, such as America/Chicago." } } }, "Capabilities": { "properties": { "summary": { "default": false, "title": "Summary", "type": "boolean" }, "users": { "default": false, "title": "Users", "type": "boolean" }, "profiles": { "default": false, "title": "Profiles", "type": "boolean" }, "activity": { "default": false, "title": "Activity", "type": "boolean" }, "user_activity": { "default": false, "title": "User Activity", "type": "boolean" } }, "title": "Capabilities", "type": "object" }, "ConnectedManifest": { "properties": { "protocol": { "$ref": "#/components/schemas/Protocol" }, "app_instance_id": { "maxLength": 512, "minLength": 1, "title": "App Instance Id", "type": "string" }, "observed_at": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$", "title": "Observed At", "type": "string" }, "capabilities": { "$ref": "#/components/schemas/Capabilities" }, "user_filters": { "default": [], "items": { "enum": [ "query", "joined_range" ], "type": "string" }, "maxItems": 2, "title": "User Filters", "type": "array" }, "link_origins": { "default": [], "items": { "type": "string" }, "maxItems": 8, "title": "Link Origins", "type": "array" }, "activity_history": { "anyOf": [ { "$ref": "#/components/schemas/Coverage" }, { "type": "null" } ], "default": null }, "activity_definition": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Activity Definition" } }, "required": [ "protocol", "app_instance_id", "observed_at", "capabilities" ], "title": "Manifest", "type": "object" }, "ConnectedTestOutput": { "type": "object", "required": [ "manifest", "receipt" ], "properties": { "manifest": { "$ref": "#/components/schemas/ConnectedManifest" }, "receipt": { "type": "string", "description": "Opaque review receipt; expires in five minutes. Never edit it." } } }, "ConnectedRelatedOutput": { "type": "object", "required": [ "linked", "requests", "conversations", "has_more" ], "properties": { "linked": { "type": "boolean" }, "requests": { "type": "array", "items": { "type": "object", "required": [ "id", "created_at", "title" ], "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "title": { "type": "string" } } } }, "conversations": { "type": "array", "items": { "type": "object", "required": [ "id", "created_at" ], "properties": { "id": { "type": "string" }, "created_at": { "type": "string" } } } }, "has_more": { "type": "boolean" } } }, "ChatMessageCreatedEvent": { "oneOf": [ { "$ref": "#/components/schemas/ChatHumanMessageCreatedEvent" }, { "$ref": "#/components/schemas/ChatAIMessageCreatedEvent" } ] }, "ChatHumanMessageCreatedEvent": { "type": "object", "required": [ "id", "type", "schema_version", "occurred_at", "project", "conversation", "message", "customer", "actor" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "chat.message_created" }, "schema_version": { "const": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "project": { "type": "object", "required": [ "id", "identifier" ], "properties": { "id": { "type": "string" }, "identifier": { "type": "string" } } }, "conversation": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "message": { "type": "object", "required": [ "id", "sequence", "sender_role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer", "minimum": 1 }, "sender_role": { "enum": [ "customer", "admin" ] } } }, "customer": { "$ref": "#/components/schemas/CustomerOutput" }, "actor": { "type": "object", "required": [ "kind", "user_id" ], "properties": { "kind": { "enum": [ "customer", "admin" ] }, "user_id": { "type": [ "string", "null" ] } } } } }, "ChatAIMessageCreatedEvent": { "type": "object", "required": [ "id", "type", "schema_version", "occurred_at", "project", "conversation", "message", "actor" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "chat.message_created" }, "schema_version": { "const": 2 }, "occurred_at": { "type": "string", "format": "date-time" }, "project": { "type": "object", "required": [ "id", "identifier" ], "properties": { "id": { "type": "string" }, "identifier": { "type": "string" } } }, "conversation": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "message": { "type": "object", "required": [ "id", "sequence", "sender_role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer", "minimum": 1 }, "sender_role": { "const": "ai" } } }, "actor": { "type": "object", "required": [ "kind", "user_id" ], "properties": { "kind": { "const": "ai" }, "user_id": { "type": "null" } } } } }, "ChatSupportModeChangedEvent": { "type": "object", "required": [ "id", "type", "schema_version", "occurred_at", "project", "conversation", "previous_mode", "reason", "actor" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "chat.support_mode_changed" }, "schema_version": { "const": 2 }, "occurred_at": { "type": "string", "format": "date-time" }, "project": { "type": "object", "required": [ "id", "identifier" ], "properties": { "id": { "type": "string" }, "identifier": { "type": "string" } } }, "conversation": { "type": "object", "required": [ "id", "support_mode", "mode_version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "support_mode": { "enum": [ "ai", "waiting_human", "human" ] }, "mode_version": { "type": "integer", "minimum": 1 } } }, "previous_mode": { "enum": [ "ai", "waiting_human", "human" ] }, "reason": { "type": "string" }, "actor": { "type": "object", "required": [ "kind", "user_id" ], "properties": { "kind": { "enum": [ "admin", "customer", "system", "ai" ] }, "user_id": { "type": [ "string", "null" ] } } } } }, "RequestWebhookEvent": { "type": "object", "required": [ "id", "type", "schema_version", "occurred_at", "project", "board", "request_id", "url", "request", "previous", "actor", "creator" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "request.created", "request.updated", "request.resubmitted", "request.accepted", "request.rejected", "request.status_changed", "request.deleted" ] }, "schema_version": { "const": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "project": { "type": "object", "required": [ "id", "identifier" ], "properties": { "id": { "type": "string" }, "identifier": { "type": "string" } } }, "board": { "type": "object", "required": [ "id", "identifier" ], "properties": { "id": { "type": "string" }, "identifier": { "type": "string" } } }, "request_id": { "type": "string" }, "url": { "type": "string" }, "request": { "type": "object", "required": [ "id", "title", "description", "moderation", "status", "accepted_at", "rejection_reason", "version" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "moderation": { "enum": [ "pending", "accepted", "rejected" ] }, "status": { "enum": [ "under_consideration", "planned", "in_progress", "shipped" ] }, "accepted_at": { "type": [ "string", "null" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "version": { "type": "integer", "minimum": 1 } } }, "previous": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Changed fields from the previous request state, or null for a new request. The field set depends on the event type." }, "actor": { "type": "object", "required": [ "user_id", "api_key_id", "kind" ], "properties": { "user_id": { "type": [ "string", "null" ] }, "api_key_id": { "type": [ "string", "null" ] }, "kind": { "enum": [ "native", "integration" ] } } }, "creator": { "type": "object", "required": [ "user_id", "external_user_id" ], "properties": { "user_id": { "type": "string" }, "external_user_id": { "type": [ "string", "null" ] } } } } }, "WebhookTestEvent": { "type": "object", "required": [ "id", "type", "schema_version", "occurred_at", "project", "actor", "test" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "webhook.test" }, "schema_version": { "const": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "project": { "type": "object", "required": [ "id", "identifier" ], "properties": { "id": { "type": "string" }, "identifier": { "type": "string" } } }, "actor": { "type": "object", "required": [ "user_id", "api_key_id", "kind" ], "properties": { "user_id": { "type": [ "string", "null" ] }, "api_key_id": { "type": [ "string", "null" ] }, "kind": { "enum": [ "native", "integration" ] } } }, "test": { "const": true } } }, "ChatSocketHello": { "type": "object", "required": [ "ticket" ], "properties": { "ticket": { "type": "string", "description": "Single-use ct_ ticket from POST /api/v1/chat/tickets." }, "after": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 0, "description": "Highest committed message sequence already received for this conversation." } } }, "ChatSocketClientFrame": { "oneOf": [ { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "const": "message" }, "message": { "type": "object", "required": [ "client_message_id", "body" ], "properties": { "client_message_id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 } } } } }, { "type": "object", "required": [ "type", "sequence" ], "properties": { "type": { "const": "read" }, "sequence": { "type": "integer", "minimum": 0, "maximum": 2147483647 } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "typing" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "pong" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "ping" } } } ] }, "ChatSocketServerFrame": { "oneOf": [ { "type": "object", "required": [ "type", "conversation_id" ], "properties": { "type": { "const": "ready" }, "conversation_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "type", "conversation" ], "properties": { "type": { "const": "state" }, "conversation": { "$ref": "#/components/schemas/ConversationOutput" } } }, { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "const": "message" }, "message": { "$ref": "#/components/schemas/MessageOutput" } } }, { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "const": "ack" }, "message": { "$ref": "#/components/schemas/MessageOutput" } } }, { "type": "object", "required": [ "type", "sender", "sender_role" ], "properties": { "type": { "const": "typing" }, "sender": { "enum": [ "visitor", "admin" ] }, "sender_role": { "enum": [ "customer", "admin" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "ping" } } }, { "type": "object", "required": [ "type", "error" ], "properties": { "type": { "const": "error" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Safe explanation for the caller; never a raw internal exception." }, "fields": { "type": "array", "description": "Optional validation issues; rejected values are not echoed.", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } ] } }, "securitySchemes": { "APIKeyCookie": { "type": "apiKey", "in": "cookie", "name": "feedback_session", "description": "Local account browser session. The account role still controls access: participant cookies do not satisfy administrator operations. Mutations also require the exact installation Origin and X-CSRF-Token." }, "NativeBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "ns_\u2026", "description": "Administrator session issued by POST /api/v1/auth/native/login. Send Authorization: Bearer ns_\u2026. Do not combine with a session cookie or chat token; no CSRF token is needed." }, "ProjectBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "fb_\u2026", "description": "Trusted backend project credential. Send Authorization: Bearer fb_\u2026. Permissions and project scope apply per operation. Never embed this secret in browser or mobile code; external_user_id is not an authentication mechanism." }, "ChatVisitor": { "type": "apiKey", "in": "header", "name": "X-Chat-Token", "description": "Secret cv_ visitor credential for one conversation and its exact website Origin. Never combine with cookies or Authorization." }, "ChatCustomer": { "type": "apiKey", "in": "header", "name": "X-Chat-Token", "description": "One-hour cc_ credential for a durable customer and project. Browser credentials require their bound Origin; native credentials omit Origin. Never combine with cookies or Authorization." } } }, "servers": [ { "url": "/", "description": "This SupaKnock installation; use its PUBLIC_BASE_URL as your client base URL." } ], "webhooks": { "chat.message_created": { "post": { "summary": "A customer, administrator or AI message was committed", "description": "Opt in through project webhook settings. Signed raw JSON using X-Feedback-Timestamp, X-Feedback-Signature and X-Feedback-Event-ID. At least once; delivery ordering is not guaranteed. Customer/admin events retain schema_version 1 and customer identity. AI events use schema_version 2, sender_role ai and no customer identity. Filter sender_role=admin for human replies; AI messages never count as human response time. Bodies and citations remain behind authenticated chat APIs. Deduplicate the stable event ID and use conversation sequence for history. See docs/chat.md and docs/webhooks.md. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessageCreatedEvent" }, "example": { "id": "d4bfa680-c7e5-4479-b4cd-e1d6a10c066e", "type": "chat.message_created", "schema_version": 1, "occurred_at": "2026-10-03T01:00:00.000Z", "project": { "id": "9dc2e44e-3c3a-4d69-a55b-e57c36a839bc", "identifier": "my-app" }, "conversation": { "id": "504f92da-bbaa-4d31-b0c1-631d315a01cb" }, "message": { "id": "d4bfa680-c7e5-4479-b4cd-e1d6a10c066e", "sequence": 2, "sender_role": "admin" }, "customer": { "id": "e7e792e7-d8c1-451c-bc85-6f8a46e5d77b", "kind": "external", "display_name": "Jordan", "user_id": "2ee560d1-1b14-4472-b5d7-c3f07edec7b3", "external_user_id": "app-user-123" }, "actor": { "kind": "admin", "user_id": "9b6ad65e-93c4-4ebe-b0e5-1f3c6fa743cc" } } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "chat.support_mode_changed": { "post": { "summary": "A conversation explicitly changed between AI and human support", "description": "Internal event schema for a committed support-mode transition. This event is not currently selectable in the v1 webhook settings events allowlist, so new subscriptions cannot be configured through this API. Schema version 2 excludes message bodies, customer identity, credentials and IP metadata. mode_version identifies the transition order.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSupportModeChangedEvent" } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": false, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "request.created": { "post": { "summary": "A request was submitted for moderation", "description": "Opt in through project webhook settings. This private event contains the creator identity and a committed request snapshot; do not serve it publicly. Business changes, immutable events and subscribed delivery jobs commit together. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestWebhookEvent" }, { "type": "object", "properties": { "type": { "const": "request.created" } } } ] } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "request.updated": { "post": { "summary": "Request content was edited", "description": "Opt in through project webhook settings. This private event contains the creator identity and a committed request snapshot; do not serve it publicly. Business changes, immutable events and subscribed delivery jobs commit together. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestWebhookEvent" }, { "type": "object", "properties": { "type": { "const": "request.updated" } } } ] } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "request.resubmitted": { "post": { "summary": "A rejected request was edited and resubmitted", "description": "Opt in through project webhook settings. This private event contains the creator identity and a committed request snapshot; do not serve it publicly. Business changes, immutable events and subscribed delivery jobs commit together. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestWebhookEvent" }, { "type": "object", "properties": { "type": { "const": "request.resubmitted" } } } ] } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "request.accepted": { "post": { "summary": "A request was accepted", "description": "Opt in through project webhook settings. This private event contains the creator identity and a committed request snapshot; do not serve it publicly. Business changes, immutable events and subscribed delivery jobs commit together. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestWebhookEvent" }, { "type": "object", "properties": { "type": { "const": "request.accepted" } } } ] } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "request.rejected": { "post": { "summary": "A request was rejected", "description": "Opt in through project webhook settings. This private event contains the creator identity and a committed request snapshot; do not serve it publicly. Business changes, immutable events and subscribed delivery jobs commit together. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestWebhookEvent" }, { "type": "object", "properties": { "type": { "const": "request.rejected" } } } ] } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "request.status_changed": { "post": { "summary": "A request changed lifecycle status", "description": "Opt in through project webhook settings. This private event contains the creator identity and a committed request snapshot; do not serve it publicly. Business changes, immutable events and subscribed delivery jobs commit together. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestWebhookEvent" }, { "type": "object", "properties": { "type": { "const": "request.status_changed" } } } ] } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "request.deleted": { "post": { "summary": "A creator deleted a request before acceptance", "description": "Opt in through project webhook settings. This private event contains the creator identity and a committed request snapshot; do not serve it publicly. Business changes, immutable events and subscribed delivery jobs commit together. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RequestWebhookEvent" }, { "type": "object", "properties": { "type": { "const": "request.deleted" } } } ] } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": true, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } }, "webhook.test": { "post": { "summary": "An administrator or manager requested a test delivery", "description": "Sent only by POST /api/v1/projects/{project}/webhook/test, to the configured destination. It is not a subscription event. Verify X-Feedback-Signature as v1= followed by the hexadecimal HMAC-SHA256 of X-Feedback-Timestamp + \".\" + the exact raw UTF-8 request body, using the webhook signing secret. X-Feedback-Timestamp is Unix seconds. Deduplicate by X-Feedback-Event-ID. Delivery is at least once and ordering is not guaranteed. Any 2xx response acknowledges delivery. Redirects are not followed; network failures, 408, 425, 429 and 5xx retry with bounded backoff (eight attempts including the first). Existing jobs retain their destination, payload and signing-secret snapshot. Manual retry uses that same saved event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestEvent" } } } }, "responses": { "200": { "description": "Accepted or already processed" }, "204": { "description": "Accepted or already processed" } }, "x-subscribable": false, "parameters": [ { "in": "header", "name": "X-Feedback-Event-ID", "required": true, "schema": { "type": "string" }, "description": "Stable event UUID; deduplicate deliveries by this ID." }, { "in": "header", "name": "X-Feedback-Timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix seconds used to sign this delivery attempt." }, { "in": "header", "name": "X-Feedback-Signature", "required": true, "schema": { "type": "string" }, "description": "v1= followed by the lowercase hexadecimal HMAC-SHA256 signature." } ] } } }, "x-websockets": { "/api/v1/chat/ws": { "summary": "Resume live messages for one authorized conversation", "description": "Use wss with an HTTPS installation. Obtain a fresh ticket over authenticated HTTP, open the socket without URL query parameters, and send the hello frame within five seconds. Browser credentials require their bound Origin; native customer credentials omit Origin. Authentication comes from the ticket, not cookies or URL credentials. After ready, state describes the current conversation and message frames replay committed messages after your cursor. On reconnect, obtain another ticket and send your highest received sequence. Deduplicate message and ack frames by message ID. Authorization and ownership are rechecked throughout the connection. HTTP remains available for all durable operations. Save optional follow_up_email through HTTP message creation; WebSocket message frames do not save contact details.", "ticketOperation": "POST /api/v1/chat/tickets", "hello": { "$ref": "#/components/schemas/ChatSocketHello" }, "clientFrames": { "$ref": "#/components/schemas/ChatSocketClientFrame" }, "serverFrames": { "$ref": "#/components/schemas/ChatSocketServerFrame" }, "limits": { "ticketLifetimeSeconds": 60, "helloTimeoutSeconds": 5, "maxFrameBytes": 32768, "maxFramesPerMinute": 120, "maxConnectionsPerSession": 8, "maxConnectionsPerInstallation": 128, "typingIntervalSeconds": 2, "serverPingIntervalSeconds": 20 }, "closeCodes": { "1013": "Installation connection capacity reached; try again later.", "4403": "Rejected before acceptance: URL query parameters or an invalid Origin.", "4401": "Credentials expired, were revoked, or no longer authorize this conversation.", "4400": "Invalid input, frame limit, per-session connection limit or another protocol error." } } } }