@standchat/cli 0.1.1 → 0.1.2

package/dist/openapi.json

@@ -1 +1 @@
-{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Stand public API","version":"0.1.0","description":"Scoped API and CLI access to supported Stand account operations. Complete initial signup and profile onboarding in the browser. Current account, organization, role, ownership and plan permissions still apply. Account deletion, subscription management, team-member changes, JavaScript experimentation opt-in, MCP and WordPress/site connections are excluded."},"externalDocs":{"description":"Public API and CLI guide","url":"https://stand.chat/guide/api-cli.md"},"servers":[{"url":"https://api.stand.chat","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/reps/me":{"get":{"operationId":"getCurrentUser","summary":"Get the authenticated identity","description":"Get the authenticated identity","tags":["Account and organization"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/reps/profile":{"get":{"operationId":"getRepProfile","summary":"Get your representative profile","description":"Get your representative profile","tags":["Account and organization"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepProfileResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"updateRepProfile","summary":"Save your representative profile","description":"Update an already-completed profile using the approved complete personal details. Initial profile completion and organization creation require the existing browser onboarding. Read the current profile and preserve unrelated fields: omitted title, organization, avatarUrl and greeting clear those profile values, and omitted greetingEnabled defaults to true. Changing the organization name additionally requires org:write and organization ownership; retain the current organization value when only editing personal details. Current membership and ownership rules still apply.","tags":["Account and organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepProfileUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepProfileResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/sites":{"get":{"operationId":"listSites","summary":"List sites in your organization","description":"List Sites in the current organization, including installation snippets and whether the caller is the owner. Active organization members can read this list.","tags":["Sites"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]},"post":{"operationId":"createSite","summary":"Add a site to your organization","description":"Any active organization member can add a site. Setting either experimentation consent switch true also requires organization ownership; external clients cannot enable either switch even as owner. Returns 200. Response includes installation HTML containing the public site ID, never a user credential. External clients must create the Site with advancedBehaviorEnabled and allowStandAdminBehavior false (or omit behaviorConfig); an owner request with either switch true returns 403 EXPERIMENTATION_CONSENT_REQUIRED before creation, while other callers remain subject to ownership checks. Stored script source remains inert until owner enablement in the dashboard.","tags":["Sites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCreate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/sites/{siteId}":{"put":{"operationId":"updateSite","summary":"Update site settings","description":"Owner only. enabled, name and defaultLanguageCode change only when supplied. A supplied behaviorConfig replaces the entire configuration, including all rules. Legacy compatibility input. On update, any supplied embedOptions object, including embedOptions: {}, merges supplied keys into the saved legacy options and then replaces behaviorConfig: advancedBehaviorEnabled and allowStandAdminBehavior become false, and all existing rules, including custom JavaScript rules, are replaced by zero or one legacy-default rule derived from the merged options. An explicit behaviorConfig in the same request is applied after this conversion and controls the final configuration. Owner-consent validation uses the committed configuration before any sibling mutation; all fields are validated before saving. For behavior edits, modern clients should read the Site and replace the complete behaviorConfig with both switches and every retained rule. At least one recognized setting is required. A null or blank defaultLanguageCode resets the fallback language. External API/CLI clients cannot enable experimentation: advancedBehaviorEnabled may remain true only when it is already enabled for that Site. The organization owner enables it in the Stand dashboard under Sites > Chat widget behavior > Experimentation (Advanced), after accepting the warning. Once enabled, owner-authorized OAuth clients with sites:write may add, edit and activate custom JavaScript rules. Disabling it strips custom JavaScript from subsequent visitor behavior responses; stored source can be retained or edited while disabled but cannot execute. API clients may disable it but cannot re-enable it, even with an unconditional configuration replacement. They also cannot grant Stand-admin experimentation access. A denied enablement returns 403 EXPERIMENTATION_CONSENT_REQUIRED with no sibling changes. Reload the Site after the owner changes consent; broader scopes or another login cannot enable it.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteSite","summary":"Delete a site","description":"Delete a site","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]},"get":{"operationId":"getSite","summary":"Read one site in your organization","description":"Active members of its organization can read it. Missing and foreign Sites return the same 404 NOT_FOUND.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]}},"/v1/sites/matches":{"get":{"operationId":"listSiteMatches","summary":"List eligible responders by site","description":"Read current representative and Stand-in routing matches for Sites in the current organization. This is configuration and availability evidence, not a completed visitor chat.","tags":["Sites"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMatches"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]}},"/v1/reps/profile/sites":{"get":{"operationId":"getRepSitePreferences","summary":"Get your chat-site selection","description":"Read your complete personal chat-site selection. siteIds null means all Sites; an explicit list selects those Sites. Both full-set replacement and a one-Site update are supported.","tags":["Sites"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"setRepSitePreferences","summary":"Replace your chat-site selection","description":"Replace your chat-site selection","tags":["Sites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferencesUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/reps/profile/sites/{siteId}":{"put":{"operationId":"setRepSitePreference","summary":"Change your chat selection for one site","description":"Changes only the named site in your personal chat selection, preserving the other sites. If never configured (siteIds null), starts from all current organization sites. The returned siteIds is the complete explicit selection; [] selects no sites. Foreign or missing site IDs return 404.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/sites/{siteId}/prompt":{"get":{"operationId":"getSitePrompt","summary":"Get the active site prompt","description":"Read the active prompt for a Site in your organization; organization members can read it.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"anyOf":[{"$ref":"#/components/schemas/SitePrompt"},{"type":"null"}]}},"required":["prompt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateSitePrompt","summary":"Replace the site prompt","description":"Replace the prompt for a Site in your organization. Requires the organization owner.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePrompt"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteSitePrompt","summary":"Clear the site prompt","description":"Clear the active prompt for a Site in your organization. Requires the organization owner.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/sites/{siteId}/prompt/history":{"get":{"operationId":"listSitePromptHistory","summary":"List site prompt revisions","description":"Existing account API value.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"type":"array","items":{"$ref":"#/components/schemas/SitePrompt"}}},"required":["prompts"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]}},"/v1/orgs/{orgId}/prompt":{"get":{"operationId":"getOrganizationPrompt","summary":"Get the active organization prompt","description":"Get the active organization prompt","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"anyOf":[{"$ref":"#/components/schemas/OrgPrompt"},{"type":"null"}]}},"required":["prompt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateOrganizationPrompt","summary":"Replace the organization prompt","description":"Replace the organization prompt","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrompt"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteOrganizationPrompt","summary":"Clear the organization prompt","description":"Clear the organization prompt","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/orgs/{orgId}/prompt/history":{"get":{"operationId":"listOrganizationPromptHistory","summary":"List organization prompt revisions","description":"Existing account API value.","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"type":"array","items":{"$ref":"#/components/schemas/OrgPrompt"}}},"required":["prompts"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/orgs/{orgId}/privacy-settings":{"get":{"operationId":"getOrganizationPrivacy","summary":"Get organization privacy settings","description":"Get organization privacy settings","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrivacy"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateOrganizationPrivacy","summary":"Save organization privacy settings","description":"Save organization privacy settings","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrivacyUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrivacy"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/archived":{"get":{"operationId":"listArchivedSessions","summary":"Search archived conversations","description":"Conversations visible to the authenticated rep. sites and labels filter metadata are populated only on page zero. Test conversations are excluded. Pagination is offset-based; concurrent changes can shift results.","tags":["Conversations"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based page. page × size must not exceed 2147483647."},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["all","rep","agent"],"default":"all"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["myself","org"],"default":"myself"},"description":"Organization scope is honored only for an owner; otherwise effective scope is myself."},{"name":"site","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal substring of the stored page URL, not a site ID or exact-hostname match. A hostname can also match text elsewhere in a URL. Blank values apply no filter; inspect returned page URLs when an exact-site corpus is needed."},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","default":"closedAt"},"description":"closedAt, createdAt, page, or messageCount. Unknown values fall back to closedAt."},{"name":"sortDir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"contact","in":"query","required":false,"schema":{"type":"string","enum":["all","email","phone","any"],"default":"all"}},{"name":"label","in":"query","required":false,"schema":{"type":"string","default":"all"},"description":"Label ID or all."},{"name":"closedFrom","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant or UTC calendar date; inclusive lower bound."},{"name":"closedTo","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant (exclusive), or UTC date including the whole specified day."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal search. Leading and trailing U+0000 through U+0020 code units are removed, then the query must contain at most 200 UTF-16 code units; a supplementary Unicode character such as an emoji counts as two. An empty normalized query applies no text filter. An over-limit normalized query returns 400 BAD_REQUEST. The limit applies after normalization and is not a raw JSON Schema maxLength constraint."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchivedSessions"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read","security":[{"bearerAuth":[]}]}},"/v1/sessions":{"get":{"operationId":"listSessions","summary":"List your active conversation IDs","description":"List your active conversation IDs","tags":["Conversations"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveSessions"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/seen":{"put":{"operationId":"markSessionSeen","summary":"Mark an assigned conversation as seen","description":"Mark an assigned conversation as seen","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/messages":{"post":{"operationId":"sendMessage","summary":"Send a conversation message","description":"Requires access to the conversation as an authorized representative. Sending a message can take over a Stand-in conversation. Preserve clientMessageId when retrying this operation; no general Idempotency-Key header is implemented.","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"clientMessageId":{"type":"string","description":"Caller-generated identifier for message replay protection."}},"required":["body"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}],"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write"}},"/v1/reps/me/greeting-variants":{"get":{"operationId":"listGreetingVariants","summary":"List your greeting variants","description":"List your greeting variants","tags":["Account and organization"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/GreetingVariant"}}},"required":["variants"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveGreetingVariants","summary":"Save your greeting variants","description":"At least one retained, nonblank greeting is required. Supply the complete requested variant set.","tags":["Account and organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/GreetingVariantInput"}}},"required":["variants"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/GreetingVariant"}}},"required":["variants"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/team":{"get":{"operationId":"getTeam","summary":"List organization members and pending invitations","description":"All active organization members can list members. Pending invitations are returned only to the owner. Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Team"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"team:read","security":[{"bearerAuth":[]}]}},"/v1/team/invite-provider-default":{"get":{"operationId":"getInviteProviderDefault","summary":"Suggest a required sign-in provider","description":"Returns an owner-specific provider suggestion; nonowners receive null.","tags":["Team"],"parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"requireProvider":{"type":["string","null"]}},"required":["requireProvider"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"team:read","security":[{"bearerAuth":[]}]}},"/v1/digest/preferences":{"get":{"operationId":"getDigestPreferences","summary":"Get email digest preferences","description":"Get email digest preferences","tags":["Digests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateDigestPreferences","summary":"Update email digest preferences","description":"Update email digest preferences","tags":["Digests"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestPreferencesUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:write","security":[{"bearerAuth":[]}]}},"/v1/digest/ai-preferences":{"get":{"operationId":"getDigestAiPreferences","summary":"Get conversation analytics preferences","description":"Get conversation analytics preferences","tags":["Digests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestAiPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateDigestAiPreferences","summary":"Save conversation analytics preferences","description":"Replaces AI preferences and the entire label set. First read getDigestAiPreferences and copy every labelId, name and testPrompt to keep before changing aiEnabled or a label. Omitted/null labels or [] removes all labels; tripwires is a legacy fallback only when labels is absent. The example assumes the retained label belongs to this representative. This is not a partial PATCH.","tags":["Digests"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestAiPreferencesUpdate"}}}},"responses":{"200":{"description":"Saved preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestAiPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Current plan does not permit enabling AI analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:write","security":[{"bearerAuth":[]}]}},"/v1/digest/send-now":{"post":{"operationId":"sendDigestNow","summary":"Email your last seven days of conversations","description":"Sends email to the authenticated representative. A concurrent request returns 409; requests within the 60-second cooldown return 429 RATE_LIMIT_EXCEEDED with Retry-After set to the remaining cooldown, rounded up to whole seconds. Do not automatically retry after an ambiguous failure.","tags":["Digests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"to":{"type":"string"},"period":{"type":"string"}},"required":["sent","to","period"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}":{"get":{"operationId":"getSession","summary":"Get a conversation and recent messages","description":"An active organization owner can read a durable closed conversation in their own organization, including a teammate's conversation. Other representative reads remain assignment-based; this archived-owner read grants no live-session or mutation access. messageLimit defaults to 200, clamps at 500 and accepts zero for no messages. Archived owner reads use retained/redacted durable data and do not supply live AI usage or turn progress. aiTurnProgress on eligible live reads is optional diagnostic data, not a durable completion guarantee.","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"messageLimit","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":200},"description":"Server clamps values above 500. Zero fetches no messages."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetails"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}],"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read"},"delete":{"operationId":"closeSession","summary":"Close a conversation","description":"Closes a session authorized for the caller. The response reports the persisted closing identity, which can differ from this caller after a race.","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"closedBy":{"type":"string"},"closedByType":{"type":"string"},"closedAt":{"type":"string","format":"date-time"}},"required":["sessionId","status","closedBy","closedByType","closedAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}],"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write"}},"/v1/sessions/archived/export":{"get":{"operationId":"exportArchivedSessions","summary":"Export matching archived conversations as JSON","description":"Streams one JSON document, not NDJSON. Membership is frozen for this export. Check failedSessionIds and exportedElements, and reject truncated or invalid JSON even after HTTP 200. Resource admission may reject the request; there is no fixed conversation-count cap.","tags":["Conversations"],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["all","rep","agent"],"default":"all"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["myself","org"],"default":"myself"},"description":"Organization scope is honored only for an owner; otherwise effective scope is myself."},{"name":"site","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal substring of the stored page URL, not a site ID or exact-hostname match. A hostname can also match text elsewhere in a URL. Blank values apply no filter; inspect returned page URLs when an exact-site corpus is needed."},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","default":"closedAt"},"description":"closedAt, createdAt, page, or messageCount. Unknown values fall back to closedAt."},{"name":"sortDir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"contact","in":"query","required":false,"schema":{"type":"string","enum":["all","email","phone","any"],"default":"all"}},{"name":"label","in":"query","required":false,"schema":{"type":"string","default":"all"},"description":"Label ID or all."},{"name":"closedFrom","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant or UTC calendar date; inclusive lower bound."},{"name":"closedTo","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant (exclusive), or UTC date including the whole specified day."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal search. Leading and trailing U+0000 through U+0020 code units are removed, then the query must contain at most 200 UTF-16 code units; a supplementary Unicode character such as an emoji counts as two. An empty normalized query applies no text filter. An over-limit normalized query returns 400 BAD_REQUEST. The limit applies after normalization and is not a raw JSON Schema maxLength constraint."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryExport"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/handoff":{"post":{"operationId":"takeOverSession","summary":"Take over a Stand-in conversation","description":"Take over a Stand-in conversation","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"takenOver":{"type":"boolean"}},"required":["sessionId","takenOver"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/handoff/offer":{"post":{"operationId":"offerSessionHandoff","summary":"Offer to join a Stand-in conversation","description":"Offer to join a Stand-in conversation","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"offered":{"type":"boolean"}},"required":["sessionId","offered"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins":{"get":{"operationId":"listStandins","summary":"List your Stand-ins","description":"List your Stand-ins, including those restricted to a Site and those available across all Sites. Both kinds can be managed with the corresponding write permission.","tags":["Account and organization"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"standins":{"type":"array","items":{"$ref":"#/components/schemas/StandinProfile"}}},"required":["standins"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]},"post":{"operationId":"createStandin","summary":"Create a Stand-in","description":"Creates a new disabled Stand-in. Supply name, displayName and prompt; optional fields use the defaults described in StandinProfileInput. Retain standinProfileId from the response, attach any knowledge or integrations, then enable explicitly.","tags":["Account and organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfileInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}":{"get":{"operationId":"getStandin","summary":"Get your Stand-in","description":"Read one of your Stand-ins, including its current configuration and public identifier.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateStandin","summary":"Update your Stand-in","description":"Replaces profile fields; this is not a partial PATCH. Read getStandin, copy name, displayName, displayBrandName, avatarUrl, greeting, prompt, toolsEnabled, siteId and pathPrefix into the request, then edit the intended values. The schema example also includes the optional question settings. Omitted brand/greeting/site/path fields clear or reset and omitted toolsEnabled resets to the string {}; omitted/null avatarUrl preserves the avatar. Omitted/null starterQuestions and suggestNextQuestions preserve their saved values; [] clears the starter questions and false turns off follow-up questions. Clone and history-preserving version replacement retain both question settings. Enabled state is preserved. If the Stand-in has durable conversation history, the update creates a new version, disables/hides the previous version and returns a different standinProfileId. Always retain the returned ID for subsequent requests; historical conversations keep their original version.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfileInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteStandin","summary":"Delete your Stand-in","description":"Changes an owned Stand-in; current account and resource permissions apply.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/enabled":{"post":{"operationId":"setStandinEnabled","summary":"Enable or disable your Stand-in","description":"Changes an owned Stand-in; current account and resource permissions apply.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/clone":{"post":{"operationId":"cloneStandin","summary":"Clone your Stand-in","description":"Creates a separate disabled copy with a new standinProfileId. The source Stand-in is unchanged. Retain the returned ID, review the copy and enable it explicitly.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Copying the source Stand-in's attached knowledge can be denied by the effective knowledge-base plan, attachment limit or grace state. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases":{"get":{"operationId":"listKnowledgeBases","summary":"List knowledge bases and plan capabilities","description":"List knowledge bases and plan capabilities","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseOverview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]},"post":{"operationId":"createKnowledgeBase","summary":"Create a knowledge base","description":"Create a knowledge base","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseCreate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBase"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan capability unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}":{"put":{"operationId":"updateKnowledgeBase","summary":"Rename a knowledge base","description":"Replaces name and description. First read listKnowledgeBases and copy the current description when renaming; omitted/null/blank description clears it. This is not a partial PATCH.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseUpsert"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBase"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteKnowledgeBase","summary":"Delete a knowledge base","description":"Delete a knowledge base","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"forceDetach","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Detach connected agents before deletion when true."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/connected-agents":{"get":{"operationId":"getKnowledgeBaseAgents","summary":"List agents connected to a knowledge base","description":"List agents connected to a knowledge base","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object","properties":{"standinProfileId":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"}},"required":["standinProfileId","name","displayName"]}}},"required":["agents"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/uploads":{"post":{"operationId":"uploadKnowledgeBaseSource","summary":"Queue a document upload","description":"Requires the knowledge-base owner and an effective upload entitlement. Maximum file size is 10 MiB; the complete multipart request is limited to 12 MiB. Oversized requests return 413. Inspect listKnowledgeBases capabilities and limitsReached before uploading.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"sourceId":{"type":"string","description":"Existing source ID to replace, when supplied."}},"required":["file"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/crawls":{"post":{"operationId":"crawlKnowledgeBase","summary":"Queue a website crawl","description":"Queue a website-prefix crawl using the existing ingestion service. A queued task is not completed ingestion. Retain taskId and sourceId; inspect sources and tasks until indexing completes. Respect returned plan capabilities and limits.","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"The selected page hostname. urlPrefix must use the same normalized domain."},"urlPrefix":{"type":"string","description":"Website URL prefix on the selected domain. Crawling stays within that host and path subtree. Use approved public content; local and private addresses are rejected outside explicitly configured development mode.","minLength":1,"pattern":"\\S"},"maxDepth":{"type":"integer","default":1,"description":"Use 0 to fetch the selected start page without discovering linked pages. Supplied values are clamped to 0 through 10."}},"required":["domain","urlPrefix"],"examples":[{"domain":"example.com","urlPrefix":"https://example.com/help/","maxDepth":0}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan capability unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/sitemaps":{"post":{"operationId":"crawlKnowledgeBaseSitemap","summary":"Queue a sitemap crawl","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sitemapUrl":{"type":"string"},"dailyRefreshEnabled":{"type":"boolean"}},"required":["sitemapUrl"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}],"description":"Start ingestion from an approved public sitemap into an owned knowledge base. Existing plan and crawl limits apply; inspect returned tasks before treating content as ready."}},"/v1/knowledge-bases/{knowledgeBaseId}/sources":{"get":{"operationId":"listKnowledgeBaseSources","summary":"List knowledge sources","description":"Without view, preserves the complete legacy application/json list and fields. Explicit view=inspection selects SQL-bounded metadata with application/vnd.stand.knowledge-inspection+json; Accept must allow that media type (406 otherwise). Inspection parameters require view=inspection. Lists are ordered by immutable createdAt descending and ID descending. Follow nextCursor as after with the same base and filters; malformed or differently bound cursors return 400. Each page rechecks current organization and knowledge-base access. Exact filter IDs outside that base return 404. Historical tasks remain readable after source deletion. complete means this response alone covers the selected list: it is false on every continuation page, including the last. hasMore/nextCursor describe the remaining pages. totalElements is an independent current count, not a snapshot across concurrent changes. Content, raw diagnostics, worker fields and storage paths are omitted. Task effectiveUrl is null for unavailable/deleted source metadata or URLs exceeding 2048 UTF-16 code units.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["inspection"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"after","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"sourceId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, select this exact source in the selected base; foreign or mismatched IDs return 404. A soft-deleted source can still scope retained tasks/documents. Without view, the existing document source filter is unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseSource"}}},"required":["sources"]}},"application/vnd.stand.knowledge-inspection+json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"status":{"type":"string"},"sourceType":{"type":"string"},"displayName":{"type":"string"},"pageCount":{"type":"integer"}},"required":["sourceId","knowledgeBaseId","status","sourceType","displayName","pageCount"]},"maxItems":50},"view":{"type":"string","const":"inspection"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"},"returnedCount":{"type":"integer","minimum":0,"maximum":50},"totalElements":{"type":"integer","minimum":0},"complete":{"type":"boolean"}},"required":["sources","view","hasMore","nextCursor","returnedCount","totalElements","complete"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"406":{"description":"Explicit inspection was requested but Accept does not allow application/vnd.stand.knowledge-inspection+json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/documents":{"get":{"operationId":"listKnowledgeBaseDocuments","summary":"List indexed documents","description":"Without view, preserves the complete legacy application/json list and fields. Explicit view=inspection selects SQL-bounded metadata with application/vnd.stand.knowledge-inspection+json; Accept must allow that media type (406 otherwise). Inspection parameters require view=inspection. Lists are ordered by immutable createdAt descending and ID descending. Follow nextCursor as after with the same base and filters; malformed or differently bound cursors return 400. Each page rechecks current organization and knowledge-base access. Exact filter IDs outside that base return 404. Historical tasks remain readable after source deletion. complete means this response alone covers the selected list: it is false on every continuation page, including the last. hasMore/nextCursor describe the remaining pages. totalElements is an independent current count, not a snapshot across concurrent changes. Content, raw diagnostics, worker fields and storage paths are omitted. Task effectiveUrl is null for unavailable/deleted source metadata or URLs exceeding 2048 UTF-16 code units.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["inspection"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"after","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"sourceId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, select this exact source in the selected base; foreign or mismatched IDs return 404. A soft-deleted source can still scope retained tasks/documents. Without view, the existing document source filter is unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseDocument"}}},"required":["documents"]}},"application/vnd.stand.knowledge-inspection+json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"documentId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"status":{"type":"string"},"chunkCount":{"type":"integer","minimum":0}},"required":["documentId","knowledgeBaseId","sourceId","status","chunkCount"]},"maxItems":50},"view":{"type":"string","const":"inspection"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"},"returnedCount":{"type":"integer","minimum":0,"maximum":50},"totalElements":{"type":"integer","minimum":0},"complete":{"type":"boolean"}},"required":["documents","view","hasMore","nextCursor","returnedCount","totalElements","complete"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"406":{"description":"Explicit inspection was requested but Accept does not allow application/vnd.stand.knowledge-inspection+json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/documents/{documentId}":{"get":{"operationId":"getKnowledgeBaseDocument","summary":"Read an indexed document","description":"Read an indexed document","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteKnowledgeBaseDocument","summary":"Schedule document deletion","description":"Schedule document deletion","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/documents/{documentId}/chunks":{"get":{"operationId":"listKnowledgeBaseDocumentChunks","summary":"Inspect document chunks","description":"Inspect document chunks","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"chunks":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseChunk"}}},"required":["chunks"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/documents/{documentId}/search":{"post":{"operationId":"searchKnowledgeBaseDocument","summary":"Search an indexed document","description":"Search an indexed document","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSearch"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseSearchResult"}}},"required":["results"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/tasks":{"get":{"operationId":"listKnowledgeBaseTasks","summary":"List ingestion tasks","description":"Without view, preserves the complete legacy application/json list and fields. Explicit view=inspection selects SQL-bounded metadata with application/vnd.stand.knowledge-inspection+json; Accept must allow that media type (406 otherwise). Inspection parameters require view=inspection. Lists are ordered by immutable createdAt descending and ID descending. Follow nextCursor as after with the same base and filters; malformed or differently bound cursors return 400. Each page rechecks current organization and knowledge-base access. Exact filter IDs outside that base return 404. Historical tasks remain readable after source deletion. complete means this response alone covers the selected list: it is false on every continuation page, including the last. hasMore/nextCursor describe the remaining pages. totalElements is an independent current count, not a snapshot across concurrent changes. Content, raw diagnostics, worker fields and storage paths are omitted. Task effectiveUrl is null for unavailable/deleted source metadata or URLs exceeding 2048 UTF-16 code units.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["inspection"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"after","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"taskId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, inspect this exact task, including an older task whose source was deleted. The task must belong to the selected base; otherwise 404."},{"name":"sourceId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, select this exact source in the selected base; foreign or mismatched IDs return 404. A soft-deleted source can still scope retained tasks/documents. Without view, the existing document source filter is unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}},"required":["tasks"]}},"application/vnd.stand.knowledge-inspection+json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"status":{"type":"string"},"sourceId":{"type":["string","null"]},"progressCurrent":{"type":"integer"},"progressTotal":{"type":"integer"},"effectiveUrl":{"type":["string","null"],"maxLength":2048}},"required":["taskId","knowledgeBaseId","status","sourceId","progressCurrent","progressTotal","effectiveUrl"]},"maxItems":50},"view":{"type":"string","const":"inspection"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"},"returnedCount":{"type":"integer","minimum":0,"maximum":50},"totalElements":{"type":"integer","minimum":0},"complete":{"type":"boolean"}},"required":["tasks","view","hasMore","nextCursor","returnedCount","totalElements","complete"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"406":{"description":"Explicit inspection was requested but Accept does not allow application/vnd.stand.knowledge-inspection+json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/sources/{sourceId}":{"delete":{"operationId":"deleteKnowledgeBaseSource","summary":"Schedule source deletion","description":"Marks a source for deletion; derived data cleanup is asynchronous.","tags":["Knowledge bases"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/sources/{sourceId}/recrawl":{"post":{"operationId":"recrawlKnowledgeBaseSource","summary":"Queue a source refresh","tags":["Knowledge bases"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}],"description":"Queue another crawl of an owned website or sitemap source, subject to existing source and plan limits."}},"/v1/knowledge-bases/sources/{sourceId}/sitemap-refresh":{"put":{"operationId":"setSitemapRefresh","summary":"Change daily sitemap refresh","tags":["Knowledge bases"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSource"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}],"description":"Change the refresh preference on an owned sitemap source; the existing background schedule performs subsequent ingestion."}},"/v1/knowledge-bases/tasks/{taskId}/cancel":{"post":{"operationId":"cancelKnowledgeBaseTask","summary":"Request ingestion cancellation","description":"Only the knowledge-base owner can request cancellation; inspect returned/task-list status until the worker reaches a terminal state.","tags":["Knowledge bases"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/search":{"post":{"operationId":"searchKnowledgeBase","summary":"Search a knowledge base","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSearch"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseSearchResult"}}},"required":["results"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}],"description":"Search documents accessible within this knowledge base. Current organization membership and knowledge-base permissions apply."}},"/v1/reps/me/standins/{standinProfileId}/knowledge-bases":{"get":{"operationId":"getAgentKnowledgeBases","summary":"List a Stand-in knowledge attachments","description":"List a Stand-in knowledge attachments","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKnowledgeBases"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"setAgentKnowledgeBases","summary":"Replace a Stand-in knowledge attachments","description":"Replace the complete knowledge attachment list for your Stand-in. Read existing attachments and preserve every ID that should remain. Always send knowledgeBaseIds explicitly; an empty list detaches all. Coordinate concurrent changes and stop if existing attachments changed unexpectedly.","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"knowledgeBaseIds":{"type":"array","items":{"type":"string"}}},"required":["knowledgeBaseIds"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKnowledgeBases"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan capability unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/integrations":{"get":{"operationId":"listIntegrations","summary":"List organization integrations and capabilities","description":"List organization integrations and capabilities","tags":["Integrations"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationOverview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:read","security":[{"bearerAuth":[]}]}},"/v1/integrations/openapi/preview":{"post":{"operationId":"previewOpenApiIntegration","summary":"Preview an imported OpenAPI integration","description":"Validates and previews a customer API specification; does not create the integration. Import rate and document/operation/schema limits apply.","tags":["Integrations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseUrl":{"type":"string"},"openApiDocument":{"type":"string"}},"required":["baseUrl","openApiDocument"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The complete integration request body exceeds 5 MiB (INTEGRATION_PAYLOAD_TOO_LARGE), including chunked requests. Reduce the payload before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the shared per-representative import window is exhausted. Retry-After is 60 seconds, a conservative wait for the existing one-minute window. Applies to preview/create and update when importing a replacement declaration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/integrations/{integrationId}/openapi":{"get":{"operationId":"getIntegrationOpenApi","summary":"Read the imported OpenAPI source","description":"Read the imported OpenAPI source","tags":["Integrations"],"parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiIntegrationSource"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateOpenApiIntegration","summary":"Update an OpenAPI integration","description":"Replaces name, description, destination and authentication metadata; this is not a partial PATCH. First read listIntegrations and copy the current name, description, baseUrl, authType and authHeaderName, then edit the intended fields. Omitted description clears it. Omitted/null/blank authType means none and deletes stored authentication. To retain a secret, explicitly keep the same non-none authType, baseUrl and applicable authHeaderName, and omit authUsername/authSecret. The example assumes an existing bearer-authenticated integration at that exact destination. Changing type, destination, header or username requires a replacement secret; basic then requires its username. A nonblank openApiDocument replaces the declaration and requires a nonempty tool selection. Without it, tools/source are preserved and nonempty selection arrays are rejected.","tags":["Integrations"],"parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The complete integration request body exceeds 5 MiB (INTEGRATION_PAYLOAD_TOO_LARGE), including chunked requests. Reduce the payload before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the shared per-representative import window is exhausted. Retry-After is 60 seconds, a conservative wait for the existing one-minute window. Applies to preview/create and update when importing a replacement declaration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/integrations/openapi":{"post":{"operationId":"createOpenApiIntegration","summary":"Create an OpenAPI integration","description":"Creates an organization integration from a complete OpenAPI declaration. Supply name, public baseUrl and at least one actual selected tool key from previewOpenApiIntegration. selectedTools takes precedence when it contains nonblank keys; enabledToolKeys is a legacy fallback. Non-none authentication requires a secret and HTTPS; basic also requires a username and api_key_header requires a header name. The server validates declaration limits, selected operation membership, public destination safety and credential/header rules. Selected write tools require configured confirmation signing.","tags":["Integrations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationCreate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The complete integration request body exceeds 5 MiB (INTEGRATION_PAYLOAD_TOO_LARGE), including chunked requests. Reduce the payload before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the shared per-representative import window is exhausted. Retry-After is 60 seconds, a conservative wait for the existing one-minute window. Applies to preview/create and update when importing a replacement declaration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/integrations/{integrationId}":{"delete":{"operationId":"deleteIntegration","summary":"Delete an integration and detach it from agents","description":"Delete an integration and detach it from agents","tags":["Integrations"],"parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{standinProfileId}/integrations":{"get":{"operationId":"getAgentIntegrations","summary":"List a Stand-in integration attachments","description":"List a Stand-in integration attachments","tags":["Integrations"],"parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentIntegrations"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"setAgentIntegrations","summary":"Replace a Stand-in integration attachments","description":"Replaces every integration attachment. First read getAgentIntegrations and include each integrationId to retain; an empty array, omission or null detaches all.","tags":["Integrations"],"parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationIds":{"type":["array","null"],"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentIntegrations"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"One or more selected integrations require a plan entitlement the organization does not have. Inspect listIntegrations capabilities; an empty set can detach integrations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/reps/profile/avatar":{"post":{"operationId":"uploadRepAvatar","summary":"Stage a profile avatar image","description":"Stages an immutable image for the authenticated representative without changing the current profile. Pass the returned filename as avatarUrl in PUT /v1/reps/profile, retaining the other profile fields. avatarUrl in this response is the resolved image URL. Static images are center-cropped and resized to 256×256 WebP. Animated GIF and WebP retain animation only when square, 64–256 pixels per side, at most 256 KiB, at most 300 frames, at most 10 seconds total, and at least 30 ms per frame; invalid animations return 400 BAD_REQUEST.","tags":["Representative presence"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":"string"},"filename":{"type":"string"}},"required":["avatarUrl","filename"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed. Animated avatar validation also returns BAD_REQUEST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standin/status":{"get":{"operationId":"getStandinStatus","summary":"Get your master Stand-in switch","description":"Read your account-wide Stand-in master switch. This is separate from the enabled state of each individual Stand-in.","tags":["Representative presence"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"standinEnabled":{"type":"boolean"}},"required":["standinEnabled"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standin/toggle":{"post":{"operationId":"toggleStandin","summary":"Set your master Stand-in switch","description":"Set your account-wide Stand-in master switch using enabled true or false. This affects all of your individually enabled Stand-ins, including those on other Sites; inspect the existing configuration and obtain approval for that shared effect.","tags":["Representative presence"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"standinEnabled":{"type":"boolean"}},"required":["standinEnabled"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/org-prompt":{"get":{"operationId":"getMyOrgPrompt","summary":"Get your current organization instructions","description":"Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Representative presence"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"hasOrg":{"type":"boolean"},"prompt":{"anyOf":[{"$ref":"#/components/schemas/OrgPrompt"},{"type":"null"}]},"ownerName":{"type":["string","null"]}},"required":["hasOrg","prompt","ownerName"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins":{"get":{"operationId":"listLapelPins","summary":"List organization pin policies","description":"List organization pin policies","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LapelPin"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveLapelPin","summary":"Save organization pin policy","description":"Replaces editable pin settings, not a partial PATCH. First read the selected pin and copy pinType, color, borderColor, fontFamily, fontColor, pillText and usePinAsBotAvatar before editing. Omitted/null pinType, color and fontFamily reset to none, #000000 and sans-serif; omitted optional text/colors clear and usePinAsBotAvatar becomes false. Existing uploaded icon/logo URLs are preserved. Sending only pillText turns the pin off. For organization policies, preserve domain to select the same policy; omission selects the organization-wide default.","tags":["Branding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPinInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteOrgPin","summary":"Delete organization pin policy","description":"Delete organization pin policy","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/me":{"get":{"operationId":"getMyPin","summary":"Get your personal pin","description":"Get your personal pin","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionalLapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveMyPin","summary":"Save your personal pin","description":"Replaces editable pin settings, not a partial PATCH. First read the selected pin and copy pinType, color, borderColor, fontFamily, fontColor, pillText and usePinAsBotAvatar before editing. Omitted/null pinType, color and fontFamily reset to none, #000000 and sans-serif; omitted optional text/colors clear and usePinAsBotAvatar becomes false. Existing uploaded icon/logo URLs are preserved. Sending only pillText turns the pin off. For organization policies, preserve domain to select the same policy; omission selects the organization-wide default.","tags":["Branding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPinInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/resolve":{"get":{"operationId":"resolveLapelPin","summary":"Resolve the effective pin for a domain","description":"Resolve the effective pin for a domain","tags":["Branding"],"parameters":[{"name":"domain","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionalLapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/me/icon":{"post":{"operationId":"uploadMyIcon","summary":"Upload your personal pin icon","description":"Applies the uploaded image immediately and returns its resolved URL. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 128×128 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"circleIconUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["circleIconUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/me/logo":{"post":{"operationId":"uploadMyLogo","summary":"Upload your personal pin logo","description":"Applies the uploaded image immediately and returns its resolved URL. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 256×64 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"pillLogoUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["pillLogoUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/{pinId}/icon":{"post":{"operationId":"uploadIcon","summary":"Upload an organization pin icon","description":"Applies the uploaded image immediately and returns its resolved URL. Requires the current active organization owner and an existing pinId from that organization; a missing or foreign pin returns 404 NOT_FOUND. Uploading does not change pinType or other pin settings. The image is resized to fit 128×128 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"parameters":[{"name":"pinId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"circleIconUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["circleIconUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/{pinId}/logo":{"post":{"operationId":"uploadLogo","summary":"Upload an organization pin logo","description":"Applies the uploaded image immediately and returns its resolved URL. Requires the current active organization owner and an existing pinId from that organization; a missing or foreign pin returns 404 NOT_FOUND. Uploading does not change pinType or other pin settings. The image is resized to fit 256×64 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"parameters":[{"name":"pinId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"pillLogoUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["pillLogoUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/skills":{"get":{"operationId":"listStandinSkills","summary":"List Stand-in skills and effective entitlements","description":"Read skills on one of your Stand-ins. Site restriction does not change ownership or delegated permissions.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkill"}}},"required":["skills"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/skills/{skillKey}":{"put":{"operationId":"updateStandinSkill","summary":"Save a Stand-in skill","description":"Skill keys are followup, customerDiscovery, and labeling. Omitted/null config preserves existing settings. followup merges supplied keys; customerDiscovery replaces the configuration, so first read listStandinSkills and copy all fields to retain them. labeling preserves labels unless config.labels is present: supply every retained label with its labelId, name, prompt, active and notify; [] clears them. Enabled state never overrides plan entitlement. Label input requires a nonblank name and prompt; testPrompt is a legacy alias used only when prompt is absent. A present null, blank or malformed prompt is rejected even if testPrompt is valid.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"skillKey","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSkillUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSkill"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective plan does not permit enabling this skill or saving active labels. Saving active labels can be denied even when the labeling skill is disabled. Inspect listStandinSkills; do not retry unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/avatar":{"post":{"operationId":"uploadStandinAvatar","summary":"Apply a Stand-in avatar image","description":"Applies the uploaded image immediately to your existing Stand-in, retaining its ID. No subsequent profile save is needed. A missing, deleted or another representative’s Stand-in returns 404 NOT_FOUND. Static images are center-cropped and resized to 256×256 WebP. Animated GIF and WebP retain animation only when square, 64–256 pixels per side, at most 256 KiB, at most 300 frames, at most 10 seconds total, and at least 30 ms per frame; invalid animations return 400 BAD_REQUEST.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":"string"}},"required":["avatarUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed. Animated avatar validation also returns BAD_REQUEST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"clearAvatar","summary":"Remove a Stand-in avatar","description":"Changes an owned Stand-in; current account and resource permissions apply.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":["string","null"]}},"required":["avatarUrl"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/avatar-upload":{"post":{"operationId":"uploadDraftAvatar","summary":"Stage an avatar for a new Stand-in","description":"Stages an immutable image without creating or modifying a Stand-in. Pass the returned filename as avatarUrl when creating the Stand-in with POST /v1/reps/me/standins. avatarUrl in this response is the resolved image URL. Static images are center-cropped and resized to 256×256 WebP. Animated GIF and WebP retain animation only when square, 64–256 pixels per side, at most 256 KiB, at most 300 frames, at most 10 seconds total, and at least 30 ms per frame; invalid animations return 400 BAD_REQUEST.","tags":["Stand-ins"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string"},"avatarUrl":{"type":"string"}},"required":["filename","avatarUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed. Animated avatar validation also returns BAD_REQUEST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/unclaimed-avatar-pool":{"get":{"operationId":"unclaimedAvatarPool","summary":"List reusable avatar candidates","description":"List reusable avatar candidates","tags":["Stand-ins"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":12},"description":"Clamped to 1 through 24."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCandidates"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/avatar-candidates":{"post":{"operationId":"generateAvatarCandidates","summary":"Generate avatar candidates","description":"Runs a bounded generation request under per-rep daily rate limits. Does not select a candidate automatically.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCandidates"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the existing per-representative daily avatar allowance is exhausted. Retry-After is the positive number of seconds until the next UTC midnight, rounded up. No provider generation starts on this denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"The image provider failed or no generated image could be processed. The generation attempt already counts toward the daily limit; do not automatically retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"extraInstructions":{"type":["string","null"]}}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/preview-avatar-candidates":{"post":{"operationId":"previewAvatarCandidates","summary":"Generate candidates before creating a Stand-in","description":"Creates an unattached candidate pool for the user under the ordinary role and quota checks; it does not update a Stand-in.","tags":["Stand-ins"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":["string","null"]},"greeting":{"type":["string","null"]},"prompt":{"type":["string","null"]},"siteId":{"type":["string","null"]},"extraInstructions":{"type":["string","null"]}},"required":["displayName"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCandidates"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the existing per-representative daily avatar allowance is exhausted. Retry-After is the positive number of seconds until the next UTC midnight, rounded up. No provider generation starts on this denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"The image provider failed or no generated image could be processed. The generation attempt already counts toward the daily limit; do not automatically retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/avatar/select-candidate":{"post":{"operationId":"selectAvatarCandidate","summary":"Apply a generated avatar candidate","description":"Select an AI-generated candidate created by you or currently available in the shared unclaimed pool. Uploaded photos and another user’s already-claimed generated candidates cannot be selected by filename.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"candidateId":{"type":"string"}},"required":["candidateId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":"string"}},"required":["avatarUrl"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/lapel-pin":{"get":{"operationId":"getStandinLapelPin","summary":"Get a Stand-in pin","description":"If the owned Stand-in has no pin yet, returns 404 NOT_FOUND with error.details.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveStandinLapelPin","summary":"Save a Stand-in pin","description":"Replaces editable pin settings, not a partial PATCH. First read the selected pin and copy pinType, color, borderColor, fontFamily, fontColor, pillText and usePinAsBotAvatar before editing. Omitted/null pinType, color and fontFamily reset to none, #000000 and sans-serif; omitted optional text/colors clear and usePinAsBotAvatar becomes false. Existing uploaded icon/logo URLs are preserved. Sending only pillText turns the pin off. For organization policies, preserve domain to select the same policy; omission selects the organization-wide default.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPinInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/lapel-pin/icon":{"post":{"operationId":"uploadStandinPinIcon","summary":"Upload a Stand-in pin icon","description":"Applies the uploaded image immediately to your Stand-in’s pin and returns its resolved URL. A missing, deleted or another representative’s Stand-in returns 404 NOT_FOUND. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 128×128 while preserving aspect ratio and stored as static WebP.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"circleIconUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["circleIconUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. These two Stand-in pin routes validate decoded image bytes without requiring a particular file-part Content-Type. PNG, JPEG, WebP and GIF are supported. The configured multipart limits are 10 MiB (10,485,760 bytes) per file and 12 MiB (12,582,912 bytes) per request, including multipart overhead; there is no separate 5 MiB controller limit on these two routes."}},"required":["file"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/lapel-pin/logo":{"post":{"operationId":"uploadStandinPinLogo","summary":"Upload a Stand-in pin logo","description":"Applies the uploaded image immediately to your Stand-in’s pin and returns its resolved URL. A missing, deleted or another representative’s Stand-in returns 404 NOT_FOUND. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 256×64 while preserving aspect ratio and stored as static WebP.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"pillLogoUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["pillLogoUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. These two Stand-in pin routes validate decoded image bytes without requiring a particular file-part Content-Type. PNG, JPEG, WebP and GIF are supported. The configured multipart limits are 10 MiB (10,485,760 bytes) per file and 12 MiB (12,582,912 bytes) per request, including multipart overhead; there is no separate 5 MiB controller limit on these two routes."}},"required":["file"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/stats":{"get":{"operationId":"getStats","summary":"Get usage statistics for an authorized scope","description":"Read statistics for an authorized representative, Site or organization. A representative can read their own statistics; an organization owner can read a member's representative statistics. Site and organization access require membership in that organization. Existing resource checks apply.","tags":["Statistics"],"parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["rep","site","org"]},"description":"Usage for an authorized representative, site or organization. Stand-in-specific statistics are not available. Resource ownership and organization membership checks apply."},{"name":"scopeId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Required resource identifier: your userId for rep, an accessible siteId for site, or your orgId for org. Obtain these from identity/profile or site reads."},{"name":"bucketType","in":"query","required":true,"schema":{"type":"string","enum":["h","d","w"]},"description":"Returns 24 hourly, 28 daily, or 52 weekly buckets."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"analytics:read","security":[{"bearerAuth":[]}]}},"/v1/stats/live-shows":{"get":{"operationId":"getLiveShows","summary":"Count recent widget shows on your covered sites","description":"Count recent widget shows on your covered sites","tags":["Statistics"],"parameters":[{"name":"windowSeconds","in":"query","required":false,"schema":{"type":"integer","default":300,"minimum":60,"maximum":3600}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveShowsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"analytics:read","security":[{"bearerAuth":[]}]}},"/v1/feedback":{"post":{"operationId":"submitFeedback","summary":"Submit feedback to Stand","description":"Submit feedback to Stand","tags":["Feedback"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"feedbackId":{"type":"string"},"submittedAt":{"type":"string","format":"date-time"}},"required":["feedbackId","submittedAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["whats-working","how-i-use-stand","idea","bug","blocker","sales-inquiry"]},"description":{"type":"string"},"file":{"type":"string","format":"binary","description":"Optional image, at most 4 MiB."}},"required":["type","description"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"feedback:write","security":[{"bearerAuth":[]}]}},"/v1/org/usage":{"get":{"operationId":"getOrgUsage","summary":"Get current plan usage","description":"Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Plans and billing"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUsage"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/org/plan":{"get":{"operationId":"getOrgPlan","summary":"Get current plan capabilities","description":"Price, billing-cycle, and overage-price fields are omitted for nonowners. Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Plans and billing"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPlan"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"User access token for stand-api managed by the supported stand-cli OAuth client. Sign in with stand auth login and use named commands or stand api; no custom client registration, personal access tokens or service accounts are offered in this beta. Live membership, role, tenant, owner and resource checks still apply."}},"schemas":{"User":{"type":"object","properties":{"isRep":{"type":"boolean"},"userId":{"type":"string"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"orgId":{"type":["string","null"]},"brand":{"type":["string","null"]},"title":{"type":["string","null"]},"avatar":{"type":["string","null"]},"roles":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["isRep","userId","email","name","orgId","brand","title","avatar","roles"]},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code. Each public operation lists known codes in x-error-codes.byStatus. That catalog is non-exhaustive; preserve unfamiliar codes and use the HTTP status as a fallback. Do not parse message text."},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"type":"object","additionalProperties":true,"properties":{"requiredScope":{"type":"string","description":"An additional delegated permission required by the requested change, when applicable."}}}},"required":["code","message","timestamp"]}},"required":["error"]},"RepProfileResponse":{"type":"object","properties":{"completed":{"type":"boolean"},"profile":{"anyOf":[{"$ref":"#/components/schemas/RepProfile"},{"type":"null"}]},"accountDisabled":{"type":"boolean"},"ownerName":{"type":["string","null"]}},"required":["completed","profile","accountDisabled","ownerName"]},"RepProfile":{"type":"object","properties":{"userId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":["string","null"]},"title":{"type":["string","null"]},"organization":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"orgId":{"type":["string","null"]},"greeting":{"type":["string","null"]},"completedAt":{"type":["string","null"],"format":"date-time"},"greetingEnabled":{"type":"boolean"}},"required":["userId","firstName","lastName","email","title","organization","avatarUrl","orgId","greeting","completedAt","greetingEnabled"]},"RepProfileUpdate":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":255},"lastName":{"type":"string","minLength":1,"maxLength":255},"title":{"type":["string","null"],"maxLength":255},"organization":{"type":["string","null"],"maxLength":255},"avatarUrl":{"type":["string","null"],"maxLength":255},"greeting":{"type":["string","null"]},"greetingEnabled":{"type":["boolean","null"]}},"required":["firstName","lastName"],"additionalProperties":false},"SiteList":{"type":"object","properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"isOwner":{"type":"boolean"},"ownerName":{"type":"string"}},"required":["sites","isOwner","ownerName"]},"Site":{"type":"object","properties":{"siteId":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"snippet":{"type":"string"},"enabled":{"type":"boolean"},"installed":{"type":"boolean"},"installedAt":{"type":"string","description":"ISO instant when installed; empty string before installation."},"createdAt":{"type":"string","format":"date-time"},"defaultLanguageCode":{"type":["string","null"]},"embedOptions":{"$ref":"#/components/schemas/SiteEmbedOptions"},"behaviorConfig":{"$ref":"#/components/schemas/SiteBehaviorConfig"}},"required":["siteId","domain","name","snippet","enabled","installed","installedAt","createdAt","defaultLanguageCode","embedOptions","behaviorConfig"]},"SiteEmbedOptions":{"type":"object","properties":{"delayToScroll":{"type":"boolean"},"noGreetings":{"type":"boolean"},"openChatAfterGreeting":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"},"revealDelayMs":{"type":"integer","minimum":0,"maximum":60000}},"required":["delayToScroll","noGreetings","openChatAfterGreeting","halfSize","stepAside","revealDelayMs"]},"SiteBehaviorConfig":{"type":"object","properties":{"advancedBehaviorEnabled":{"type":"boolean"},"allowStandAdminBehavior":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SiteBehaviorRule"}}},"required":["advancedBehaviorEnabled","allowStandAdminBehavior","rules"]},"SiteBehaviorRule":{"type":"object","properties":{"ruleId":{"type":"string"},"name":{"type":"string"},"pathPrefix":{"type":"string"},"customJavascript":{"type":"string"},"enabled":{"type":"boolean"},"hideButtonUntilTriggered":{"type":"boolean"},"presentation":{"$ref":"#/components/schemas/SiteBehaviorPresentation"},"trigger":{"$ref":"#/components/schemas/SiteBehaviorTrigger"},"action":{"$ref":"#/components/schemas/SiteBehaviorAction"}},"required":["ruleId","name","pathPrefix","customJavascript","enabled","hideButtonUntilTriggered","presentation","trigger","action"]},"SiteBehaviorPresentation":{"type":"object","properties":{"noGreetings":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"}},"required":["noGreetings","halfSize","stepAside"]},"SiteBehaviorTrigger":{"type":"object","properties":{"type":{"type":"string"},"delayMs":{"type":"integer"},"scrollPercent":{"type":"integer"}},"required":["type","delayMs","scrollPercent"]},"SiteBehaviorAction":{"type":"object","properties":{"type":{"type":"string"},"initialMessage":{"type":"string"}},"required":["type","initialMessage"]},"SiteCreate":{"type":"object","properties":{"domain":{"type":"string","description":"The normalized domain must fit 255 characters. Supply a hostname, without URL path or query.","minLength":1,"maxLength":255},"name":{"type":["string","null"],"maxLength":255},"embedOptions":{"$ref":"#/components/schemas/SiteEmbedOptionsUpdate"},"behaviorConfig":{"$ref":"#/components/schemas/SiteBehaviorConfigInput"}},"required":["domain"]},"SiteEmbedOptionsUpdate":{"type":"object","properties":{"delayToScroll":{"type":"boolean"},"noGreetings":{"type":"boolean"},"openChatAfterGreeting":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"},"revealDelayMs":{"type":"integer","minimum":0,"maximum":60000}},"additionalProperties":false,"description":"Legacy compatibility input. On update, any supplied embedOptions object, including embedOptions: {}, merges supplied keys into the saved legacy options and then replaces behaviorConfig: advancedBehaviorEnabled and allowStandAdminBehavior become false, and all existing rules, including custom JavaScript rules, are replaced by zero or one legacy-default rule derived from the merged options. An explicit behaviorConfig in the same request is applied after this conversion and controls the final configuration. Owner-consent validation uses the committed configuration before any sibling mutation; all fields are validated before saving. For behavior edits, modern clients should read the Site and replace the complete behaviorConfig with both switches and every retained rule."},"SiteBehaviorConfigInput":{"type":"object","properties":{"advancedBehaviorEnabled":{"type":"boolean"},"allowStandAdminBehavior":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SiteBehaviorRuleInput"}}},"required":["advancedBehaviorEnabled","allowStandAdminBehavior","rules"],"additionalProperties":false,"description":"Complete replacement, not a partial update. Read the current behaviorConfig first and include both switches and every retained rule. Missing primitive switches become false and missing rules becomes an empty list on the server; send all three fields to avoid unintended resets. External API/CLI clients cannot enable experimentation: advancedBehaviorEnabled may remain true only when it is already enabled for that Site. The organization owner enables it in the Stand dashboard under Sites > Chat widget behavior > Experimentation (Advanced), after accepting the warning. Once enabled, owner-authorized OAuth clients with sites:write may add, edit and activate custom JavaScript rules. Disabling it strips custom JavaScript from subsequent visitor behavior responses; stored source can be retained or edited while disabled but cannot execute. API clients may disable it but cannot re-enable it, even with an unconditional configuration replacement. They also cannot grant Stand-admin experimentation access. A denied enablement returns 403 EXPERIMENTATION_CONSENT_REQUIRED with no sibling changes. Reload the Site after the owner changes consent; broader scopes or another login cannot enable it."},"SiteBehaviorRuleInput":{"type":"object","properties":{"ruleId":{"type":"string"},"name":{"type":"string"},"pathPrefix":{"type":"string"},"customJavascript":{"type":"string"},"enabled":{"type":"boolean"},"hideButtonUntilTriggered":{"type":"boolean"},"presentation":{"type":"object","properties":{"noGreetings":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"}},"additionalProperties":false},"trigger":{"type":"object","properties":{"type":{"type":"string"},"delayMs":{"type":"integer"},"scrollPercent":{"type":"integer"}},"additionalProperties":false},"action":{"type":"object","properties":{"type":{"type":"string"},"initialMessage":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"Deleted":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]},"SiteMatches":{"type":"object","properties":{"siteMatches":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/SiteMatch"}},"description":"Map keyed by public site ID."}},"required":["siteMatches"]},"SiteMatch":{"type":"object","properties":{"probability":{"type":"number"},"responderType":{"type":"string"},"pathPrefix":{"type":"string"},"ownerRepId":{"type":"string"},"repId":{"type":["string","null"]},"standinProfileId":{"type":["string","null"]},"name":{"type":["string","null"]},"brandName":{"type":["string","null"]},"avatar":{"type":["string","null"]},"ownerName":{"type":["string","null"]},"ownerTitle":{"type":["string","null"]},"lapelPin":{"anyOf":[{"$ref":"#/components/schemas/LapelPin"},{"type":"null"}]}},"required":["probability","responderType","pathPrefix","ownerRepId","repId","standinProfileId","name","brandName","avatar","ownerName","ownerTitle","lapelPin"]},"LapelPin":{"type":"object","properties":{"pinId":{"type":["string","null"]},"orgId":{"type":["string","null"]},"domain":{"type":["string","null"]},"color":{"type":["string","null"]},"borderColor":{"type":["string","null"]},"fontFamily":{"type":["string","null"]},"fontColor":{"type":["string","null"]},"pillText":{"type":["string","null"]},"circleIconUrl":{"type":["string","null"]},"pillLogoUrl":{"type":["string","null"]},"pinType":{"type":"string"},"usePinAsBotAvatar":{"type":"boolean"}},"required":["pinId","orgId","domain","color","borderColor","fontFamily","fontColor","pillText","circleIconUrl","pillLogoUrl","pinType","usePinAsBotAvatar"]},"SitePreferences":{"type":"object","properties":{"siteIds":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"null means never configured; [] opts out of all sites."}},"required":["siteIds"]},"SitePrompt":{"type":"object","properties":{"sitePromptId":{"type":"string"},"siteId":{"type":"string"},"content":{"type":"string"},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["sitePromptId","siteId","content","active","createdAt"]},"PromptUpdate":{"type":"object","properties":{"content":{"type":"string"}},"required":["content"]},"OrgPrompt":{"type":"object","properties":{"orgPromptId":{"type":"string"},"orgId":{"type":"string"},"content":{"type":"string"},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["orgPromptId","orgId","content","active","createdAt"]},"OrgPrivacy":{"type":"object","properties":{"orgId":{"type":"string"},"sensitiveNoticeEnabled":{"type":"boolean"},"sensitiveNoticeText":{"type":["string","null"]},"retentionDays":{"type":"integer"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["orgId","sensitiveNoticeEnabled","sensitiveNoticeText","retentionDays","updatedAt"]},"OrgPrivacyUpdate":{"type":"object","properties":{"sensitiveNoticeEnabled":{"type":"boolean"},"sensitiveNoticeText":{"type":["string","null"]},"retentionDays":{"type":"integer"}},"required":["sensitiveNoticeEnabled","retentionDays"]},"ArchivedSessions":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ArchivedSession"}},"page":{"type":"integer"},"totalPages":{"type":"integer"},"totalElements":{"type":"integer","format":"int64"},"isOwner":{"type":"boolean"},"sites":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/HistoryLabelOption"}}},"required":["sessions","page","totalPages","totalElements","isOwner","sites","labels"]},"ArchivedSession":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"page":{"type":"string"},"closedBy":{"type":["string","null"]},"closedByType":{"type":["string","null"]},"visitorName":{"type":["string","null"]},"visitorEmail":{"type":["string","null"]},"visitorPhone":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"messageCount":{"type":"integer"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/SessionLabel"}}},"required":["sessionId","status","page","closedBy","closedByType","visitorName","visitorEmail","visitorPhone","createdAt","closedAt","messageCount","labels"]},"SessionLabel":{"type":"object","properties":{"labelId":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"setAt":{"type":"string","format":"date-time"}},"required":["labelId","name","summary","setAt"]},"HistoryLabelOption":{"type":"object","properties":{"labelId":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"}},"required":["labelId","name"]},"ActiveSessions":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"string"}},"standinSessions":{"type":"array","items":{"type":"string"}},"needsAttention":{"type":"boolean"}},"required":["sessions","standinSessions","needsAttention"]},"Message":{"type":"object","properties":{"messageId":{"type":"string"},"sessionId":{"type":"string"},"senderId":{"type":"string"},"senderType":{"type":"string"},"body":{"type":"string"},"type":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"seq":{"type":"integer"},"clientMessageId":{"type":["string","null"]}},"required":["messageId","sessionId","senderId","senderType","body","type","sentAt","seq","clientMessageId"]},"GreetingVariant":{"type":"object","properties":{"greetingVariantId":{"type":"string"},"ownerType":{"type":"string"},"ownerId":{"type":"string"},"text":{"type":"string"},"status":{"type":"string"},"defaultVariant":{"type":"boolean"},"shownCount":{"type":"integer","format":"int64"},"openedCount":{"type":"integer","format":"int64"},"conversationStartedCount":{"type":"integer","format":"int64"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["greetingVariantId","ownerType","ownerId","text","status","defaultVariant","shownCount","openedCount","conversationStartedCount","createdAt","updatedAt"]},"GreetingVariantInput":{"type":"object","properties":{"greetingVariantId":{"type":["string","null"]},"text":{"type":"string"},"status":{"type":"string"},"defaultVariant":{"type":"boolean"}},"required":["text"]},"Team":{"type":"object","properties":{"orgId":{"type":"string"},"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}},"invitations":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"isOwner":{"type":"boolean"}},"required":["orgId","members","invitations","isOwner"]},"TeamMember":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"avatarUrl":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"},"joinedAt":{"type":"string"},"online":{"type":"boolean"},"acceptingChats":{"type":"boolean"},"agentsEnabled":{"type":"boolean"}},"required":["userId","email","firstName","lastName","avatarUrl","role","status","joinedAt","online","acceptingChats","agentsEnabled"]},"Invitation":{"type":"object","properties":{"invitationId":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"requireProvider":{"type":["string","null"]}},"required":["invitationId","email","status","createdAt","expiresAt","requireProvider"]},"DigestPreferences":{"type":"object","properties":{"cadence":{"type":"string","enum":["NONE","DAILY","WEEKLY","MONTHLY"]},"skipEmptyReports":{"type":"boolean"},"lastSentAt":{"type":["string","null"],"format":"date-time"},"includeTips":{"type":"boolean"}},"required":["cadence","skipEmptyReports","lastSentAt","includeTips"]},"DigestPreferencesUpdate":{"type":"object","properties":{"cadence":{"type":"string","enum":["NONE","DAILY","WEEKLY","MONTHLY"]},"skipEmptyReports":{"type":"boolean"},"includeTips":{"type":"boolean"}},"anyOf":[{"required":["cadence"]},{"required":["skipEmptyReports"]},{"required":["includeTips"]}]},"DigestAiPreferences":{"type":"object","properties":{"aiEnabled":{"type":"boolean"},"planAllows":{"type":"boolean"},"maxLabels":{"type":"integer"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/DigestLabel"}}},"required":["aiEnabled","planAllows","maxLabels","labels"]},"DigestLabel":{"type":"object","properties":{"labelId":{"type":"string"},"position":{"type":"integer"},"name":{"type":"string"},"testPrompt":{"type":"string"},"active":{"type":"boolean"}},"required":["labelId","position","name","testPrompt","active"]},"SessionDetails":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"page":{"type":"string"},"closedBy":{"type":["string","null"]},"siteId":{"type":["string","null"]},"websocketUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"visitorContact":{"anyOf":[{"$ref":"#/components/schemas/VisitorContact"},{"type":"null"}]},"labels":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SessionLabel"}},{"type":"null"}]},"closedByType":{"type":"string"},"conversationLanguage":{"type":["string","null"],"description":"Language tag when available; null for a durable archived-owner read without live language state."},"aiUsage":{"$ref":"#/components/schemas/AiUsage"},"aiTurnProgress":{"$ref":"#/components/schemas/AiTurnProgress"}},"required":["sessionId","status","page","closedBy","siteId","websocketUrl","createdAt","lastActivityAt","closedAt","participants","messages","visitorContact","labels","conversationLanguage"]},"VisitorContact":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"timezone":{"type":["string","null"]}},"required":["name","email","phone","timezone"]},"AiUsage":{"type":"object","properties":{"model":{"type":["string","null"]},"location":{"type":["string","null"]},"trafficType":{"type":["string","null"]},"providerRequests":{"type":"integer","format":"int64"},"promptTokens":{"type":"integer","format":"int64"},"cachedInputTokens":{"type":"integer","format":"int64"},"candidateTokens":{"type":"integer","format":"int64"},"thoughtsTokens":{"type":"integer","format":"int64"},"toolUsePromptTokens":{"type":"integer","format":"int64"},"totalTokens":{"type":"integer","format":"int64"}},"required":["model","location","trafficType","providerRequests","promptTokens","cachedInputTokens","candidateTokens","thoughtsTokens","toolUsePromptTokens","totalTokens"]},"AiTurnProgress":{"type":"object","properties":{"version":{"type":"integer"},"scope":{"type":"string"},"turnId":{"type":"string"},"visitorMessageSeq":{"type":"integer"},"status":{"type":"string"},"pendingEffects":{"type":"integer"}},"required":["version","scope","turnId","visitorMessageSeq","status","pendingEffects"]},"HistoryExport":{"type":"object","properties":{"exportedAt":{"type":"string","format":"date-time"},"filters":{"type":"object","properties":{"type":{"type":"string"},"scope":{"type":"string"},"contact":{"type":"string"},"site":{"type":["string","null"]},"label":{"type":["string","null"]},"q":{"type":["string","null"]},"closedFrom":{"type":["string","null"],"format":"date-time"},"closedTo":{"type":["string","null"],"format":"date-time"}}},"conversations":{"type":"array","items":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/ArchivedSession"},"session":{"$ref":"#/components/schemas/Session"},"metadata":{"$ref":"#/components/schemas/ArchivedExportMetadata"}},"required":["summary","session","metadata"]}},"totalElements":{"type":"integer","format":"int64"},"exportedElements":{"type":"integer","format":"int64"},"exportLimit":{"type":"integer","format":"int64","deprecated":true,"description":"Compatibility field equal to totalElements, not a maximum export count."},"failedSessionIds":{"type":"array","items":{"type":"string"}}},"required":["exportedAt","filters","conversations","totalElements","exportedElements","exportLimit","failedSessionIds"]},"Session":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"page":{"type":"string"},"closedBy":{"type":["string","null"]},"siteId":{"type":["string","null"]},"websocketUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"visitorContact":{"anyOf":[{"$ref":"#/components/schemas/VisitorContact"},{"type":"null"}]},"labels":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SessionLabel"}},{"type":"null"}]}},"required":["sessionId","status","page","closedBy","siteId","websocketUrl","createdAt","lastActivityAt","closedAt","participants","messages","visitorContact","labels"]},"ArchivedExportMetadata":{"type":"object","properties":{"repId":{"type":["string","null"]},"orgId":{"type":["string","null"]},"standinId":{"type":["string","null"]},"closedByType":{"type":["string","null"]},"modelName":{"type":["string","null"]},"visitorTimezone":{"type":["string","null"]},"followupReason":{"type":["string","null"]},"greetingVariantId":{"type":["string","null"]},"handledBy":{"type":"string","enum":["rep","agent"]},"inputTokens":{"type":["integer","null"]},"outputTokens":{"type":["integer","null"]},"followupRequested":{"type":"boolean"},"greetingConversationStarted":{"type":"boolean"}},"required":["repId","orgId","standinId","closedByType","modelName","visitorTimezone","followupReason","greetingVariantId","handledBy","inputTokens","outputTokens","followupRequested","greetingConversationStarted"]},"StandinProfile":{"type":"object","properties":{"standinProfileId":{"type":["string","null"]},"repId":{"type":["string","null"]},"name":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayBrandName":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"greeting":{"type":["string","null"]},"prompt":{"type":["string","null"]},"toolsEnabled":{"type":["string","null"]},"siteId":{"type":["string","null"]},"pathPrefix":{"type":"string"},"enabled":{"type":"boolean"},"deleted":{"type":"boolean"},"hasSessions":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"starterQuestions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":4,"description":"Normalized questions visitors can tap for their first message, in display order. An empty array means none. Older responses may omit this field."},"suggestNextQuestions":{"type":"boolean","description":"Whether the Stand-in offers up to two follow-up questions after a reply. Older responses may omit this field; treat omission as false."}},"required":["standinProfileId","repId","name","displayName","displayBrandName","avatarUrl","greeting","prompt","toolsEnabled","siteId","pathPrefix","enabled","deleted","hasSessions","createdAt"]},"StandinProfileInput":{"type":"object","properties":{"name":{"type":"string","description":"Internal name. Required on both create and update.","minLength":1,"maxLength":255,"pattern":"\\S"},"displayName":{"type":"string","description":"Visitor-facing name. Required on both create and update.","minLength":1,"maxLength":255,"pattern":"\\S"},"prompt":{"type":"string","description":"Complete instructions. Required and nonblank. The effective plan imposes a character limit: 4,000 on Base/Pro and 8,000 on Business.","minLength":1,"pattern":"\\S"},"displayBrandName":{"type":["string","null"],"maxLength":255,"description":"Omission, null or blank clears the brand name. Trimmed length must be at most 255 characters."},"avatarUrl":{"type":["string","null"],"maxLength":255,"description":"On update, omission or null preserves the avatar; an explicit blank string clears it. On create, omission means no avatar."},"greeting":{"type":["string","null"],"description":"Complete greeting; omission or null clears it."},"toolsEnabled":{"type":["string","null"],"contentMediaType":"application/json","contentSchema":{"type":"object","additionalProperties":true},"description":"A string containing exactly one valid JSON object, not an object-valued request field. Omission or null resets it to the string {}. Malformed JSON, scalars and arrays return 400."},"siteId":{"type":["string","null"],"description":"Site in your organization. Omission, null or blank removes the site restriction."},"pathPrefix":{"type":["string","null"],"description":"URL path restriction on siteId; requires a nonblank siteId when nonblank. Omission, null or blank resets to the whole site."},"starterQuestions":{"type":["array","null"],"items":{"type":["string","null"]},"description":"Optional first-message questions. The server strips leading/trailing whitespace, collapses inner whitespace, drops null/blank entries and removes case-insensitive duplicates while retaining order. After normalization, at most 4 questions of at most 60 Unicode code points each are allowed; otherwise 400 BAD_REQUEST. Raw array size and string length are not the normalized limits. On create, omission/null means []; on update, omission/null preserves the saved questions and [] clears them."},"suggestNextQuestions":{"type":["boolean","null"],"description":"Offers up to two follow-up questions after each Stand-in reply. On create, omission/null defaults to false; on update, omission/null preserves the saved setting. Set false explicitly to turn it off."}},"required":["name","displayName","prompt"],"allOf":[{"if":{"required":["pathPrefix"],"properties":{"pathPrefix":{"type":"string","pattern":"\\S"}}},"then":{"required":["siteId"],"properties":{"siteId":{"type":"string","pattern":"\\S"}}}}],"examples":[{"name":"Website help","displayName":"Alex","displayBrandName":"Example","avatarUrl":null,"greeting":"How can I help?","prompt":"Answer questions about our public help pages.","toolsEnabled":"{}","siteId":"site-id-from-listSites","pathPrefix":"/help","starterQuestions":["How does setup work?"],"suggestNextQuestions":false}]},"KnowledgeBaseOverview":{"type":"object","properties":{"planCode":{"type":["string","null"]},"planName":{"type":["string","null"]},"capabilities":{"$ref":"#/components/schemas/KnowledgeBaseCapabilities"},"usage":{"$ref":"#/components/schemas/KnowledgeBaseUsage"},"limitsReached":{"type":"array","items":{"type":"string"}},"createAllowed":{"type":"boolean"},"ingestionAllowed":{"type":"boolean"},"graceReadOnly":{"type":"boolean"},"businessAllowed":{"type":"boolean"},"ingestionUnavailableReason":{"type":["string","null"]},"knowledgeBases":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBase"}},"maxPagesPerCrawl":{"type":"integer"},"maxPagesPerSitemap":{"type":"integer"},"maxAttachedPerAgent":{"type":"integer"},"quota":{"$ref":"#/components/schemas/KnowledgeBaseQuota"}},"required":["planCode","planName","capabilities","usage","limitsReached","createAllowed","ingestionAllowed","graceReadOnly","businessAllowed","ingestionUnavailableReason","knowledgeBases","maxPagesPerCrawl","maxPagesPerSitemap","maxAttachedPerAgent","quota"]},"KnowledgeBaseCapabilities":{"type":"object","properties":{"knowledgeBaseCountLimit":{"type":["integer","null"]},"pageCountLimit":{"type":["integer","null"]},"storageBytesLimit":{"type":["integer","null"]},"storageLimitAdvertised":{"type":"boolean"},"documentUploadAllowed":{"type":"boolean"},"sitemapAllowed":{"type":"boolean"},"automaticRefreshAllowed":{"type":"boolean"},"maxAttachedPerAgent":{"type":"integer"}},"required":["knowledgeBaseCountLimit","pageCountLimit","storageBytesLimit","storageLimitAdvertised","documentUploadAllowed","sitemapAllowed","automaticRefreshAllowed","maxAttachedPerAgent"]},"KnowledgeBaseUsage":{"type":"object","properties":{"knowledgeBaseCount":{"type":"integer"},"pageCount":{"type":"integer"},"storageBytes":{"type":"integer"}},"required":["knowledgeBaseCount","pageCount","storageBytes"]},"KnowledgeBase":{"type":"object","properties":{"knowledgeBaseId":{"type":"string"},"orgId":{"type":"string"},"ownerRepId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"ownedByCurrentRep":{"type":"boolean"},"pagesIngested":{"type":"integer"},"storageBytes":{"type":"integer"},"attachedAgentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["knowledgeBaseId","orgId","ownerRepId","name","description","ownedByCurrentRep","pagesIngested","storageBytes","attachedAgentCount","createdAt","updatedAt"]},"KnowledgeBaseQuota":{"type":"object","properties":{"storageBytesUsed":{"type":"integer"},"storageBytesLimit":{"type":["integer","null"]},"uploadBytesUsed":{"type":"integer"},"uploadBytesLimit":{"type":["integer","null"]}},"required":["storageBytesUsed","storageBytesLimit","uploadBytesUsed","uploadBytesLimit"]},"KnowledgeBaseCreate":{"type":"object","properties":{"name":{"type":"string","description":"Required nonblank name; at most 255 UTF-16 code units after stripping surrounding Java whitespace."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description, including on rename. Copy the current description to preserve it."}},"required":["name"],"examples":[{"name":"Help center renamed","description":"Copy the existing description here to retain it."}]},"KnowledgeBaseIngestionTask":{"type":"object","properties":{"taskId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"taskType":{"type":"string"},"status":{"type":"string","description":"Known active states are queued and processing. Known terminal states are completed, failed, cancelled, and partially_failed. partially_failed means some work failed and must not be treated as a complete successful ingestion. Inspect errorMessage and source/document results. Poll GET /v1/knowledge-bases/{knowledgeBaseId}/tasks by taskId; cancellation is a request and unknown future states must not be assumed successful.","x-extensible-enum":["queued","processing","completed","failed","cancelled","partially_failed"]},"sourceId":{"type":["string","null"]},"currentStage":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"workerId":{"type":["string","null"]},"pipelineVersion":{"type":["string","null"]},"progressCurrent":{"type":"integer"},"progressTotal":{"type":"integer"},"retryCount":{"type":"integer"},"cancelRequested":{"type":"boolean"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["taskId","knowledgeBaseId","taskType","status","sourceId","currentStage","errorMessage","workerId","pipelineVersion","progressCurrent","progressTotal","retryCount","cancelRequested","startedAt","completedAt","createdAt","updatedAt"]},"KnowledgeBaseSource":{"type":"object","properties":{"sourceId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceType":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"},"originalFilename":{"type":["string","null"]},"originalUrl":{"type":["string","null"]},"crawlDomain":{"type":["string","null"]},"crawlUrlPrefix":{"type":["string","null"]},"crawlMaxDepth":{"type":["integer","null"]},"rawSizeBytes":{"type":"integer"},"pageCount":{"type":"integer"},"vectorCount":{"type":"integer"},"sitemapRefreshEnabled":{"type":"boolean"},"sitemapLastCheckedAt":{"type":["string","null"],"format":"date-time"},"sitemapLastSuccessAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["sourceId","knowledgeBaseId","sourceType","displayName","status","originalFilename","originalUrl","crawlDomain","crawlUrlPrefix","crawlMaxDepth","rawSizeBytes","pageCount","vectorCount","sitemapRefreshEnabled","sitemapLastCheckedAt","sitemapLastSuccessAt","createdAt","updatedAt"]},"KnowledgeBaseDocument":{"type":"object","properties":{"documentId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"status":{"type":"string"},"title":{"type":["string","null"]},"originalUrl":{"type":["string","null"]},"rawSizeBytes":{"type":"integer"},"chunkCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["documentId","knowledgeBaseId","sourceId","status","title","originalUrl","rawSizeBytes","chunkCount","createdAt","updatedAt"]},"KnowledgeBaseDocumentDetail":{"type":"object","properties":{"documentId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"status":{"type":"string"},"title":{"type":["string","null"]},"originalUrl":{"type":["string","null"]},"rawSizeBytes":{"type":"integer"},"chunkCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"text":{"type":"string"}},"required":["documentId","knowledgeBaseId","sourceId","status","title","originalUrl","rawSizeBytes","chunkCount","createdAt","updatedAt","text"]},"KnowledgeBaseChunk":{"type":"object","properties":{"chunkId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"documentId":{"type":"string"},"chunkText":{"type":"string"},"sourceUrl":{"type":["string","null"]},"chunkIndex":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Source-format-specific ingestion metadata. Keys vary by source type; consumers must not require undocumented keys."}},"required":["chunkId","knowledgeBaseId","sourceId","documentId","chunkText","sourceUrl","chunkIndex","metadata"]},"KnowledgeBaseSearch":{"type":"object","properties":{"query":{"type":"string"},"topK":{"type":"integer","default":5}},"required":["query"]},"KnowledgeBaseSearchResult":{"type":"object","properties":{"chunkId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"documentId":{"type":"string"},"chunkText":{"type":"string"},"sourceUrl":{"type":["string","null"]},"sourceName":{"type":["string","null"]},"documentTitle":{"type":["string","null"]},"score":{"type":"number"},"metadata":{"type":"object","additionalProperties":true,"description":"Source-format-specific ingestion metadata. Keys vary by source type; consumers must not require undocumented keys."}},"required":["chunkId","knowledgeBaseId","sourceId","documentId","chunkText","sourceUrl","sourceName","documentTitle","score","metadata"]},"AgentKnowledgeBases":{"type":"object","properties":{"knowledgeBaseIds":{"type":"array","items":{"type":"string"}},"maxAttached":{"type":"integer"},"planCode":{"type":["string","null"]},"capabilities":{"$ref":"#/components/schemas/KnowledgeBaseCapabilities"},"graceReadOnly":{"type":"boolean"},"businessAllowed":{"type":"boolean"}},"required":["knowledgeBaseIds","maxAttached","planCode","capabilities","graceReadOnly","businessAllowed"]},"IntegrationOverview":{"type":"object","properties":{"proAllowed":{"type":"boolean"},"businessAllowed":{"type":"boolean"},"credentialsAvailable":{"type":"boolean"},"writeToolsAvailable":{"type":"boolean"},"maxAttachedPerAgent":{"type":"integer"},"maxRuntimeToolsPerAgent":{"type":"integer"},"availableTypes":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationTypeOption"}},"integrations":{"type":"array","items":{"$ref":"#/components/schemas/Integration"}}},"required":["proAllowed","businessAllowed","credentialsAvailable","writeToolsAvailable","maxAttachedPerAgent","maxRuntimeToolsPerAgent","availableTypes","integrations"]},"IntegrationTypeOption":{"type":"object","properties":{"providerKey":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"requiredPlan":{"type":"string"},"available":{"type":"boolean"},"implemented":{"type":"boolean"}},"required":["providerKey","name","type","requiredPlan","available","implemented"]},"Integration":{"type":"object","properties":{"integrationId":{"type":"string"},"orgId":{"type":"string"},"createdByRepId":{"type":"string"},"type":{"type":"string"},"providerKey":{"type":"string"},"name":{"type":"string"},"baseUrl":{"type":"string"},"authType":{"type":"string"},"description":{"type":["string","null"]},"authHeaderName":{"type":["string","null"]},"requiredPlan":{"type":["string","null"]},"secretConfigured":{"type":"boolean"},"available":{"type":"boolean"},"toolCount":{"type":"integer"},"attachedAgentCount":{"type":"integer"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationTool"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["integrationId","orgId","createdByRepId","type","providerKey","name","baseUrl","authType","description","authHeaderName","requiredPlan","secretConfigured","available","toolCount","attachedAgentCount","tools","createdAt","updatedAt"]},"IntegrationTool":{"type":"object","properties":{"toolKey":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"httpMethod":{"type":"string"},"path":{"type":"string"},"readOnly":{"type":"boolean"},"inputSchema":{"type":"object","additionalProperties":true,"description":"Imported JSON Schema describing this tool input. Its properties come from the customer OpenAPI document."},"executionConfig":{"$ref":"#/components/schemas/IntegrationExecutionConfig"},"toolId":{"type":"string"},"integrationId":{"type":"string"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["toolKey","summary","description","httpMethod","path","readOnly","inputSchema","executionConfig","toolId","integrationId","enabled","createdAt","updatedAt"]},"IntegrationExecutionConfig":{"type":"object","properties":{"parameters":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string"},"name":{"type":"string"},"in":{"type":"string"},"collectionFormat":{"type":"string"}},"required":["property","name","in"]}},"bodyProperty":{"type":"string"},"contentType":{"type":"string"}},"required":["parameters"]},"IntegrationPreview":{"type":"object","properties":{"providerKey":{"type":"string"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationToolPreview"}},"maxDocumentChars":{"type":"integer"},"maxOperations":{"type":"integer"},"maxSchemaDepth":{"type":"integer"},"maxDescriptionChars":{"type":"integer"}},"required":["providerKey","tools","maxDocumentChars","maxOperations","maxSchemaDepth","maxDescriptionChars"]},"IntegrationToolPreview":{"type":"object","properties":{"toolKey":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"httpMethod":{"type":"string"},"path":{"type":"string"},"readOnly":{"type":"boolean"},"inputSchema":{"type":"object","additionalProperties":true,"description":"Imported JSON Schema describing this tool input. Its properties come from the customer OpenAPI document."},"executionConfig":{"$ref":"#/components/schemas/IntegrationExecutionConfig"}},"required":["toolKey","summary","description","httpMethod","path","readOnly","inputSchema","executionConfig"]},"OpenApiIntegrationSource":{"type":"object","properties":{"openApiDocument":{"type":"string"}},"required":["openApiDocument"]},"IntegrationCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Required on create and update. Trimmed name is limited to 120 characters."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description; normalized content is truncated to 1,000 characters."},"baseUrl":{"type":"string","minLength":1,"pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^\\s/?#@]+(?:/[^\\s?#]*)?\\s*$","description":"Required public HTTP(S) base URL, without credentials, query or fragment. Public-address/DNS safety and port validity are checked by the server. Authenticated integrations require HTTPS."},"authType":{"type":["string","null"],"pattern":"^\\s*(?:[nN][oO][nN][eE]|[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC]|)\\s*$","description":"Supported values: none, bearer, api_key_header, basic (trimmed and case-insensitive). Omission, null or blank means none, including on update: this removes existing authentication."},"authHeaderName":{"type":["string","null"],"description":"Required for api_key_header. Valid non-reserved HTTP header token, at most 120 characters after trimming; ignored for other authentication types."},"authUsername":{"type":["string","null"],"description":"Required with a new basic-auth secret; nonblank, at most 512 UTF-16 code units, without colon or control characters. Omit when preserving stored credentials."},"authSecret":{"type":["string","null"],"writeOnly":true,"description":"Required for non-none authentication on create. On update, omit/null/blank preserves the stored secret only when authentication type, baseUrl and header are unchanged and no username is supplied; otherwise a replacement secret is required. Never log it."},"openApiDocument":{"type":"string","minLength":1,"pattern":"\\S","description":"OpenAPI JSON or YAML declaration as a string. Required and nonblank on create. On update, a nonblank value replaces the source and tools; omission/null/blank preserves them. Parser limits and operation validity are checked by the server."},"enabledToolKeys":{"type":["array","null"],"items":{"type":["string","null"]},"description":"Legacy selection fallback used only if selectedTools has no nonblank tool keys. At least one selected operation must exist in the declaration; at most 50 distinct tools. Omit or send [] when retaining tools on update."},"selectedTools":{"type":["array","null"],"items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"description":"Selected tool keys and optional read-only classifications. Nonblank keys take precedence over enabledToolKeys; null/blank entries are ignored. Keys must be returned by previewOpenApiIntegration. Omit or send [] when retaining tools on update."}},"required":["name","baseUrl","openApiDocument"],"allOf":[{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},"then":{"properties":{"baseUrl":{"type":"string","pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]://"}}}},{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR])\\s*$"}}},"then":{"required":["authHeaderName"],"properties":{"authHeaderName":{"type":"string","minLength":1,"pattern":"^\\s*[A-Za-z0-9!#$%&'*+.^_`|~-]+\\s*$"}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"required":["authUsername"],"properties":{"authUsername":{"type":"string","minLength":1,"pattern":"^[^:\\u0000-\\u001f\\u007f-\\u009f]*[^\\s:\\u0000-\\u001f\\u007f-\\u009f][^:\\u0000-\\u001f\\u007f-\\u009f]*$"}}}},{"anyOf":[{"required":["selectedTools"],"properties":{"selectedTools":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"contains":{"type":"object","properties":{"toolKey":{"type":"string","minLength":1,"pattern":"\\S"}},"required":["toolKey"]}}}},{"required":["enabledToolKeys"],"properties":{"enabledToolKeys":{"type":"array","items":{"type":["string","null"]},"contains":{"type":"string","minLength":1,"pattern":"\\S"}}}}]},{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},"then":{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}}],"examples":[{"name":"Orders","description":"Read order information","baseUrl":"https://example.com","authType":"none","openApiDocument":"{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Orders\",\"version\":\"1.0.0\"},\"paths\":{\"/orders\":{\"get\":{\"operationId\":\"listOrders\",\"responses\":{\"200\":{\"description\":\"Order list\"}}}}}}","selectedTools":[{"toolKey":"listOrders","readOnly":true}]}]},"AgentIntegrations":{"type":"object","properties":{"integrationIds":{"type":"array","items":{"type":"string"}},"maxAttached":{"type":"integer"},"proAllowed":{"type":"boolean"},"businessAllowed":{"type":"boolean"}},"required":["integrationIds","maxAttached","proAllowed","businessAllowed"]},"OptionalLapelPin":{"type":"object","properties":{"lapelPin":{"anyOf":[{"$ref":"#/components/schemas/LapelPin"},{"type":"object","properties":{},"maxProperties":0}],"description":"An empty object denotes no configured pin; it is not null."}},"required":["lapelPin"]},"AgentSkill":{"type":"object","properties":{"skillKey":{"type":"string"},"enabled":{"type":"boolean"},"available":{"type":"boolean"},"requiredPlan":{"type":["string","null"]},"limit":{"type":["integer","null"]},"config":{"$ref":"#/components/schemas/AgentSkillConfig"}},"required":["skillKey","enabled","available","requiredPlan","limit","config"]},"AgentSkillConfig":{"type":"object","properties":{"guidance":{"type":"string"},"recipientEmail":{"type":"string"},"candidateCriteria":{"type":"string"},"learningGoal":{"type":"string"},"avoid":{"type":"string"},"interviewDepth":{"type":"string"},"learningQuestions":{"type":"array","items":{"type":"string"}},"maxQuestions":{"type":"integer"},"notify":{"type":"boolean"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkillLabel"}},"maxActiveLabels":{"type":"integer"}}},"AgentSkillLabel":{"type":"object","properties":{"labelId":{"type":"string"},"name":{"type":"string"},"prompt":{"type":"string"},"testPrompt":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"effectiveActive":{"type":"boolean"},"notify":{"type":"boolean"}},"required":["labelId","name","prompt","testPrompt","position","active","effectiveActive","notify"]},"AgentSkillUpdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"config":{"anyOf":[{"$ref":"#/components/schemas/AgentSkillConfigInput"},{"type":"null"}],"description":"Omission/null preserves current configuration. followup merges supplied keys; customerDiscovery replaces configuration and normalizes omitted fields to defaults. labeling preserves labels unless config.labels is supplied, which replaces the full set ([] clears)."}},"required":["enabled"],"examples":[{"enabled":true},{"enabled":true,"config":{"labels":[{"labelId":"existing-label-id","name":"Pricing","prompt":"The visitor asks about pricing.","active":true,"notify":false}]}}]},"AgentSkillConfigInput":{"type":"object","properties":{"guidance":{"type":"string"},"recipientEmail":{"type":"string"},"candidateCriteria":{"type":"string"},"learningGoal":{"type":"string"},"avoid":{"type":"string"},"interviewDepth":{"type":"string"},"learningQuestions":{"type":"array","items":{"type":"string"}},"maxQuestions":{"type":"integer"},"notify":{"type":"boolean"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkillLabelInput"}},"maxActiveLabels":{"type":"integer"}}},"AgentSkillLabelInput":{"type":"object","properties":{"labelId":{"type":["string","null"]},"name":{"type":"string","minLength":1,"maxLength":80,"pattern":"\\S"},"prompt":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"},"testPrompt":{"description":"Legacy prompt alias, used only when prompt is absent. Ignored when prompt is present, even if this alias is null or another JSON type."},"active":{"type":"boolean"},"notify":{"type":"boolean"}},"required":["name"],"if":{"required":["prompt"]},"then":{"required":["prompt"]},"else":{"required":["testPrompt"],"properties":{"testPrompt":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"}}}},"AvatarCandidates":{"type":"object","properties":{"candidates":{"type":"array","items":{"type":"object","properties":{"candidateId":{"type":"string"},"url":{"type":"string"}},"required":["candidateId","url"]}}},"required":["candidates"]},"StatsResponse":{"type":"object","properties":{"scope":{"type":"string"},"scopeId":{"type":"string"},"bucketType":{"type":"string"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/StatsBucket"}}},"required":["scope","scopeId","bucketType","buckets"]},"StatsBucket":{"type":"object","properties":{"bucketKey":{"type":"string"},"opportunity":{"type":"integer","format":"int64"},"show":{"type":"integer","format":"int64"},"activate":{"type":"integer","format":"int64"},"chatStart":{"type":"integer","format":"int64"},"sessionLengthSum":{"type":"integer","format":"int64"},"sessionLengthCount":{"type":"integer","format":"int64"}},"required":["bucketKey","opportunity","show","activate","chatStart","sessionLengthSum","sessionLengthCount"]},"LiveShowsResponse":{"type":"object","properties":{"shows":{"type":"integer","format":"int64"},"windowSeconds":{"type":"integer"},"coveredSiteCount":{"type":"integer"},"asOf":{"type":"string","format":"date-time"}},"required":["shows","windowSeconds","coveredSiteCount","asOf"]},"OrgUsage":{"type":"object","properties":{"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"chatCount":{"type":"integer"},"overageCount":{"type":"integer"},"chatsBalance":{"type":"integer"},"chatQuota":{"type":["integer","null"]},"periodType":{"type":["string","null"]},"accountBalanceCents":{"type":"integer","description":"Owner-only; omitted for members."}},"required":["periodStart","periodEnd","chatCount","overageCount","chatsBalance","chatQuota","periodType"]},"OrgPlan":{"type":"object","properties":{"planCode":{"type":"string"},"name":{"type":"string"},"planVersion":{"type":"integer"},"chatQuota":{"type":["integer","null"]},"periodType":{"type":["string","null"]},"priceCents":{"type":"integer"},"overageCents":{"type":"integer"},"promptCharacterLimit":{"type":"integer"},"billingCycle":{"type":"string"}},"required":["planCode","planVersion","name","chatQuota","periodType","promptCharacterLimit"]},"SiteUpdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"name":{"type":"string","maxLength":255},"defaultLanguageCode":{"type":["string","null"]},"embedOptions":{"$ref":"#/components/schemas/SiteEmbedOptionsUpdate","description":"Legacy compatibility input. On update, any supplied embedOptions object, including embedOptions: {}, merges supplied keys into the saved legacy options and then replaces behaviorConfig: advancedBehaviorEnabled and allowStandAdminBehavior become false, and all existing rules, including custom JavaScript rules, are replaced by zero or one legacy-default rule derived from the merged options. An explicit behaviorConfig in the same request is applied after this conversion and controls the final configuration. Owner-consent validation uses the committed configuration before any sibling mutation; all fields are validated before saving. For behavior edits, modern clients should read the Site and replace the complete behaviorConfig with both switches and every retained rule."},"behaviorConfig":{"$ref":"#/components/schemas/SiteBehaviorConfigInput"}},"anyOf":[{"required":["enabled"]},{"required":["name"]},{"required":["defaultLanguageCode"]},{"required":["embedOptions"]},{"required":["behaviorConfig"]}]},"SitePreferencesUpdate":{"type":"object","properties":{"siteIds":{"type":"array","items":{"type":"string"}}},"required":["siteIds"]},"DigestAiPreferencesUpdate":{"type":"object","properties":{"aiEnabled":{"type":"boolean"},"labels":{"type":["array","null"],"items":{"type":"object","properties":{"labelId":{"type":["string","null"]},"name":{"type":"string"},"testPrompt":{"type":"string"}},"required":["name","testPrompt"]},"maxItems":10,"description":"Complete replacement label set. Omission or null clears all labels unless the legacy tripwires field is used when labels is absent. [] explicitly clears. Preserve each current labelId, name and testPrompt to retain it."},"tripwires":{"description":"Legacy fallback used only when labels is absent; ignored when labels is present. Prefer labels."}},"required":["aiEnabled"],"if":{"not":{"required":["labels"]}},"then":{"properties":{"tripwires":{"type":["array","null"],"items":{"type":"object","properties":{"labelId":{"type":["string","null"]},"name":{"type":"string"},"testPrompt":{"type":"string"}},"required":["name","testPrompt"]},"maxItems":10}}},"examples":[{"aiEnabled":true,"labels":[{"labelId":"existing-label-id","name":"Pricing","testPrompt":"The visitor asks about pricing."}]}]},"KnowledgeBaseUpsert":{"type":"object","properties":{"name":{"type":"string","description":"Required nonblank name; at most 255 UTF-16 code units after stripping surrounding Java whitespace."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description, including on rename. Copy the current description to preserve it."}},"required":["name"],"examples":[{"name":"Help center renamed","description":"Copy the existing description here to retain it."}]},"IntegrationUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Required on create and update. Trimmed name is limited to 120 characters."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description; normalized content is truncated to 1,000 characters."},"baseUrl":{"type":"string","minLength":1,"pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^\\s/?#@]+(?:/[^\\s?#]*)?\\s*$","description":"Required public HTTP(S) base URL, without credentials, query or fragment. Public-address/DNS safety and port validity are checked by the server. Authenticated integrations require HTTPS."},"authType":{"type":["string","null"],"pattern":"^\\s*(?:[nN][oO][nN][eE]|[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC]|)\\s*$","description":"Supported values: none, bearer, api_key_header, basic (trimmed and case-insensitive). Omission, null or blank means none, including on update: this removes existing authentication."},"authHeaderName":{"type":["string","null"],"description":"Required for api_key_header. Valid non-reserved HTTP header token, at most 120 characters after trimming; ignored for other authentication types."},"authUsername":{"type":["string","null"],"description":"Required with a new basic-auth secret; nonblank, at most 512 UTF-16 code units, without colon or control characters. Omit when preserving stored credentials."},"authSecret":{"type":["string","null"],"writeOnly":true,"description":"Required for non-none authentication on create. On update, omit/null/blank preserves the stored secret only when authentication type, baseUrl and header are unchanged and no username is supplied; otherwise a replacement secret is required. Never log it."},"openApiDocument":{"type":["string","null"],"description":"OpenAPI JSON or YAML declaration as a string. Required and nonblank on create. On update, a nonblank value replaces the source and tools; omission/null/blank preserves them. Parser limits and operation validity are checked by the server."},"enabledToolKeys":{"type":["array","null"],"items":{"type":["string","null"]},"description":"Legacy selection fallback used only if selectedTools has no nonblank tool keys. At least one selected operation must exist in the declaration; at most 50 distinct tools. Omit or send [] when retaining tools on update."},"selectedTools":{"type":["array","null"],"items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"description":"Selected tool keys and optional read-only classifications. Nonblank keys take precedence over enabledToolKeys; null/blank entries are ignored. Keys must be returned by previewOpenApiIntegration. Omit or send [] when retaining tools on update."}},"required":["name","baseUrl"],"allOf":[{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},"then":{"properties":{"baseUrl":{"type":"string","pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]://"}}}},{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR])\\s*$"}}},"then":{"required":["authHeaderName"],"properties":{"authHeaderName":{"type":"string","minLength":1,"pattern":"^\\s*[A-Za-z0-9!#$%&'*+.^_`|~-]+\\s*$"}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"required":["authUsername"],"properties":{"authUsername":{"type":"string","minLength":1,"pattern":"^[^:\\u0000-\\u001f\\u007f-\\u009f]*[^\\s:\\u0000-\\u001f\\u007f-\\u009f][^:\\u0000-\\u001f\\u007f-\\u009f]*$"}}}},{"if":{"required":["openApiDocument"],"properties":{"openApiDocument":{"type":"string","minLength":1,"pattern":"\\S"}}},"then":{"anyOf":[{"required":["selectedTools"],"properties":{"selectedTools":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"contains":{"type":"object","properties":{"toolKey":{"type":"string","minLength":1,"pattern":"\\S"}},"required":["toolKey"]}}}},{"required":["enabledToolKeys"],"properties":{"enabledToolKeys":{"type":"array","items":{"type":["string","null"]},"contains":{"type":"string","minLength":1,"pattern":"\\S"}}}}]},"else":{"properties":{"selectedTools":{"type":["array","null"],"maxItems":0},"enabledToolKeys":{"type":["array","null"],"maxItems":0}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authUsername"],"properties":{"authUsername":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}}],"examples":[{"name":"Orders renamed","description":"Read order information","baseUrl":"https://example.com","authType":"bearer"}]},"LapelPinInput":{"type":"object","properties":{"domain":{"type":["string","null"],"maxLength":255,"description":"Organization policy selector only: omission/null/blank selects the organization-wide default; a nonblank domain selects its own policy. Ignored for personal and Stand-in pins."},"pinType":{"type":["string","null"],"enum":["none","circle","pill","free",null],"description":"Omission or null resets to none, turning the pin off."},"color":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","maxLength":7},{"type":"null"}],"description":"Omission or null resets to #000000; blank is invalid."},"borderColor":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","maxLength":7},{"type":"string","pattern":"^[\\u0009-\\u000d\\u001c-\\u0020\\u1680\\u2000-\\u2006\\u2008-\\u200a\\u2028\\u2029\\u205f\\u3000]*$"},{"type":"null"}],"description":"Omission, null or a Java-blank string clears the color override; otherwise use #RRGGBB."},"fontFamily":{"type":["string","null"],"enum":["Arial","Verdana","Helvetica","Tahoma","Trebuchet MS","Times New Roman","Georgia","Garamond","Courier New","Brush Script MT","sans-serif","serif","monospace",null],"description":"Case-sensitive font name. Omission or null resets to sans-serif."},"fontColor":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","maxLength":7},{"type":"string","pattern":"^[\\u0009-\\u000d\\u001c-\\u0020\\u1680\\u2000-\\u2006\\u2008-\\u200a\\u2028\\u2029\\u205f\\u3000]*$"},{"type":"null"}],"description":"Omission, null or a Java-blank string clears the color override; otherwise use #RRGGBB."},"pillText":{"type":["string","null"],"maxLength":255,"description":"Omission or null clears the text."},"usePinAsBotAvatar":{"type":["boolean","null"],"description":"Omission or null resets to false."}},"examples":[{"pinType":"pill","color":"#000000","borderColor":null,"fontFamily":"sans-serif","fontColor":"#ffffff","pillText":"Ask me","usePinAsBotAvatar":false}]}}}}
+{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Stand public API","version":"0.1.0","description":"Scoped API and CLI access to supported Stand account operations. Complete initial signup and profile onboarding in the browser. Current account, organization, role, ownership and plan permissions still apply. Account deletion, subscription management, team-member changes, JavaScript experimentation opt-in, MCP and WordPress/site connections are excluded."},"externalDocs":{"description":"Public API and CLI guide","url":"https://stand.chat/guide/api-cli.md"},"servers":[{"url":"https://api.stand.chat","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/reps/me":{"get":{"operationId":"getCurrentUser","summary":"Get the authenticated identity","description":"Get the authenticated identity","tags":["Account and organization"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/reps/profile":{"get":{"operationId":"getRepProfile","summary":"Get your representative profile","description":"Get your representative profile","tags":["Account and organization"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepProfileResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"updateRepProfile","summary":"Save your representative profile","description":"Update an already-completed profile using the approved complete personal details. Initial profile completion and organization creation require the existing browser onboarding. Read the current profile and preserve unrelated fields: omitted title, organization, avatarUrl and greeting clear those profile values, and omitted greetingEnabled defaults to true. Changing the organization name additionally requires org:write and organization ownership; retain the current organization value when only editing personal details. Current membership and ownership rules still apply.","tags":["Account and organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepProfileUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepProfileResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/sites":{"get":{"operationId":"listSites","summary":"List sites in your organization","description":"List Sites in the current organization, including installation snippets and whether the caller is the owner. Active organization members can read this list.","tags":["Sites"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]},"post":{"operationId":"createSite","summary":"Add a site to your organization","description":"Any active organization member can add a site. Setting either experimentation consent switch true also requires organization ownership; external clients cannot enable either switch even as owner. Returns 200. Response includes installation HTML containing the public site ID, never a user credential. External clients must create the Site with advancedBehaviorEnabled and allowStandAdminBehavior false (or omit behaviorConfig); an owner request with either switch true returns 403 EXPERIMENTATION_CONSENT_REQUIRED before creation, while other callers remain subject to ownership checks. Stored script source remains inert until owner enablement in the dashboard.","tags":["Sites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCreate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/sites/{siteId}":{"put":{"operationId":"updateSite","summary":"Update site settings","description":"Owner only. enabled, name and defaultLanguageCode change only when supplied. A supplied behaviorConfig replaces the entire configuration, including all rules. Legacy compatibility input. On update, any supplied embedOptions object, including embedOptions: {}, merges supplied keys into the saved legacy options and then replaces behaviorConfig: advancedBehaviorEnabled and allowStandAdminBehavior become false, and all existing rules, including custom JavaScript rules, are replaced by zero or one legacy-default rule derived from the merged options. An explicit behaviorConfig in the same request is applied after this conversion and controls the final configuration. Owner-consent validation uses the committed configuration before any sibling mutation; all fields are validated before saving. For behavior edits, modern clients should read the Site and replace the complete behaviorConfig with both switches and every retained rule. At least one recognized setting is required. A null or blank defaultLanguageCode resets the fallback language. External API/CLI clients cannot enable experimentation: advancedBehaviorEnabled may remain true only when it is already enabled for that Site. The organization owner enables it in the Stand dashboard under Sites > Chat widget behavior > Experimentation (Advanced), after accepting the warning. Once enabled, owner-authorized OAuth clients with sites:write may add, edit and activate custom JavaScript rules. Disabling it strips custom JavaScript from subsequent visitor behavior responses; stored source can be retained or edited while disabled but cannot execute. API clients may disable it but cannot re-enable it, even with an unconditional configuration replacement. They also cannot grant Stand-admin experimentation access. A denied enablement returns 403 EXPERIMENTATION_CONSENT_REQUIRED with no sibling changes. Reload the Site after the owner changes consent; broader scopes or another login cannot enable it.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteSite","summary":"Delete a site","description":"Delete a site","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]},"get":{"operationId":"getSite","summary":"Read one site in your organization","description":"Active members of its organization can read it. Missing and foreign Sites return the same 404 NOT_FOUND.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]}},"/v1/sites/matches":{"get":{"operationId":"listSiteMatches","summary":"List eligible responders by site","description":"Read current representative and Stand-in routing matches for Sites in the current organization. This is configuration and availability evidence, not a completed visitor chat.","tags":["Sites"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMatches"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]}},"/v1/reps/profile/sites":{"get":{"operationId":"getRepSitePreferences","summary":"Get your chat-site selection","description":"Read your complete personal chat-site selection. siteIds null means all Sites; an explicit list selects those Sites. Both full-set replacement and a one-Site update are supported.","tags":["Sites"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"setRepSitePreferences","summary":"Replace your chat-site selection","description":"Replace your chat-site selection","tags":["Sites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferencesUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/reps/profile/sites/{siteId}":{"put":{"operationId":"setRepSitePreference","summary":"Change your chat selection for one site","description":"Changes only the named site in your personal chat selection, preserving the other sites. If never configured (siteIds null), starts from all current organization sites. The returned siteIds is the complete explicit selection; [] selects no sites. Foreign or missing site IDs return 404.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/sites/{siteId}/prompt":{"get":{"operationId":"getSitePrompt","summary":"Get the active site prompt","description":"Read the active prompt for a Site in your organization; organization members can read it.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"anyOf":[{"$ref":"#/components/schemas/SitePrompt"},{"type":"null"}]}},"required":["prompt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateSitePrompt","summary":"Replace the site prompt","description":"Replace the prompt for a Site in your organization. Requires the organization owner.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePrompt"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteSitePrompt","summary":"Clear the site prompt","description":"Clear the active prompt for a Site in your organization. Requires the organization owner.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"sites:write","security":[{"bearerAuth":[]}]}},"/v1/sites/{siteId}/prompt/history":{"get":{"operationId":"listSitePromptHistory","summary":"List site prompt revisions","description":"Existing account API value.","tags":["Sites"],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"type":"array","items":{"$ref":"#/components/schemas/SitePrompt"}}},"required":["prompts"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sites:read","security":[{"bearerAuth":[]}]}},"/v1/orgs/{orgId}/prompt":{"get":{"operationId":"getOrganizationPrompt","summary":"Get the active organization prompt","description":"Get the active organization prompt","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"anyOf":[{"$ref":"#/components/schemas/OrgPrompt"},{"type":"null"}]}},"required":["prompt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateOrganizationPrompt","summary":"Replace the organization prompt","description":"Replace the organization prompt","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrompt"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteOrganizationPrompt","summary":"Clear the organization prompt","description":"Clear the organization prompt","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/orgs/{orgId}/prompt/history":{"get":{"operationId":"listOrganizationPromptHistory","summary":"List organization prompt revisions","description":"Existing account API value.","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"type":"array","items":{"$ref":"#/components/schemas/OrgPrompt"}}},"required":["prompts"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/orgs/{orgId}/privacy-settings":{"get":{"operationId":"getOrganizationPrivacy","summary":"Get organization privacy settings","description":"Get organization privacy settings","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrivacy"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateOrganizationPrivacy","summary":"Save organization privacy settings","description":"Save organization privacy settings","tags":["Account and organization"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrivacyUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPrivacy"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/archived":{"get":{"operationId":"listArchivedSessions","summary":"Search archived conversations","description":"Conversations visible to the authenticated rep. sites and labels filter metadata are populated only on page zero. Test conversations are excluded. Pagination is offset-based; concurrent changes can shift results.","tags":["Conversations"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based page. page × size must not exceed 2147483647."},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["all","rep","agent"],"default":"all"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["myself","org"],"default":"myself"},"description":"Organization scope is honored only for an owner; otherwise effective scope is myself."},{"name":"site","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal substring of the stored page URL, not a site ID or exact-hostname match. A hostname can also match text elsewhere in a URL. Blank values apply no filter; inspect returned page URLs when an exact-site corpus is needed."},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","default":"closedAt"},"description":"closedAt, createdAt, page, or messageCount. Unknown values fall back to closedAt."},{"name":"sortDir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"contact","in":"query","required":false,"schema":{"type":"string","enum":["all","email","phone","any"],"default":"all"}},{"name":"label","in":"query","required":false,"schema":{"type":"string","default":"all"},"description":"Label ID or all."},{"name":"closedFrom","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant or UTC calendar date; inclusive lower bound."},{"name":"closedTo","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant (exclusive), or UTC date including the whole specified day."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal search. Leading and trailing U+0000 through U+0020 code units are removed, then the query must contain at most 200 UTF-16 code units; a supplementary Unicode character such as an emoji counts as two. An empty normalized query applies no text filter. An over-limit normalized query returns 400 BAD_REQUEST. The limit applies after normalization and is not a raw JSON Schema maxLength constraint."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchivedSessions"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read","security":[{"bearerAuth":[]}]}},"/v1/sessions":{"get":{"operationId":"listSessions","summary":"List your active conversation IDs","description":"List your active conversation IDs","tags":["Conversations"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveSessions"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/seen":{"put":{"operationId":"markSessionSeen","summary":"Mark an assigned conversation as seen","description":"Mark an assigned conversation as seen","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/messages":{"post":{"operationId":"sendMessage","summary":"Send a conversation message","description":"Requires access to the conversation as an authorized representative. Sending a message can take over a Stand-in conversation. Preserve clientMessageId when retrying this operation; no general Idempotency-Key header is implemented.","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"clientMessageId":{"type":"string","description":"Caller-generated identifier for message replay protection."}},"required":["body"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}],"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write"}},"/v1/reps/me/greeting-variants":{"get":{"operationId":"listGreetingVariants","summary":"List your greeting variants","description":"List your greeting variants","tags":["Account and organization"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/GreetingVariant"}}},"required":["variants"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveGreetingVariants","summary":"Save your greeting variants","description":"At least one retained, nonblank greeting is required. Supply the complete requested variant set.","tags":["Account and organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/GreetingVariantInput"}}},"required":["variants"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/GreetingVariant"}}},"required":["variants"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/team":{"get":{"operationId":"getTeam","summary":"List organization members and pending invitations","description":"All active organization members can list members. Pending invitations are returned only to the owner. Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Team"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"team:read","security":[{"bearerAuth":[]}]}},"/v1/team/invite-provider-default":{"get":{"operationId":"getInviteProviderDefault","summary":"Suggest a required sign-in provider","description":"Returns an owner-specific provider suggestion; nonowners receive null.","tags":["Team"],"parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"requireProvider":{"type":["string","null"]}},"required":["requireProvider"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"team:read","security":[{"bearerAuth":[]}]}},"/v1/digest/preferences":{"get":{"operationId":"getDigestPreferences","summary":"Get email digest preferences","description":"Get email digest preferences","tags":["Digests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateDigestPreferences","summary":"Update email digest preferences","description":"Update email digest preferences","tags":["Digests"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestPreferencesUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:write","security":[{"bearerAuth":[]}]}},"/v1/digest/ai-preferences":{"get":{"operationId":"getDigestAiPreferences","summary":"Get conversation analytics preferences","description":"Get conversation analytics preferences","tags":["Digests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestAiPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateDigestAiPreferences","summary":"Save conversation analytics preferences","description":"Replaces AI preferences and the entire label set. First read getDigestAiPreferences and copy every labelId, name and testPrompt to keep before changing aiEnabled or a label. Omitted/null labels or [] removes all labels; tripwires is a legacy fallback only when labels is absent. The example assumes the retained label belongs to this representative. This is not a partial PATCH.","tags":["Digests"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestAiPreferencesUpdate"}}}},"responses":{"200":{"description":"Saved preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestAiPreferences"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Current plan does not permit enabling AI analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:write","security":[{"bearerAuth":[]}]}},"/v1/digest/send-now":{"post":{"operationId":"sendDigestNow","summary":"Email your last seven days of conversations","description":"Sends email to the authenticated representative. A concurrent request returns 409; requests within the 60-second cooldown return 429 RATE_LIMIT_EXCEEDED with Retry-After set to the remaining cooldown, rounded up to whole seconds. Do not automatically retry after an ambiguous failure.","tags":["Digests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"to":{"type":"string"},"period":{"type":"string"}},"required":["sent","to","period"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"digest:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}":{"get":{"operationId":"getSession","summary":"Get a conversation and recent messages","description":"An active organization owner can read a durable closed conversation in their own organization, including a teammate's conversation. Other representative reads remain assignment-based; this archived-owner read grants no live-session or mutation access. messageLimit defaults to 200, clamps at 500 and accepts zero for no messages. Archived owner reads use retained/redacted durable data and do not supply live AI usage or turn progress. aiTurnProgress on eligible live reads is optional diagnostic data, not a durable completion guarantee.","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"messageLimit","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":200},"description":"Server clamps values above 500. Zero fetches no messages."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetails"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}],"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read"},"delete":{"operationId":"closeSession","summary":"Close a conversation","description":"Closes a session authorized for the caller. The response reports the persisted closing identity, which can differ from this caller after a race.","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"closedBy":{"type":"string"},"closedByType":{"type":"string"},"closedAt":{"type":"string","format":"date-time"}},"required":["sessionId","status","closedBy","closedByType","closedAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}],"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write"}},"/v1/sessions/archived/export":{"get":{"operationId":"exportArchivedSessions","summary":"Export matching archived conversations as JSON","description":"Streams one JSON document, not NDJSON. Membership is frozen for this export. Check failedSessionIds and exportedElements, and reject truncated or invalid JSON even after HTTP 200. Resource admission may reject the request; there is no fixed conversation-count cap.","tags":["Conversations"],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["all","rep","agent"],"default":"all"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["myself","org"],"default":"myself"},"description":"Organization scope is honored only for an owner; otherwise effective scope is myself."},{"name":"site","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal substring of the stored page URL, not a site ID or exact-hostname match. A hostname can also match text elsewhere in a URL. Blank values apply no filter; inspect returned page URLs when an exact-site corpus is needed."},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","default":"closedAt"},"description":"closedAt, createdAt, page, or messageCount. Unknown values fall back to closedAt."},{"name":"sortDir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"contact","in":"query","required":false,"schema":{"type":"string","enum":["all","email","phone","any"],"default":"all"}},{"name":"label","in":"query","required":false,"schema":{"type":"string","default":"all"},"description":"Label ID or all."},{"name":"closedFrom","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant or UTC calendar date; inclusive lower bound."},{"name":"closedTo","in":"query","required":false,"schema":{"type":"string"},"description":"ISO instant (exclusive), or UTC date including the whole specified day."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive literal search. Leading and trailing U+0000 through U+0020 code units are removed, then the query must contain at most 200 UTF-16 code units; a supplementary Unicode character such as an emoji counts as two. An empty normalized query applies no text filter. An over-limit normalized query returns 400 BAD_REQUEST. The limit applies after normalization and is not a raw JSON Schema maxLength constraint."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryExport"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:read","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/handoff":{"post":{"operationId":"takeOverSession","summary":"Take over a Stand-in conversation","description":"Take over a Stand-in conversation","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"takenOver":{"type":"boolean"}},"required":["sessionId","takenOver"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write","security":[{"bearerAuth":[]}]}},"/v1/sessions/{sessionId}/handoff/offer":{"post":{"operationId":"offerSessionHandoff","summary":"Offer to join a Stand-in conversation","description":"Offer to join a Stand-in conversation","tags":["Conversations"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"offered":{"type":"boolean"}},"required":["sessionId","offered"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"sessions:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins":{"get":{"operationId":"listStandins","summary":"List your Stand-ins","description":"List your Stand-ins, including those restricted to a Site and those available across all Sites. Both kinds can be managed with the corresponding write permission.","tags":["Account and organization"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"standins":{"type":"array","items":{"$ref":"#/components/schemas/StandinProfile"}}},"required":["standins"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]},"post":{"operationId":"createStandin","summary":"Create a Stand-in","description":"Creates a new disabled Stand-in. Supply name, displayName and prompt; optional fields use the defaults described in StandinProfileInput. Retain standinProfileId from the response, attach any knowledge or integrations, then enable explicitly.","tags":["Account and organization"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfileInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}":{"get":{"operationId":"getStandin","summary":"Get your Stand-in","description":"Read one of your Stand-ins, including its current configuration and public identifier.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateStandin","summary":"Update your Stand-in","description":"Replaces profile fields; this is not a partial PATCH. Read getStandin, copy name, displayName, displayBrandName, avatarUrl, greeting, prompt, toolsEnabled, siteId and pathPrefix into the request, then edit the intended values. The schema example also includes the optional question settings. Omitted brand/greeting/site/path fields clear or reset and omitted toolsEnabled resets to the string {}; omitted/null avatarUrl preserves the avatar. Omitted/null starterQuestions and suggestNextQuestions preserve their saved values; [] clears the starter questions and false turns off follow-up questions. Clone and history-preserving version replacement retain both question settings. Enabled state is preserved. If the Stand-in has durable conversation history, the update creates a new version, disables/hides the previous version and returns a different standinProfileId. Always retain the returned ID for subsequent requests; historical conversations keep their original version.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfileInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteStandin","summary":"Delete your Stand-in","description":"Changes an owned Stand-in; current account and resource permissions apply.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Completed without a response body"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/enabled":{"post":{"operationId":"setStandinEnabled","summary":"Enable or disable your Stand-in","description":"Changes an owned Stand-in; current account and resource permissions apply.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/clone":{"post":{"operationId":"cloneStandin","summary":"Clone your Stand-in","description":"Creates a separate disabled copy with a new standinProfileId. The source Stand-in is unchanged. Retain the returned ID, review the copy and enable it explicitly.","tags":["Account and organization"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandinProfile"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Copying the source Stand-in's attached knowledge can be denied by the effective knowledge-base plan, attachment limit or grace state. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases":{"get":{"operationId":"listKnowledgeBases","summary":"List knowledge bases and plan capabilities","description":"List knowledge bases visible in the current organization, their ownership, and effective plan capabilities. Use capabilities.documentUploadAllowed to discover document-upload entitlement (normally Pro or Business). Inspect ingestionAllowed, ingestionUnavailableReason, graceReadOnly, usage, and limitsReached for current ingestion constraints. A true upload capability does not bypass knowledge-base ownership, remaining capacity, or worker availability. Capacity-full replacement of an uploaded source with existing completed content has separate rules documented by uploadKnowledgeBaseSource.","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseOverview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]},"post":{"operationId":"createKnowledgeBase","summary":"Create a knowledge base","description":"Create a knowledge base","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseCreate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBase"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan capability unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}":{"put":{"operationId":"updateKnowledgeBase","summary":"Rename a knowledge base","description":"Replaces name and description. First read listKnowledgeBases and copy the current description when renaming; omitted/null/blank description clears it. This is not a partial PATCH.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseUpsert"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBase"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteKnowledgeBase","summary":"Delete a knowledge base","description":"Delete a knowledge base","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"forceDetach","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Detach connected agents before deletion when true."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/connected-agents":{"get":{"operationId":"getKnowledgeBaseAgents","summary":"List agents connected to a knowledge base","description":"List agents connected to a knowledge base","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object","properties":{"standinProfileId":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"}},"required":["standinProfileId","name","displayName"]}}},"required":["agents"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/uploads":{"post":{"operationId":"uploadKnowledgeBaseSource","summary":"Queue a document upload","description":"Queue one nonempty PDF (.pdf), Word (.docx), Markdown (.md or .markdown), or text (.txt) document for asynchronous indexing. Send a multipart/form-data file part; the backend accepts a supported filename extension or its supported media type (application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/markdown, or text/plain). The maximum file size is 10 MiB (10485760 bytes); the complete multipart request is limited to 12 MiB (12582912 bytes). Oversized requests return 413. Requires knowledge:write, the knowledge-base owner, and capabilities.documentUploadAllowed=true from listKnowledgeBases (normally Pro or Business; use the effective capability rather than inferring entitlement from a plan name). Inspect ingestionAllowed, ingestionUnavailableReason, graceReadOnly, usage, and limitsReached as well: the ingestion worker must be available, and new sources require remaining page and indexed-content capacity. The raw-file request limit is separate from indexed-content storage allowance. Omit sourceId to create a new uploaded source. Supply sourceId as a query parameter or multipart field to replace an uploaded source in the same knowledge base and organization; do not supply it in both places. Website and sitemap sources cannot be replaced by uploading. An open indexing task for that source returns 409. A replacement keeps existing completed content active until the new content is activated; failure or cancellation leaves that completed content in place. A source with completed content can be replaced when new-ingestion capacity is full, but the upload entitlement and graceReadOnly gates still apply. A 200 response returns the queued ingestion task, not proof that indexing has completed; inspect listKnowledgeBaseTasks for progress.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"sourceId","in":"query","required":false,"description":"Optional existing uploaded source to replace in the same knowledge base and organization. Omit or leave blank to create a new source. The source must have no open indexing task. May alternatively be supplied as a multipart field; use only one location.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Empty file, unsupported document format, or replacement of a source that is not an uploaded document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The uploaded source already has an open indexing task; inspect or cancel that task before requesting a replacement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"One nonempty PDF (.pdf), Word (.docx), Markdown (.md or .markdown), or text (.txt) file, at most 10 MiB (10485760 bytes). Supported media types are application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/markdown, and text/plain. The server accepts a supported filename extension or media type; the filename extensions below describe the supported document formats.","x-allowed-file-extensions":[".pdf",".docx",".md",".markdown",".txt"],"x-max-file-bytes":10485760},"sourceId":{"type":"string","description":"Optional existing uploaded source to replace in the same knowledge base and organization. Omit or leave blank to create a new source. The source must have no open indexing task. May alternatively be supplied as a multipart field; use only one location."}},"required":["file"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/crawls":{"post":{"operationId":"crawlKnowledgeBase","summary":"Queue a website crawl","description":"Queue a website-prefix crawl using the existing ingestion service. A queued task is not completed ingestion. Retain taskId and sourceId; inspect sources and tasks until indexing completes. Respect returned plan capabilities and limits.","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"The selected page hostname. urlPrefix must use the same normalized domain."},"urlPrefix":{"type":"string","description":"Website URL prefix on the selected domain. Crawling stays within that host and path subtree. Use approved public content; local and private addresses are rejected outside explicitly configured development mode.","minLength":1,"pattern":"\\S"},"maxDepth":{"type":"integer","default":1,"description":"Use 0 to fetch the selected start page without discovering linked pages. Supplied values are clamped to 0 through 10."}},"required":["domain","urlPrefix"],"examples":[{"domain":"example.com","urlPrefix":"https://example.com/help/","maxDepth":0}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan capability unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/sitemaps":{"post":{"operationId":"crawlKnowledgeBaseSitemap","summary":"Queue a sitemap crawl","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sitemapUrl":{"type":"string"},"dailyRefreshEnabled":{"type":"boolean"}},"required":["sitemapUrl"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}],"description":"Start ingestion from an approved public sitemap into an owned knowledge base. Existing plan and crawl limits apply; inspect returned tasks before treating content as ready."}},"/v1/knowledge-bases/{knowledgeBaseId}/sources":{"get":{"operationId":"listKnowledgeBaseSources","summary":"List knowledge sources","description":"Without view, preserves the complete legacy application/json list and fields. Explicit view=inspection selects SQL-bounded metadata with application/vnd.stand.knowledge-inspection+json; Accept must allow that media type (406 otherwise). Inspection parameters require view=inspection. Lists are ordered by immutable createdAt descending and ID descending. Follow nextCursor as after with the same base and filters; malformed or differently bound cursors return 400. Each page rechecks current organization and knowledge-base access. Exact filter IDs outside that base return 404. Historical tasks remain readable after source deletion. complete means this response alone covers the selected list: it is false on every continuation page, including the last. hasMore/nextCursor describe the remaining pages. totalElements is an independent current count, not a snapshot across concurrent changes. Content, raw diagnostics, worker fields and storage paths are omitted. Task effectiveUrl is null for unavailable/deleted source metadata or URLs exceeding 2048 UTF-16 code units.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["inspection"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"after","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"sourceId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, select this exact source in the selected base; foreign or mismatched IDs return 404. A soft-deleted source can still scope retained tasks/documents. Without view, the existing document source filter is unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseSource"}}},"required":["sources"]}},"application/vnd.stand.knowledge-inspection+json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"status":{"type":"string"},"sourceType":{"type":"string"},"displayName":{"type":"string"},"pageCount":{"type":"integer"}},"required":["sourceId","knowledgeBaseId","status","sourceType","displayName","pageCount"]},"maxItems":50},"view":{"type":"string","const":"inspection"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"},"returnedCount":{"type":"integer","minimum":0,"maximum":50},"totalElements":{"type":"integer","minimum":0},"complete":{"type":"boolean"}},"required":["sources","view","hasMore","nextCursor","returnedCount","totalElements","complete"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"406":{"description":"Explicit inspection was requested but Accept does not allow application/vnd.stand.knowledge-inspection+json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/documents":{"get":{"operationId":"listKnowledgeBaseDocuments","summary":"List indexed documents","description":"Without view, preserves the complete legacy application/json list and fields. Explicit view=inspection selects SQL-bounded metadata with application/vnd.stand.knowledge-inspection+json; Accept must allow that media type (406 otherwise). Inspection parameters require view=inspection. Lists are ordered by immutable createdAt descending and ID descending. Follow nextCursor as after with the same base and filters; malformed or differently bound cursors return 400. Each page rechecks current organization and knowledge-base access. Exact filter IDs outside that base return 404. Historical tasks remain readable after source deletion. complete means this response alone covers the selected list: it is false on every continuation page, including the last. hasMore/nextCursor describe the remaining pages. totalElements is an independent current count, not a snapshot across concurrent changes. Content, raw diagnostics, worker fields and storage paths are omitted. Task effectiveUrl is null for unavailable/deleted source metadata or URLs exceeding 2048 UTF-16 code units.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["inspection"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"after","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"sourceId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, select this exact source in the selected base; foreign or mismatched IDs return 404. A soft-deleted source can still scope retained tasks/documents. Without view, the existing document source filter is unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseDocument"}}},"required":["documents"]}},"application/vnd.stand.knowledge-inspection+json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"documentId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"status":{"type":"string"},"chunkCount":{"type":"integer","minimum":0}},"required":["documentId","knowledgeBaseId","sourceId","status","chunkCount"]},"maxItems":50},"view":{"type":"string","const":"inspection"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"},"returnedCount":{"type":"integer","minimum":0,"maximum":50},"totalElements":{"type":"integer","minimum":0},"complete":{"type":"boolean"}},"required":["documents","view","hasMore","nextCursor","returnedCount","totalElements","complete"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"406":{"description":"Explicit inspection was requested but Accept does not allow application/vnd.stand.knowledge-inspection+json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/documents/{documentId}":{"get":{"operationId":"getKnowledgeBaseDocument","summary":"Read an indexed document","description":"Read an indexed document","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseDocumentDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteKnowledgeBaseDocument","summary":"Schedule document deletion","description":"Schedule document deletion","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/documents/{documentId}/chunks":{"get":{"operationId":"listKnowledgeBaseDocumentChunks","summary":"Inspect document chunks","description":"Inspect document chunks","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"chunks":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseChunk"}}},"required":["chunks"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/documents/{documentId}/search":{"post":{"operationId":"searchKnowledgeBaseDocument","summary":"Search an indexed document","description":"Search an indexed document","tags":["Knowledge bases"],"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSearch"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseSearchResult"}}},"required":["results"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/tasks":{"get":{"operationId":"listKnowledgeBaseTasks","summary":"List ingestion tasks","description":"Without view, preserves the complete legacy application/json list and fields. Explicit view=inspection selects SQL-bounded metadata with application/vnd.stand.knowledge-inspection+json; Accept must allow that media type (406 otherwise). Inspection parameters require view=inspection. Lists are ordered by immutable createdAt descending and ID descending. Follow nextCursor as after with the same base and filters; malformed or differently bound cursors return 400. Each page rechecks current organization and knowledge-base access. Exact filter IDs outside that base return 404. Historical tasks remain readable after source deletion. complete means this response alone covers the selected list: it is false on every continuation page, including the last. hasMore/nextCursor describe the remaining pages. totalElements is an independent current count, not a snapshot across concurrent changes. Content, raw diagnostics, worker fields and storage paths are omitted. Task effectiveUrl is null for unavailable/deleted source metadata or URLs exceeding 2048 UTF-16 code units.","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["inspection"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"after","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"}},{"name":"taskId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, inspect this exact task, including an older task whose source was deleted. The task must belong to the selected base; otherwise 404."},{"name":"sourceId","in":"query","required":false,"schema":{"type":"string"},"description":"In inspection mode, select this exact source in the selected base; foreign or mismatched IDs return 404. A soft-deleted source can still scope retained tasks/documents. Without view, the existing document source filter is unchanged."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}},"required":["tasks"]}},"application/vnd.stand.knowledge-inspection+json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"status":{"type":"string"},"sourceId":{"type":["string","null"]},"progressCurrent":{"type":"integer"},"progressTotal":{"type":"integer"},"effectiveUrl":{"type":["string","null"],"maxLength":2048}},"required":["taskId","knowledgeBaseId","status","sourceId","progressCurrent","progressTotal","effectiveUrl"]},"maxItems":50},"view":{"type":"string","const":"inspection"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"],"minLength":1,"maxLength":4096,"pattern":"^[A-Za-z0-9_-]+$"},"returnedCount":{"type":"integer","minimum":0,"maximum":50},"totalElements":{"type":"integer","minimum":0},"complete":{"type":"boolean"}},"required":["tasks","view","hasMore","nextCursor","returnedCount","totalElements","complete"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"406":{"description":"Explicit inspection was requested but Accept does not allow application/vnd.stand.knowledge-inspection+json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/sources/{sourceId}":{"delete":{"operationId":"deleteKnowledgeBaseSource","summary":"Schedule source deletion","description":"Marks a source for deletion; derived data cleanup is asynchronous.","tags":["Knowledge bases"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/sources/{sourceId}/recrawl":{"post":{"operationId":"recrawlKnowledgeBaseSource","summary":"Queue a source refresh","tags":["Knowledge bases"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}],"description":"Queue another crawl of an owned website or sitemap source, subject to existing source and plan limits."}},"/v1/knowledge-bases/sources/{sourceId}/sitemap-refresh":{"put":{"operationId":"setSitemapRefresh","summary":"Change daily sitemap refresh","tags":["Knowledge bases"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSource"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}],"description":"Change the refresh preference on an owned sitemap source; the existing background schedule performs subsequent ingestion."}},"/v1/knowledge-bases/tasks/{taskId}/cancel":{"post":{"operationId":"cancelKnowledgeBaseTask","summary":"Request ingestion cancellation","description":"Only the knowledge-base owner can request cancellation; inspect returned/task-list status until the worker reaches a terminal state.","tags":["Knowledge bases"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseIngestionTask"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","security":[{"bearerAuth":[]}]}},"/v1/knowledge-bases/{knowledgeBaseId}/search":{"post":{"operationId":"searchKnowledgeBase","summary":"Search a knowledge base","tags":["Knowledge bases"],"parameters":[{"name":"knowledgeBaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseSearch"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseSearchResult"}}},"required":["results"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective knowledge-base plan, capability, capacity or grace-state gate denies this action. Inspect listKnowledgeBases capabilities, usage and limitsReached and the error code/details; do not retry the unchanged request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}],"description":"Search documents accessible within this knowledge base. Current organization membership and knowledge-base permissions apply."}},"/v1/reps/me/standins/{standinProfileId}/knowledge-bases":{"get":{"operationId":"getAgentKnowledgeBases","summary":"List a Stand-in knowledge attachments","description":"List a Stand-in knowledge attachments","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:read","parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKnowledgeBases"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"setAgentKnowledgeBases","summary":"Replace a Stand-in knowledge attachments","description":"Replace the complete knowledge attachment list for your Stand-in. Read existing attachments and preserve every ID that should remain. Always send knowledgeBaseIds explicitly; an empty list detaches all. Coordinate concurrent changes and stop if existing attachments changed unexpectedly.","tags":["Knowledge bases"],"x-stability":"beta","x-owner-required":false,"x-required-scope":"knowledge:write","parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"knowledgeBaseIds":{"type":"array","items":{"type":"string"}}},"required":["knowledgeBaseIds"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKnowledgeBases"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, expired or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan capability unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission, scope, membership or plan restriction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource or operation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/integrations":{"get":{"operationId":"listIntegrations","summary":"List organization integrations and capabilities","description":"List organization integrations and capabilities","tags":["Integrations"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationOverview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:read","security":[{"bearerAuth":[]}]}},"/v1/integrations/openapi/preview":{"post":{"operationId":"previewOpenApiIntegration","summary":"Preview an imported OpenAPI integration","description":"Validates and previews a customer API specification; does not create the integration. Import rate and document/operation/schema limits apply.","tags":["Integrations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"baseUrl":{"type":"string"},"openApiDocument":{"type":"string"}},"required":["baseUrl","openApiDocument"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The complete integration request body exceeds 5 MiB (INTEGRATION_PAYLOAD_TOO_LARGE), including chunked requests. Reduce the payload before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the shared per-representative import window is exhausted. Retry-After is 60 seconds, a conservative wait for the existing one-minute window. Applies to preview/create and update when importing a replacement declaration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/integrations/{integrationId}/openapi":{"get":{"operationId":"getIntegrationOpenApi","summary":"Read the imported OpenAPI source","description":"Read the imported OpenAPI source","tags":["Integrations"],"parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiIntegrationSource"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"updateOpenApiIntegration","summary":"Update an OpenAPI integration","description":"Replaces name, description, destination and authentication metadata; this is not a partial PATCH. First read listIntegrations and copy the current name, description, baseUrl, authType and authHeaderName, then edit the intended fields. Omitted description clears it. Omitted/null/blank authType means none and deletes stored authentication. To retain a secret, explicitly keep the same non-none authType, baseUrl and applicable authHeaderName, and omit authUsername/authSecret. The example assumes an existing bearer-authenticated integration at that exact destination. Changing type, destination, header or username requires a replacement secret; basic then requires its username. A nonblank openApiDocument replaces the declaration and requires a nonempty tool selection. Without it, tools/source are preserved and nonempty selection arrays are rejected.","tags":["Integrations"],"parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The complete integration request body exceeds 5 MiB (INTEGRATION_PAYLOAD_TOO_LARGE), including chunked requests. Reduce the payload before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the shared per-representative import window is exhausted. Retry-After is 60 seconds, a conservative wait for the existing one-minute window. Applies to preview/create and update when importing a replacement declaration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/integrations/openapi":{"post":{"operationId":"createOpenApiIntegration","summary":"Create an OpenAPI integration","description":"Creates an organization integration from a complete OpenAPI declaration. Supply name, public baseUrl and at least one actual selected tool key from previewOpenApiIntegration. selectedTools takes precedence when it contains nonblank keys; enabledToolKeys is a legacy fallback. Non-none authentication requires a secret and HTTPS; basic also requires a username and api_key_header requires a header name. The server validates declaration limits, selected operation membership, public destination safety and credential/header rules. Selected write tools require configured confirmation signing.","tags":["Integrations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationCreate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Integration"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Generic OpenAPI integrations require the Business plan. Inspect listIntegrations capabilities; do not retry an unchanged plan denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"The complete integration request body exceeds 5 MiB (INTEGRATION_PAYLOAD_TOO_LARGE), including chunked requests. Reduce the payload before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the shared per-representative import window is exhausted. Retry-After is 60 seconds, a conservative wait for the existing one-minute window. Applies to preview/create and update when importing a replacement declaration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/integrations/{integrationId}":{"delete":{"operationId":"deleteIntegration","summary":"Delete an integration and detach it from agents","description":"Delete an integration and detach it from agents","tags":["Integrations"],"parameters":[{"name":"integrationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{standinProfileId}/integrations":{"get":{"operationId":"getAgentIntegrations","summary":"List a Stand-in integration attachments","description":"List a Stand-in integration attachments","tags":["Integrations"],"parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentIntegrations"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"setAgentIntegrations","summary":"Replace a Stand-in integration attachments","description":"Replaces every integration attachment. First read getAgentIntegrations and include each integrationId to retain; an empty array, omission or null detaches all.","tags":["Integrations"],"parameters":[{"name":"standinProfileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationIds":{"type":["array","null"],"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentIntegrations"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"One or more selected integrations require a plan entitlement the organization does not have. Inspect listIntegrations capabilities; an empty set can detach integrations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"integrations:write","security":[{"bearerAuth":[]}]}},"/v1/reps/profile/avatar":{"post":{"operationId":"uploadRepAvatar","summary":"Stage a profile avatar image","description":"Stages an immutable image for the authenticated representative without changing the current profile. Pass the returned filename as avatarUrl in PUT /v1/reps/profile, retaining the other profile fields. avatarUrl in this response is the resolved image URL. Static images are center-cropped and resized to 256×256 WebP. Animated GIF and WebP retain animation only when square, 64–256 pixels per side, at most 256 KiB, at most 300 frames, at most 10 seconds total, and at least 30 ms per frame; invalid animations return 400 BAD_REQUEST.","tags":["Representative presence"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":"string"},"filename":{"type":"string"}},"required":["avatarUrl","filename"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed. Animated avatar validation also returns BAD_REQUEST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standin/status":{"get":{"operationId":"getStandinStatus","summary":"Get your master Stand-in switch","description":"Read your account-wide Stand-in master switch. This is separate from the enabled state of each individual Stand-in.","tags":["Representative presence"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"standinEnabled":{"type":"boolean"}},"required":["standinEnabled"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standin/toggle":{"post":{"operationId":"toggleStandin","summary":"Set your master Stand-in switch","description":"Set your account-wide Stand-in master switch using enabled true or false. This affects all of your individually enabled Stand-ins, including those on other Sites; inspect the existing configuration and obtain approval for that shared effect.","tags":["Representative presence"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"standinEnabled":{"type":"boolean"}},"required":["standinEnabled"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/org-prompt":{"get":{"operationId":"getMyOrgPrompt","summary":"Get your current organization instructions","description":"Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Representative presence"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"hasOrg":{"type":"boolean"},"prompt":{"anyOf":[{"$ref":"#/components/schemas/OrgPrompt"},{"type":"null"}]},"ownerName":{"type":["string","null"]}},"required":["hasOrg","prompt","ownerName"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins":{"get":{"operationId":"listLapelPins","summary":"List organization pin policies","description":"List organization pin policies","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LapelPin"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveLapelPin","summary":"Save organization pin policy","description":"Replaces editable pin settings, not a partial PATCH. First read the selected pin and copy pinType, color, borderColor, fontFamily, fontColor, pillText and usePinAsBotAvatar before editing. Omitted/null pinType, color and fontFamily reset to none, #000000 and sans-serif; omitted optional text/colors clear and usePinAsBotAvatar becomes false. Existing uploaded icon/logo URLs are preserved. Sending only pillText turns the pin off. For organization policies, preserve domain to select the same policy; omission selects the organization-wide default.","tags":["Branding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPinInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"deleteOrgPin","summary":"Delete organization pin policy","description":"Delete organization pin policy","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/me":{"get":{"operationId":"getMyPin","summary":"Get your personal pin","description":"Get your personal pin","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionalLapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveMyPin","summary":"Save your personal pin","description":"Replaces editable pin settings, not a partial PATCH. First read the selected pin and copy pinType, color, borderColor, fontFamily, fontColor, pillText and usePinAsBotAvatar before editing. Omitted/null pinType, color and fontFamily reset to none, #000000 and sans-serif; omitted optional text/colors clear and usePinAsBotAvatar becomes false. Existing uploaded icon/logo URLs are preserved. Sending only pillText turns the pin off. For organization policies, preserve domain to select the same policy; omission selects the organization-wide default.","tags":["Branding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPinInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/resolve":{"get":{"operationId":"resolveLapelPin","summary":"Resolve the effective pin for a domain","description":"Resolve the effective pin for a domain","tags":["Branding"],"parameters":[{"name":"domain","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionalLapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/me/icon":{"post":{"operationId":"uploadMyIcon","summary":"Upload your personal pin icon","description":"Applies the uploaded image immediately and returns its resolved URL. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 128×128 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"circleIconUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["circleIconUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/me/logo":{"post":{"operationId":"uploadMyLogo","summary":"Upload your personal pin logo","description":"Applies the uploaded image immediately and returns its resolved URL. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 256×64 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"pillLogoUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["pillLogoUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"profile:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/{pinId}/icon":{"post":{"operationId":"uploadIcon","summary":"Upload an organization pin icon","description":"Applies the uploaded image immediately and returns its resolved URL. Requires the current active organization owner and an existing pinId from that organization; a missing or foreign pin returns 404 NOT_FOUND. Uploading does not change pinType or other pin settings. The image is resized to fit 128×128 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"parameters":[{"name":"pinId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"circleIconUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["circleIconUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/lapel-pins/{pinId}/logo":{"post":{"operationId":"uploadLogo","summary":"Upload an organization pin logo","description":"Applies the uploaded image immediately and returns its resolved URL. Requires the current active organization owner and an existing pinId from that organization; a missing or foreign pin returns 404 NOT_FOUND. Uploading does not change pinType or other pin settings. The image is resized to fit 256×64 while preserving aspect ratio and stored as static WebP.","tags":["Branding"],"parameters":[{"name":"pinId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"pillLogoUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["pillLogoUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":true,"x-required-scope":"org:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/skills":{"get":{"operationId":"listStandinSkills","summary":"List Stand-in skills and effective entitlements","description":"Read skills on one of your Stand-ins. Site restriction does not change ownership or delegated permissions.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkill"}}},"required":["skills"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/skills/{skillKey}":{"put":{"operationId":"updateStandinSkill","summary":"Save a Stand-in skill","description":"Skill keys are followup, customerDiscovery, and labeling. Omitted/null config preserves existing settings. followup merges supplied keys; customerDiscovery replaces the configuration, so first read listStandinSkills and copy all fields to retain them. labeling preserves labels unless config.labels is present: supply every retained label with its labelId, name, prompt, active and notify; [] clears them. Enabled state never overrides plan entitlement. Label input requires a nonblank name and prompt; testPrompt is a legacy alias used only when prompt is absent. A present null, blank or malformed prompt is rejected even if testPrompt is valid.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"skillKey","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSkillUpdate"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSkill"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The effective plan does not permit enabling this skill or saving active labels. Saving active labels can be denied even when the labeling skill is disabled. Inspect listStandinSkills; do not retry unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/avatar":{"post":{"operationId":"uploadStandinAvatar","summary":"Apply a Stand-in avatar image","description":"Applies the uploaded image immediately to your existing Stand-in, retaining its ID. No subsequent profile save is needed. A missing, deleted or another representative’s Stand-in returns 404 NOT_FOUND. Static images are center-cropped and resized to 256×256 WebP. Animated GIF and WebP retain animation only when square, 64–256 pixels per side, at most 256 KiB, at most 300 frames, at most 10 seconds total, and at least 30 ms per frame; invalid animations return 400 BAD_REQUEST.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":"string"}},"required":["avatarUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed. Animated avatar validation also returns BAD_REQUEST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]},"delete":{"operationId":"clearAvatar","summary":"Remove a Stand-in avatar","description":"Changes an owned Stand-in; current account and resource permissions apply.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":["string","null"]}},"required":["avatarUrl"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/avatar-upload":{"post":{"operationId":"uploadDraftAvatar","summary":"Stage an avatar for a new Stand-in","description":"Stages an immutable image without creating or modifying a Stand-in. Pass the returned filename as avatarUrl when creating the Stand-in with POST /v1/reps/me/standins. avatarUrl in this response is the resolved image URL. Static images are center-cropped and resized to 256×256 WebP. Animated GIF and WebP retain animation only when square, 64–256 pixels per side, at most 256 KiB, at most 300 frames, at most 10 seconds total, and at least 30 ms per frame; invalid animations return 400 BAD_REQUEST.","tags":["Stand-ins"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string"},"avatarUrl":{"type":"string"}},"required":["filename","avatarUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, a file-part Content-Type outside image/*, a file larger than 5 MiB, or image bytes that cannot be processed. Animated avatar validation also returns BAD_REQUEST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. The file part must declare an image/* Content-Type and contain at most 5 MiB (5,242,880 bytes). The bytes must decode as a supported raster image; PNG, JPEG, WebP and GIF are supported. A MIME label alone does not make a file a valid image."}},"required":["file"]},"encoding":{"file":{"contentType":"image/*"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/unclaimed-avatar-pool":{"get":{"operationId":"unclaimedAvatarPool","summary":"List reusable avatar candidates","description":"List reusable avatar candidates","tags":["Stand-ins"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":12},"description":"Clamped to 1 through 24."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCandidates"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/avatar-candidates":{"post":{"operationId":"generateAvatarCandidates","summary":"Generate avatar candidates","description":"Runs a bounded generation request under per-rep daily rate limits. Does not select a candidate automatically.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCandidates"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the existing per-representative daily avatar allowance is exhausted. Retry-After is the positive number of seconds until the next UTC midnight, rounded up. No provider generation starts on this denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"The image provider failed or no generated image could be processed. The generation attempt already counts toward the daily limit; do not automatically retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"extraInstructions":{"type":["string","null"]}}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/preview-avatar-candidates":{"post":{"operationId":"previewAvatarCandidates","summary":"Generate candidates before creating a Stand-in","description":"Creates an unattached candidate pool for the user under the ordinary role and quota checks; it does not update a Stand-in.","tags":["Stand-ins"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":["string","null"]},"greeting":{"type":["string","null"]},"prompt":{"type":["string","null"]},"siteId":{"type":["string","null"]},"extraInstructions":{"type":["string","null"]}},"required":["displayName"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarCandidates"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"RATE_LIMIT_EXCEEDED: the existing per-representative daily avatar allowance is exhausted. Retry-After is the positive number of seconds until the next UTC midnight, rounded up. No provider generation starts on this denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"The image provider failed or no generated image could be processed. The generation attempt already counts toward the daily limit; do not automatically retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/avatar/select-candidate":{"post":{"operationId":"selectAvatarCandidate","summary":"Apply a generated avatar candidate","description":"Select an AI-generated candidate created by you or currently available in the shared unclaimed pool. Uploaded photos and another user’s already-claimed generated candidates cannot be selected by filename.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"candidateId":{"type":"string"}},"required":["candidateId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"avatarUrl":{"type":"string"}},"required":["avatarUrl"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/lapel-pin":{"get":{"operationId":"getStandinLapelPin","summary":"Get a Stand-in pin","description":"If the owned Stand-in has no pin yet, returns 404 NOT_FOUND with error.details.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:read","security":[{"bearerAuth":[]}]},"put":{"operationId":"saveStandinLapelPin","summary":"Save a Stand-in pin","description":"Replaces editable pin settings, not a partial PATCH. First read the selected pin and copy pinType, color, borderColor, fontFamily, fontColor, pillText and usePinAsBotAvatar before editing. Omitted/null pinType, color and fontFamily reset to none, #000000 and sans-serif; omitted optional text/colors clear and usePinAsBotAvatar becomes false. Existing uploaded icon/logo URLs are preserved. Sending only pillText turns the pin off. For organization policies, preserve domain to select the same policy; omission selects the organization-wide default.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPinInput"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LapelPin"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/lapel-pin/icon":{"post":{"operationId":"uploadStandinPinIcon","summary":"Upload a Stand-in pin icon","description":"Applies the uploaded image immediately to your Stand-in’s pin and returns its resolved URL. A missing, deleted or another representative’s Stand-in returns 404 NOT_FOUND. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 128×128 while preserving aspect ratio and stored as static WebP.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"circleIconUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["circleIconUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. These two Stand-in pin routes validate decoded image bytes without requiring a particular file-part Content-Type. PNG, JPEG, WebP and GIF are supported. The configured multipart limits are 10 MiB (10,485,760 bytes) per file and 12 MiB (12,582,912 bytes) per request, including multipart overhead; there is no separate 5 MiB controller limit on these two routes."}},"required":["file"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/reps/me/standins/{id}/lapel-pin/logo":{"post":{"operationId":"uploadStandinPinLogo","summary":"Upload a Stand-in pin logo","description":"Applies the uploaded image immediately to your Stand-in’s pin and returns its resolved URL. A missing, deleted or another representative’s Stand-in returns 404 NOT_FOUND. If no pin exists, a pin with pinType none is created. Uploading does not change pinType; save the pin settings separately to enable its display. The image is resized to fit 256×64 while preserving aspect ratio and stored as static WebP.","tags":["Stand-ins"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"pillLogoUrl":{"type":"string","description":"Resolved URL of the uploaded image."}},"required":["pillLogoUrl"]}}}},"400":{"description":"BAD_REQUEST: missing or empty file, or image bytes that cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","minLength":1,"description":"Nonempty image bytes, not a filename or base64 text. These two Stand-in pin routes validate decoded image bytes without requiring a particular file-part Content-Type. PNG, JPEG, WebP and GIF are supported. The configured multipart limits are 10 MiB (10,485,760 bytes) per file and 12 MiB (12,582,912 bytes) per request, including multipart overhead; there is no separate 5 MiB controller limit on these two routes."}},"required":["file"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"standins:write","security":[{"bearerAuth":[]}]}},"/v1/stats":{"get":{"operationId":"getStats","summary":"Get usage statistics for an authorized scope","description":"Read statistics for an authorized representative, Site or organization. A representative can read their own statistics; an organization owner can read a member's representative statistics. Site and organization access require membership in that organization. Existing resource checks apply.","tags":["Statistics"],"parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["rep","site","org"]},"description":"Usage for an authorized representative, site or organization. Stand-in-specific statistics are not available. Resource ownership and organization membership checks apply."},{"name":"scopeId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Required resource identifier: your userId for rep, an accessible siteId for site, or your orgId for org. Obtain these from identity/profile or site reads."},{"name":"bucketType","in":"query","required":true,"schema":{"type":"string","enum":["h","d","w"]},"description":"Returns 24 hourly, 28 daily, or 52 weekly buckets."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"analytics:read","security":[{"bearerAuth":[]}]}},"/v1/stats/live-shows":{"get":{"operationId":"getLiveShows","summary":"Count recent widget shows on your covered sites","description":"Count recent widget shows on your covered sites","tags":["Statistics"],"parameters":[{"name":"windowSeconds","in":"query","required":false,"schema":{"type":"integer","default":300,"minimum":60,"maximum":3600}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveShowsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"analytics:read","security":[{"bearerAuth":[]}]}},"/v1/feedback":{"post":{"operationId":"submitFeedback","summary":"Submit feedback to Stand","description":"Submit feedback to Stand","tags":["Feedback"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"feedbackId":{"type":"string"},"submittedAt":{"type":"string","format":"date-time"}},"required":["feedbackId","submittedAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Multipart file or request exceeds the configured server upload limit (PAYLOAD_TOO_LARGE). Per-operation file validation can also reject smaller invalid files with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["whats-working","how-i-use-stand","idea","bug","blocker","sales-inquiry"]},"description":{"type":"string"},"file":{"type":"string","format":"binary","description":"Optional image, at most 4 MiB."}},"required":["type","description"]}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"feedback:write","security":[{"bearerAuth":[]}]}},"/v1/org/usage":{"get":{"operationId":"getOrgUsage","summary":"Get current plan usage","description":"Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Plans and billing"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUsage"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}},"/v1/org/plan":{"get":{"operationId":"getOrgPlan","summary":"Get current plan capabilities","description":"Price, billing-cycle, and overage-price fields are omitted for nonowners. Existing role restrictions still apply; this credential does not grant organization-wide writes.","tags":["Plans and billing"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPlan"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Access denied. INSUFFICIENT_SCOPE identifies missing OAuth permission; details.requiredScope names it. OWNER_REQUIRED identifies an organization-owner guard. Other membership, resource and permission denials retain their own code, including FORBIDDEN. These codes are not an exhaustive list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"NOT_FOUND: resource not found or unavailable to the caller. An authenticated external client also receives generic 404 for an unmapped method/path; no insufficient_scope challenge is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Current state conflicts with request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-stability":"beta","x-owner-required":false,"x-required-scope":"org:read","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"User access token for stand-api managed by the supported stand-cli OAuth client. Sign in with stand auth login and use named commands or stand api; no custom client registration, personal access tokens or service accounts are offered in this beta. Live membership, role, tenant, owner and resource checks still apply."}},"schemas":{"User":{"type":"object","properties":{"isRep":{"type":"boolean"},"userId":{"type":"string"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"orgId":{"type":["string","null"]},"brand":{"type":["string","null"]},"title":{"type":["string","null"]},"avatar":{"type":["string","null"]},"roles":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["isRep","userId","email","name","orgId","brand","title","avatar","roles"]},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code. Each public operation lists known codes in x-error-codes.byStatus. That catalog is non-exhaustive; preserve unfamiliar codes and use the HTTP status as a fallback. Do not parse message text."},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"type":"object","additionalProperties":true,"properties":{"requiredScope":{"type":"string","description":"An additional delegated permission required by the requested change, when applicable."}}}},"required":["code","message","timestamp"]}},"required":["error"]},"RepProfileResponse":{"type":"object","properties":{"completed":{"type":"boolean"},"profile":{"anyOf":[{"$ref":"#/components/schemas/RepProfile"},{"type":"null"}]},"accountDisabled":{"type":"boolean"},"ownerName":{"type":["string","null"]}},"required":["completed","profile","accountDisabled","ownerName"]},"RepProfile":{"type":"object","properties":{"userId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":["string","null"]},"title":{"type":["string","null"]},"organization":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"orgId":{"type":["string","null"]},"greeting":{"type":["string","null"]},"completedAt":{"type":["string","null"],"format":"date-time"},"greetingEnabled":{"type":"boolean"}},"required":["userId","firstName","lastName","email","title","organization","avatarUrl","orgId","greeting","completedAt","greetingEnabled"]},"RepProfileUpdate":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":255},"lastName":{"type":"string","minLength":1,"maxLength":255},"title":{"type":["string","null"],"maxLength":255},"organization":{"type":["string","null"],"maxLength":255},"avatarUrl":{"type":["string","null"],"maxLength":255},"greeting":{"type":["string","null"]},"greetingEnabled":{"type":["boolean","null"]}},"required":["firstName","lastName"],"additionalProperties":false},"SiteList":{"type":"object","properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"isOwner":{"type":"boolean"},"ownerName":{"type":"string"}},"required":["sites","isOwner","ownerName"]},"Site":{"type":"object","properties":{"siteId":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"snippet":{"type":"string"},"enabled":{"type":"boolean"},"installed":{"type":"boolean"},"installedAt":{"type":"string","description":"ISO instant when installed; empty string before installation."},"createdAt":{"type":"string","format":"date-time"},"defaultLanguageCode":{"type":["string","null"]},"embedOptions":{"$ref":"#/components/schemas/SiteEmbedOptions"},"behaviorConfig":{"$ref":"#/components/schemas/SiteBehaviorConfig"}},"required":["siteId","domain","name","snippet","enabled","installed","installedAt","createdAt","defaultLanguageCode","embedOptions","behaviorConfig"]},"SiteEmbedOptions":{"type":"object","properties":{"delayToScroll":{"type":"boolean"},"noGreetings":{"type":"boolean"},"openChatAfterGreeting":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"},"revealDelayMs":{"type":"integer","minimum":0,"maximum":60000}},"required":["delayToScroll","noGreetings","openChatAfterGreeting","halfSize","stepAside","revealDelayMs"]},"SiteBehaviorConfig":{"type":"object","properties":{"advancedBehaviorEnabled":{"type":"boolean"},"allowStandAdminBehavior":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SiteBehaviorRule"}}},"required":["advancedBehaviorEnabled","allowStandAdminBehavior","rules"]},"SiteBehaviorRule":{"type":"object","properties":{"ruleId":{"type":"string"},"name":{"type":"string"},"pathPrefix":{"type":"string"},"customJavascript":{"type":"string"},"enabled":{"type":"boolean"},"hideButtonUntilTriggered":{"type":"boolean"},"presentation":{"$ref":"#/components/schemas/SiteBehaviorPresentation"},"trigger":{"$ref":"#/components/schemas/SiteBehaviorTrigger"},"action":{"$ref":"#/components/schemas/SiteBehaviorAction"}},"required":["ruleId","name","pathPrefix","customJavascript","enabled","hideButtonUntilTriggered","presentation","trigger","action"]},"SiteBehaviorPresentation":{"type":"object","properties":{"noGreetings":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"}},"required":["noGreetings","halfSize","stepAside"]},"SiteBehaviorTrigger":{"type":"object","properties":{"type":{"type":"string"},"delayMs":{"type":"integer"},"scrollPercent":{"type":"integer"}},"required":["type","delayMs","scrollPercent"]},"SiteBehaviorAction":{"type":"object","properties":{"type":{"type":"string"},"initialMessage":{"type":"string"}},"required":["type","initialMessage"]},"SiteCreate":{"type":"object","properties":{"domain":{"type":"string","description":"The normalized domain must fit 255 characters. Supply a hostname, without URL path or query.","minLength":1,"maxLength":255},"name":{"type":["string","null"],"maxLength":255},"embedOptions":{"$ref":"#/components/schemas/SiteEmbedOptionsUpdate"},"behaviorConfig":{"$ref":"#/components/schemas/SiteBehaviorConfigInput"}},"required":["domain"]},"SiteEmbedOptionsUpdate":{"type":"object","properties":{"delayToScroll":{"type":"boolean"},"noGreetings":{"type":"boolean"},"openChatAfterGreeting":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"},"revealDelayMs":{"type":"integer","minimum":0,"maximum":60000}},"additionalProperties":false,"description":"Legacy compatibility input. On update, any supplied embedOptions object, including embedOptions: {}, merges supplied keys into the saved legacy options and then replaces behaviorConfig: advancedBehaviorEnabled and allowStandAdminBehavior become false, and all existing rules, including custom JavaScript rules, are replaced by zero or one legacy-default rule derived from the merged options. An explicit behaviorConfig in the same request is applied after this conversion and controls the final configuration. Owner-consent validation uses the committed configuration before any sibling mutation; all fields are validated before saving. For behavior edits, modern clients should read the Site and replace the complete behaviorConfig with both switches and every retained rule."},"SiteBehaviorConfigInput":{"type":"object","properties":{"advancedBehaviorEnabled":{"type":"boolean"},"allowStandAdminBehavior":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SiteBehaviorRuleInput"}}},"required":["advancedBehaviorEnabled","allowStandAdminBehavior","rules"],"additionalProperties":false,"description":"Complete replacement, not a partial update. Read the current behaviorConfig first and include both switches and every retained rule. Missing primitive switches become false and missing rules becomes an empty list on the server; send all three fields to avoid unintended resets. External API/CLI clients cannot enable experimentation: advancedBehaviorEnabled may remain true only when it is already enabled for that Site. The organization owner enables it in the Stand dashboard under Sites > Chat widget behavior > Experimentation (Advanced), after accepting the warning. Once enabled, owner-authorized OAuth clients with sites:write may add, edit and activate custom JavaScript rules. Disabling it strips custom JavaScript from subsequent visitor behavior responses; stored source can be retained or edited while disabled but cannot execute. API clients may disable it but cannot re-enable it, even with an unconditional configuration replacement. They also cannot grant Stand-admin experimentation access. A denied enablement returns 403 EXPERIMENTATION_CONSENT_REQUIRED with no sibling changes. Reload the Site after the owner changes consent; broader scopes or another login cannot enable it."},"SiteBehaviorRuleInput":{"type":"object","properties":{"ruleId":{"type":"string"},"name":{"type":"string"},"pathPrefix":{"type":"string"},"customJavascript":{"type":"string"},"enabled":{"type":"boolean"},"hideButtonUntilTriggered":{"type":"boolean"},"presentation":{"type":"object","properties":{"noGreetings":{"type":"boolean"},"halfSize":{"type":"boolean"},"stepAside":{"type":"boolean"}},"additionalProperties":false},"trigger":{"type":"object","properties":{"type":{"type":"string"},"delayMs":{"type":"integer"},"scrollPercent":{"type":"integer"}},"additionalProperties":false},"action":{"type":"object","properties":{"type":{"type":"string"},"initialMessage":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"Deleted":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]},"SiteMatches":{"type":"object","properties":{"siteMatches":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/SiteMatch"}},"description":"Map keyed by public site ID."}},"required":["siteMatches"]},"SiteMatch":{"type":"object","properties":{"probability":{"type":"number"},"responderType":{"type":"string"},"pathPrefix":{"type":"string"},"ownerRepId":{"type":"string"},"repId":{"type":["string","null"]},"standinProfileId":{"type":["string","null"]},"name":{"type":["string","null"]},"brandName":{"type":["string","null"]},"avatar":{"type":["string","null"]},"ownerName":{"type":["string","null"]},"ownerTitle":{"type":["string","null"]},"lapelPin":{"anyOf":[{"$ref":"#/components/schemas/LapelPin"},{"type":"null"}]}},"required":["probability","responderType","pathPrefix","ownerRepId","repId","standinProfileId","name","brandName","avatar","ownerName","ownerTitle","lapelPin"]},"LapelPin":{"type":"object","properties":{"pinId":{"type":["string","null"]},"orgId":{"type":["string","null"]},"domain":{"type":["string","null"]},"color":{"type":["string","null"]},"borderColor":{"type":["string","null"]},"fontFamily":{"type":["string","null"]},"fontColor":{"type":["string","null"]},"pillText":{"type":["string","null"]},"circleIconUrl":{"type":["string","null"]},"pillLogoUrl":{"type":["string","null"]},"pinType":{"type":"string"},"usePinAsBotAvatar":{"type":"boolean"}},"required":["pinId","orgId","domain","color","borderColor","fontFamily","fontColor","pillText","circleIconUrl","pillLogoUrl","pinType","usePinAsBotAvatar"]},"SitePreferences":{"type":"object","properties":{"siteIds":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"null means never configured; [] opts out of all sites."}},"required":["siteIds"]},"SitePrompt":{"type":"object","properties":{"sitePromptId":{"type":"string"},"siteId":{"type":"string"},"content":{"type":"string"},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["sitePromptId","siteId","content","active","createdAt"]},"PromptUpdate":{"type":"object","properties":{"content":{"type":"string"}},"required":["content"]},"OrgPrompt":{"type":"object","properties":{"orgPromptId":{"type":"string"},"orgId":{"type":"string"},"content":{"type":"string"},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["orgPromptId","orgId","content","active","createdAt"]},"OrgPrivacy":{"type":"object","properties":{"orgId":{"type":"string"},"sensitiveNoticeEnabled":{"type":"boolean"},"sensitiveNoticeText":{"type":["string","null"]},"retentionDays":{"type":"integer"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["orgId","sensitiveNoticeEnabled","sensitiveNoticeText","retentionDays","updatedAt"]},"OrgPrivacyUpdate":{"type":"object","properties":{"sensitiveNoticeEnabled":{"type":"boolean"},"sensitiveNoticeText":{"type":["string","null"]},"retentionDays":{"type":"integer"}},"required":["sensitiveNoticeEnabled","retentionDays"]},"ArchivedSessions":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ArchivedSession"}},"page":{"type":"integer"},"totalPages":{"type":"integer"},"totalElements":{"type":"integer","format":"int64"},"isOwner":{"type":"boolean"},"sites":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/HistoryLabelOption"}}},"required":["sessions","page","totalPages","totalElements","isOwner","sites","labels"]},"ArchivedSession":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"page":{"type":"string"},"closedBy":{"type":["string","null"]},"closedByType":{"type":["string","null"]},"visitorName":{"type":["string","null"]},"visitorEmail":{"type":["string","null"]},"visitorPhone":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"messageCount":{"type":"integer"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/SessionLabel"}}},"required":["sessionId","status","page","closedBy","closedByType","visitorName","visitorEmail","visitorPhone","createdAt","closedAt","messageCount","labels"]},"SessionLabel":{"type":"object","properties":{"labelId":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"setAt":{"type":"string","format":"date-time"}},"required":["labelId","name","summary","setAt"]},"HistoryLabelOption":{"type":"object","properties":{"labelId":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"}},"required":["labelId","name"]},"ActiveSessions":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"string"}},"standinSessions":{"type":"array","items":{"type":"string"}},"needsAttention":{"type":"boolean"}},"required":["sessions","standinSessions","needsAttention"]},"Message":{"type":"object","properties":{"messageId":{"type":"string"},"sessionId":{"type":"string"},"senderId":{"type":"string"},"senderType":{"type":"string"},"body":{"type":"string"},"type":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"seq":{"type":"integer"},"clientMessageId":{"type":["string","null"]}},"required":["messageId","sessionId","senderId","senderType","body","type","sentAt","seq","clientMessageId"]},"GreetingVariant":{"type":"object","properties":{"greetingVariantId":{"type":"string"},"ownerType":{"type":"string"},"ownerId":{"type":"string"},"text":{"type":"string"},"status":{"type":"string"},"defaultVariant":{"type":"boolean"},"shownCount":{"type":"integer","format":"int64"},"openedCount":{"type":"integer","format":"int64"},"conversationStartedCount":{"type":"integer","format":"int64"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["greetingVariantId","ownerType","ownerId","text","status","defaultVariant","shownCount","openedCount","conversationStartedCount","createdAt","updatedAt"]},"GreetingVariantInput":{"type":"object","properties":{"greetingVariantId":{"type":["string","null"]},"text":{"type":"string"},"status":{"type":"string"},"defaultVariant":{"type":"boolean"}},"required":["text"]},"Team":{"type":"object","properties":{"orgId":{"type":"string"},"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}},"invitations":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"isOwner":{"type":"boolean"}},"required":["orgId","members","invitations","isOwner"]},"TeamMember":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"avatarUrl":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"},"joinedAt":{"type":"string"},"online":{"type":"boolean"},"acceptingChats":{"type":"boolean"},"agentsEnabled":{"type":"boolean"}},"required":["userId","email","firstName","lastName","avatarUrl","role","status","joinedAt","online","acceptingChats","agentsEnabled"]},"Invitation":{"type":"object","properties":{"invitationId":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"requireProvider":{"type":["string","null"]}},"required":["invitationId","email","status","createdAt","expiresAt","requireProvider"]},"DigestPreferences":{"type":"object","properties":{"cadence":{"type":"string","enum":["NONE","DAILY","WEEKLY","MONTHLY"]},"skipEmptyReports":{"type":"boolean"},"lastSentAt":{"type":["string","null"],"format":"date-time"},"includeTips":{"type":"boolean"}},"required":["cadence","skipEmptyReports","lastSentAt","includeTips"]},"DigestPreferencesUpdate":{"type":"object","properties":{"cadence":{"type":"string","enum":["NONE","DAILY","WEEKLY","MONTHLY"]},"skipEmptyReports":{"type":"boolean"},"includeTips":{"type":"boolean"}},"anyOf":[{"required":["cadence"]},{"required":["skipEmptyReports"]},{"required":["includeTips"]}]},"DigestAiPreferences":{"type":"object","properties":{"aiEnabled":{"type":"boolean"},"planAllows":{"type":"boolean"},"maxLabels":{"type":"integer"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/DigestLabel"}}},"required":["aiEnabled","planAllows","maxLabels","labels"]},"DigestLabel":{"type":"object","properties":{"labelId":{"type":"string"},"position":{"type":"integer"},"name":{"type":"string"},"testPrompt":{"type":"string"},"active":{"type":"boolean"}},"required":["labelId","position","name","testPrompt","active"]},"SessionDetails":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"page":{"type":"string"},"closedBy":{"type":["string","null"]},"siteId":{"type":["string","null"]},"websocketUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"visitorContact":{"anyOf":[{"$ref":"#/components/schemas/VisitorContact"},{"type":"null"}]},"labels":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SessionLabel"}},{"type":"null"}]},"closedByType":{"type":"string"},"conversationLanguage":{"type":["string","null"],"description":"Language tag when available; null for a durable archived-owner read without live language state."},"aiUsage":{"$ref":"#/components/schemas/AiUsage"},"aiTurnProgress":{"$ref":"#/components/schemas/AiTurnProgress"}},"required":["sessionId","status","page","closedBy","siteId","websocketUrl","createdAt","lastActivityAt","closedAt","participants","messages","visitorContact","labels","conversationLanguage"]},"VisitorContact":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"timezone":{"type":["string","null"]}},"required":["name","email","phone","timezone"]},"AiUsage":{"type":"object","properties":{"model":{"type":["string","null"]},"location":{"type":["string","null"]},"trafficType":{"type":["string","null"]},"providerRequests":{"type":"integer","format":"int64"},"promptTokens":{"type":"integer","format":"int64"},"cachedInputTokens":{"type":"integer","format":"int64"},"candidateTokens":{"type":"integer","format":"int64"},"thoughtsTokens":{"type":"integer","format":"int64"},"toolUsePromptTokens":{"type":"integer","format":"int64"},"totalTokens":{"type":"integer","format":"int64"}},"required":["model","location","trafficType","providerRequests","promptTokens","cachedInputTokens","candidateTokens","thoughtsTokens","toolUsePromptTokens","totalTokens"]},"AiTurnProgress":{"type":"object","properties":{"version":{"type":"integer"},"scope":{"type":"string"},"turnId":{"type":"string"},"visitorMessageSeq":{"type":"integer"},"status":{"type":"string"},"pendingEffects":{"type":"integer"}},"required":["version","scope","turnId","visitorMessageSeq","status","pendingEffects"]},"HistoryExport":{"type":"object","properties":{"exportedAt":{"type":"string","format":"date-time"},"filters":{"type":"object","properties":{"type":{"type":"string"},"scope":{"type":"string"},"contact":{"type":"string"},"site":{"type":["string","null"]},"label":{"type":["string","null"]},"q":{"type":["string","null"]},"closedFrom":{"type":["string","null"],"format":"date-time"},"closedTo":{"type":["string","null"],"format":"date-time"}}},"conversations":{"type":"array","items":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/ArchivedSession"},"session":{"$ref":"#/components/schemas/Session"},"metadata":{"$ref":"#/components/schemas/ArchivedExportMetadata"}},"required":["summary","session","metadata"]}},"totalElements":{"type":"integer","format":"int64"},"exportedElements":{"type":"integer","format":"int64"},"exportLimit":{"type":"integer","format":"int64","deprecated":true,"description":"Compatibility field equal to totalElements, not a maximum export count."},"failedSessionIds":{"type":"array","items":{"type":"string"}}},"required":["exportedAt","filters","conversations","totalElements","exportedElements","exportLimit","failedSessionIds"]},"Session":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"page":{"type":"string"},"closedBy":{"type":["string","null"]},"siteId":{"type":["string","null"]},"websocketUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"visitorContact":{"anyOf":[{"$ref":"#/components/schemas/VisitorContact"},{"type":"null"}]},"labels":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SessionLabel"}},{"type":"null"}]}},"required":["sessionId","status","page","closedBy","siteId","websocketUrl","createdAt","lastActivityAt","closedAt","participants","messages","visitorContact","labels"]},"ArchivedExportMetadata":{"type":"object","properties":{"repId":{"type":["string","null"]},"orgId":{"type":["string","null"]},"standinId":{"type":["string","null"]},"closedByType":{"type":["string","null"]},"modelName":{"type":["string","null"]},"visitorTimezone":{"type":["string","null"]},"followupReason":{"type":["string","null"]},"greetingVariantId":{"type":["string","null"]},"handledBy":{"type":"string","enum":["rep","agent"]},"inputTokens":{"type":["integer","null"]},"outputTokens":{"type":["integer","null"]},"followupRequested":{"type":"boolean"},"greetingConversationStarted":{"type":"boolean"}},"required":["repId","orgId","standinId","closedByType","modelName","visitorTimezone","followupReason","greetingVariantId","handledBy","inputTokens","outputTokens","followupRequested","greetingConversationStarted"]},"StandinProfile":{"type":"object","properties":{"standinProfileId":{"type":["string","null"]},"repId":{"type":["string","null"]},"name":{"type":["string","null"]},"displayName":{"type":["string","null"]},"displayBrandName":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"greeting":{"type":["string","null"]},"prompt":{"type":["string","null"]},"toolsEnabled":{"type":["string","null"]},"siteId":{"type":["string","null"]},"pathPrefix":{"type":"string"},"enabled":{"type":"boolean"},"deleted":{"type":"boolean"},"hasSessions":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"starterQuestions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":4,"description":"Normalized questions visitors can tap for their first message, in display order. An empty array means none. Older responses may omit this field."},"suggestNextQuestions":{"type":"boolean","description":"Whether the Stand-in offers up to two follow-up questions after a reply. Older responses may omit this field; treat omission as false."}},"required":["standinProfileId","repId","name","displayName","displayBrandName","avatarUrl","greeting","prompt","toolsEnabled","siteId","pathPrefix","enabled","deleted","hasSessions","createdAt"]},"StandinProfileInput":{"type":"object","properties":{"name":{"type":"string","description":"Internal name. Required on both create and update.","minLength":1,"maxLength":255,"pattern":"\\S"},"displayName":{"type":"string","description":"Visitor-facing name. Required on both create and update.","minLength":1,"maxLength":255,"pattern":"\\S"},"prompt":{"type":"string","description":"Complete instructions. Required and nonblank. The effective plan imposes a character limit: 4,000 on Base/Pro and 8,000 on Business.","minLength":1,"pattern":"\\S"},"displayBrandName":{"type":["string","null"],"maxLength":255,"description":"Omission, null or blank clears the brand name. Trimmed length must be at most 255 characters."},"avatarUrl":{"type":["string","null"],"maxLength":255,"description":"On update, omission or null preserves the avatar; an explicit blank string clears it. On create, omission means no avatar."},"greeting":{"type":["string","null"],"description":"Complete greeting; omission or null clears it."},"toolsEnabled":{"type":["string","null"],"contentMediaType":"application/json","contentSchema":{"type":"object","additionalProperties":true},"description":"A string containing exactly one valid JSON object, not an object-valued request field. Omission or null resets it to the string {}. Malformed JSON, scalars and arrays return 400."},"siteId":{"type":["string","null"],"description":"Site in your organization. Omission, null or blank removes the site restriction."},"pathPrefix":{"type":["string","null"],"description":"URL path restriction on siteId; requires a nonblank siteId when nonblank. Omission, null or blank resets to the whole site."},"starterQuestions":{"type":["array","null"],"items":{"type":["string","null"]},"description":"Optional first-message questions. The server strips leading/trailing whitespace, collapses inner whitespace, drops null/blank entries and removes case-insensitive duplicates while retaining order. After normalization, at most 4 questions of at most 60 Unicode code points each are allowed; otherwise 400 BAD_REQUEST. Raw array size and string length are not the normalized limits. On create, omission/null means []; on update, omission/null preserves the saved questions and [] clears them."},"suggestNextQuestions":{"type":["boolean","null"],"description":"Offers up to two follow-up questions after each Stand-in reply. On create, omission/null defaults to false; on update, omission/null preserves the saved setting. Set false explicitly to turn it off."}},"required":["name","displayName","prompt"],"allOf":[{"if":{"required":["pathPrefix"],"properties":{"pathPrefix":{"type":"string","pattern":"\\S"}}},"then":{"required":["siteId"],"properties":{"siteId":{"type":"string","pattern":"\\S"}}}}],"examples":[{"name":"Website help","displayName":"Alex","displayBrandName":"Example","avatarUrl":null,"greeting":"How can I help?","prompt":"Answer questions about our public help pages.","toolsEnabled":"{}","siteId":"site-id-from-listSites","pathPrefix":"/help","starterQuestions":["How does setup work?"],"suggestNextQuestions":false}]},"KnowledgeBaseOverview":{"type":"object","properties":{"planCode":{"type":["string","null"]},"planName":{"type":["string","null"]},"capabilities":{"$ref":"#/components/schemas/KnowledgeBaseCapabilities"},"usage":{"$ref":"#/components/schemas/KnowledgeBaseUsage"},"limitsReached":{"type":"array","items":{"type":"string"}},"createAllowed":{"type":"boolean"},"ingestionAllowed":{"type":"boolean"},"graceReadOnly":{"type":"boolean"},"businessAllowed":{"type":"boolean"},"ingestionUnavailableReason":{"type":["string","null"]},"knowledgeBases":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBase"}},"maxPagesPerCrawl":{"type":"integer"},"maxPagesPerSitemap":{"type":"integer"},"maxAttachedPerAgent":{"type":"integer"},"quota":{"$ref":"#/components/schemas/KnowledgeBaseQuota"}},"required":["planCode","planName","capabilities","usage","limitsReached","createAllowed","ingestionAllowed","graceReadOnly","businessAllowed","ingestionUnavailableReason","knowledgeBases","maxPagesPerCrawl","maxPagesPerSitemap","maxAttachedPerAgent","quota"]},"KnowledgeBaseCapabilities":{"type":"object","properties":{"knowledgeBaseCountLimit":{"type":["integer","null"]},"pageCountLimit":{"type":["integer","null"]},"storageBytesLimit":{"type":["integer","null"]},"storageLimitAdvertised":{"type":"boolean"},"documentUploadAllowed":{"type":"boolean","description":"Effective document-upload entitlement, normally true on Pro and Business. This capability does not by itself grant ownership, knowledge:write, ingestion-worker availability, or permission to exceed current ingestion/grace limits."},"sitemapAllowed":{"type":"boolean"},"automaticRefreshAllowed":{"type":"boolean"},"maxAttachedPerAgent":{"type":"integer"}},"required":["knowledgeBaseCountLimit","pageCountLimit","storageBytesLimit","storageLimitAdvertised","documentUploadAllowed","sitemapAllowed","automaticRefreshAllowed","maxAttachedPerAgent"]},"KnowledgeBaseUsage":{"type":"object","properties":{"knowledgeBaseCount":{"type":"integer"},"pageCount":{"type":"integer"},"storageBytes":{"type":"integer"}},"required":["knowledgeBaseCount","pageCount","storageBytes"]},"KnowledgeBase":{"type":"object","properties":{"knowledgeBaseId":{"type":"string"},"orgId":{"type":"string"},"ownerRepId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"ownedByCurrentRep":{"type":"boolean"},"pagesIngested":{"type":"integer"},"storageBytes":{"type":"integer"},"attachedAgentCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["knowledgeBaseId","orgId","ownerRepId","name","description","ownedByCurrentRep","pagesIngested","storageBytes","attachedAgentCount","createdAt","updatedAt"]},"KnowledgeBaseQuota":{"type":"object","properties":{"storageBytesUsed":{"type":"integer"},"storageBytesLimit":{"type":["integer","null"]},"uploadBytesUsed":{"type":"integer"},"uploadBytesLimit":{"type":["integer","null"]}},"required":["storageBytesUsed","storageBytesLimit","uploadBytesUsed","uploadBytesLimit"]},"KnowledgeBaseCreate":{"type":"object","properties":{"name":{"type":"string","description":"Required nonblank name; at most 255 UTF-16 code units after stripping surrounding Java whitespace."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description, including on rename. Copy the current description to preserve it."}},"required":["name"],"examples":[{"name":"Help center renamed","description":"Copy the existing description here to retain it."}]},"KnowledgeBaseIngestionTask":{"type":"object","properties":{"taskId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"taskType":{"type":"string"},"status":{"type":"string","description":"Known active states are queued and processing. Known terminal states are completed, failed, cancelled, and partially_failed. partially_failed means some work failed and must not be treated as a complete successful ingestion. Inspect errorMessage and source/document results. Poll GET /v1/knowledge-bases/{knowledgeBaseId}/tasks by taskId; cancellation is a request and unknown future states must not be assumed successful.","x-extensible-enum":["queued","processing","completed","failed","cancelled","partially_failed"]},"sourceId":{"type":["string","null"]},"currentStage":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"workerId":{"type":["string","null"]},"pipelineVersion":{"type":["string","null"]},"progressCurrent":{"type":"integer"},"progressTotal":{"type":"integer"},"retryCount":{"type":"integer"},"cancelRequested":{"type":"boolean"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["taskId","knowledgeBaseId","taskType","status","sourceId","currentStage","errorMessage","workerId","pipelineVersion","progressCurrent","progressTotal","retryCount","cancelRequested","startedAt","completedAt","createdAt","updatedAt"]},"KnowledgeBaseSource":{"type":"object","properties":{"sourceId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceType":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"},"originalFilename":{"type":["string","null"]},"originalUrl":{"type":["string","null"]},"crawlDomain":{"type":["string","null"]},"crawlUrlPrefix":{"type":["string","null"]},"crawlMaxDepth":{"type":["integer","null"]},"rawSizeBytes":{"type":"integer"},"pageCount":{"type":"integer"},"vectorCount":{"type":"integer"},"sitemapRefreshEnabled":{"type":"boolean"},"sitemapLastCheckedAt":{"type":["string","null"],"format":"date-time"},"sitemapLastSuccessAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["sourceId","knowledgeBaseId","sourceType","displayName","status","originalFilename","originalUrl","crawlDomain","crawlUrlPrefix","crawlMaxDepth","rawSizeBytes","pageCount","vectorCount","sitemapRefreshEnabled","sitemapLastCheckedAt","sitemapLastSuccessAt","createdAt","updatedAt"]},"KnowledgeBaseDocument":{"type":"object","properties":{"documentId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"status":{"type":"string"},"title":{"type":["string","null"]},"originalUrl":{"type":["string","null"]},"rawSizeBytes":{"type":"integer"},"chunkCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["documentId","knowledgeBaseId","sourceId","status","title","originalUrl","rawSizeBytes","chunkCount","createdAt","updatedAt"]},"KnowledgeBaseDocumentDetail":{"type":"object","properties":{"documentId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"status":{"type":"string"},"title":{"type":["string","null"]},"originalUrl":{"type":["string","null"]},"rawSizeBytes":{"type":"integer"},"chunkCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"text":{"type":"string"}},"required":["documentId","knowledgeBaseId","sourceId","status","title","originalUrl","rawSizeBytes","chunkCount","createdAt","updatedAt","text"]},"KnowledgeBaseChunk":{"type":"object","properties":{"chunkId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"documentId":{"type":"string"},"chunkText":{"type":"string"},"sourceUrl":{"type":["string","null"]},"chunkIndex":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Source-format-specific ingestion metadata. Keys vary by source type; consumers must not require undocumented keys."}},"required":["chunkId","knowledgeBaseId","sourceId","documentId","chunkText","sourceUrl","chunkIndex","metadata"]},"KnowledgeBaseSearch":{"type":"object","properties":{"query":{"type":"string"},"topK":{"type":"integer","default":5}},"required":["query"]},"KnowledgeBaseSearchResult":{"type":"object","properties":{"chunkId":{"type":"string"},"knowledgeBaseId":{"type":"string"},"sourceId":{"type":"string"},"documentId":{"type":"string"},"chunkText":{"type":"string"},"sourceUrl":{"type":["string","null"]},"sourceName":{"type":["string","null"]},"documentTitle":{"type":["string","null"]},"score":{"type":"number"},"metadata":{"type":"object","additionalProperties":true,"description":"Source-format-specific ingestion metadata. Keys vary by source type; consumers must not require undocumented keys."}},"required":["chunkId","knowledgeBaseId","sourceId","documentId","chunkText","sourceUrl","sourceName","documentTitle","score","metadata"]},"AgentKnowledgeBases":{"type":"object","properties":{"knowledgeBaseIds":{"type":"array","items":{"type":"string"}},"maxAttached":{"type":"integer"},"planCode":{"type":["string","null"]},"capabilities":{"$ref":"#/components/schemas/KnowledgeBaseCapabilities"},"graceReadOnly":{"type":"boolean"},"businessAllowed":{"type":"boolean"}},"required":["knowledgeBaseIds","maxAttached","planCode","capabilities","graceReadOnly","businessAllowed"]},"IntegrationOverview":{"type":"object","properties":{"proAllowed":{"type":"boolean"},"businessAllowed":{"type":"boolean"},"credentialsAvailable":{"type":"boolean"},"writeToolsAvailable":{"type":"boolean"},"maxAttachedPerAgent":{"type":"integer"},"maxRuntimeToolsPerAgent":{"type":"integer"},"availableTypes":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationTypeOption"}},"integrations":{"type":"array","items":{"$ref":"#/components/schemas/Integration"}}},"required":["proAllowed","businessAllowed","credentialsAvailable","writeToolsAvailable","maxAttachedPerAgent","maxRuntimeToolsPerAgent","availableTypes","integrations"]},"IntegrationTypeOption":{"type":"object","properties":{"providerKey":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"requiredPlan":{"type":"string"},"available":{"type":"boolean"},"implemented":{"type":"boolean"}},"required":["providerKey","name","type","requiredPlan","available","implemented"]},"Integration":{"type":"object","properties":{"integrationId":{"type":"string"},"orgId":{"type":"string"},"createdByRepId":{"type":"string"},"type":{"type":"string"},"providerKey":{"type":"string"},"name":{"type":"string"},"baseUrl":{"type":"string"},"authType":{"type":"string"},"description":{"type":["string","null"]},"authHeaderName":{"type":["string","null"]},"requiredPlan":{"type":["string","null"]},"secretConfigured":{"type":"boolean"},"available":{"type":"boolean"},"toolCount":{"type":"integer"},"attachedAgentCount":{"type":"integer"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationTool"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["integrationId","orgId","createdByRepId","type","providerKey","name","baseUrl","authType","description","authHeaderName","requiredPlan","secretConfigured","available","toolCount","attachedAgentCount","tools","createdAt","updatedAt"]},"IntegrationTool":{"type":"object","properties":{"toolKey":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"httpMethod":{"type":"string"},"path":{"type":"string"},"readOnly":{"type":"boolean"},"inputSchema":{"type":"object","additionalProperties":true,"description":"Imported JSON Schema describing this tool input. Its properties come from the customer OpenAPI document."},"executionConfig":{"$ref":"#/components/schemas/IntegrationExecutionConfig"},"toolId":{"type":"string"},"integrationId":{"type":"string"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["toolKey","summary","description","httpMethod","path","readOnly","inputSchema","executionConfig","toolId","integrationId","enabled","createdAt","updatedAt"]},"IntegrationExecutionConfig":{"type":"object","properties":{"parameters":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string"},"name":{"type":"string"},"in":{"type":"string"},"collectionFormat":{"type":"string"}},"required":["property","name","in"]}},"bodyProperty":{"type":"string"},"contentType":{"type":"string"}},"required":["parameters"]},"IntegrationPreview":{"type":"object","properties":{"providerKey":{"type":"string"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationToolPreview"}},"maxDocumentChars":{"type":"integer"},"maxOperations":{"type":"integer"},"maxSchemaDepth":{"type":"integer"},"maxDescriptionChars":{"type":"integer"}},"required":["providerKey","tools","maxDocumentChars","maxOperations","maxSchemaDepth","maxDescriptionChars"]},"IntegrationToolPreview":{"type":"object","properties":{"toolKey":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"httpMethod":{"type":"string"},"path":{"type":"string"},"readOnly":{"type":"boolean"},"inputSchema":{"type":"object","additionalProperties":true,"description":"Imported JSON Schema describing this tool input. Its properties come from the customer OpenAPI document."},"executionConfig":{"$ref":"#/components/schemas/IntegrationExecutionConfig"}},"required":["toolKey","summary","description","httpMethod","path","readOnly","inputSchema","executionConfig"]},"OpenApiIntegrationSource":{"type":"object","properties":{"openApiDocument":{"type":"string"}},"required":["openApiDocument"]},"IntegrationCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Required on create and update. Trimmed name is limited to 120 characters."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description; normalized content is truncated to 1,000 characters."},"baseUrl":{"type":"string","minLength":1,"pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^\\s/?#@]+(?:/[^\\s?#]*)?\\s*$","description":"Required public HTTP(S) base URL, without credentials, query or fragment. Public-address/DNS safety and port validity are checked by the server. Authenticated integrations require HTTPS."},"authType":{"type":["string","null"],"pattern":"^\\s*(?:[nN][oO][nN][eE]|[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC]|)\\s*$","description":"Supported values: none, bearer, api_key_header, basic (trimmed and case-insensitive). Omission, null or blank means none, including on update: this removes existing authentication."},"authHeaderName":{"type":["string","null"],"description":"Required for api_key_header. Valid non-reserved HTTP header token, at most 120 characters after trimming; ignored for other authentication types."},"authUsername":{"type":["string","null"],"description":"Required with a new basic-auth secret; nonblank, at most 512 UTF-16 code units, without colon or control characters. Omit when preserving stored credentials."},"authSecret":{"type":["string","null"],"writeOnly":true,"description":"Required for non-none authentication on create. On update, omit/null/blank preserves the stored secret only when authentication type, baseUrl and header are unchanged and no username is supplied; otherwise a replacement secret is required. Never log it."},"openApiDocument":{"type":"string","minLength":1,"pattern":"\\S","description":"OpenAPI JSON or YAML declaration as a string. Required and nonblank on create. On update, a nonblank value replaces the source and tools; omission/null/blank preserves them. Parser limits and operation validity are checked by the server."},"enabledToolKeys":{"type":["array","null"],"items":{"type":["string","null"]},"description":"Legacy selection fallback used only if selectedTools has no nonblank tool keys. At least one selected operation must exist in the declaration; at most 50 distinct tools. Omit or send [] when retaining tools on update."},"selectedTools":{"type":["array","null"],"items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"description":"Selected tool keys and optional read-only classifications. Nonblank keys take precedence over enabledToolKeys; null/blank entries are ignored. Keys must be returned by previewOpenApiIntegration. Omit or send [] when retaining tools on update."}},"required":["name","baseUrl","openApiDocument"],"allOf":[{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},"then":{"properties":{"baseUrl":{"type":"string","pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]://"}}}},{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR])\\s*$"}}},"then":{"required":["authHeaderName"],"properties":{"authHeaderName":{"type":"string","minLength":1,"pattern":"^\\s*[A-Za-z0-9!#$%&'*+.^_`|~-]+\\s*$"}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"required":["authUsername"],"properties":{"authUsername":{"type":"string","minLength":1,"pattern":"^[^:\\u0000-\\u001f\\u007f-\\u009f]*[^\\s:\\u0000-\\u001f\\u007f-\\u009f][^:\\u0000-\\u001f\\u007f-\\u009f]*$"}}}},{"anyOf":[{"required":["selectedTools"],"properties":{"selectedTools":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"contains":{"type":"object","properties":{"toolKey":{"type":"string","minLength":1,"pattern":"\\S"}},"required":["toolKey"]}}}},{"required":["enabledToolKeys"],"properties":{"enabledToolKeys":{"type":"array","items":{"type":["string","null"]},"contains":{"type":"string","minLength":1,"pattern":"\\S"}}}}]},{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},"then":{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}}],"examples":[{"name":"Orders","description":"Read order information","baseUrl":"https://example.com","authType":"none","openApiDocument":"{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Orders\",\"version\":\"1.0.0\"},\"paths\":{\"/orders\":{\"get\":{\"operationId\":\"listOrders\",\"responses\":{\"200\":{\"description\":\"Order list\"}}}}}}","selectedTools":[{"toolKey":"listOrders","readOnly":true}]}]},"AgentIntegrations":{"type":"object","properties":{"integrationIds":{"type":"array","items":{"type":"string"}},"maxAttached":{"type":"integer"},"proAllowed":{"type":"boolean"},"businessAllowed":{"type":"boolean"}},"required":["integrationIds","maxAttached","proAllowed","businessAllowed"]},"OptionalLapelPin":{"type":"object","properties":{"lapelPin":{"anyOf":[{"$ref":"#/components/schemas/LapelPin"},{"type":"object","properties":{},"maxProperties":0}],"description":"An empty object denotes no configured pin; it is not null."}},"required":["lapelPin"]},"AgentSkill":{"type":"object","properties":{"skillKey":{"type":"string"},"enabled":{"type":"boolean"},"available":{"type":"boolean"},"requiredPlan":{"type":["string","null"]},"limit":{"type":["integer","null"]},"config":{"$ref":"#/components/schemas/AgentSkillConfig"}},"required":["skillKey","enabled","available","requiredPlan","limit","config"]},"AgentSkillConfig":{"type":"object","properties":{"guidance":{"type":"string"},"recipientEmail":{"type":"string"},"candidateCriteria":{"type":"string"},"learningGoal":{"type":"string"},"avoid":{"type":"string"},"interviewDepth":{"type":"string"},"learningQuestions":{"type":"array","items":{"type":"string"}},"maxQuestions":{"type":"integer"},"notify":{"type":"boolean"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkillLabel"}},"maxActiveLabels":{"type":"integer"}}},"AgentSkillLabel":{"type":"object","properties":{"labelId":{"type":"string"},"name":{"type":"string"},"prompt":{"type":"string"},"testPrompt":{"type":"string"},"position":{"type":"integer"},"active":{"type":"boolean"},"effectiveActive":{"type":"boolean"},"notify":{"type":"boolean"}},"required":["labelId","name","prompt","testPrompt","position","active","effectiveActive","notify"]},"AgentSkillUpdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"config":{"anyOf":[{"$ref":"#/components/schemas/AgentSkillConfigInput"},{"type":"null"}],"description":"Omission/null preserves current configuration. followup merges supplied keys; customerDiscovery replaces configuration and normalizes omitted fields to defaults. labeling preserves labels unless config.labels is supplied, which replaces the full set ([] clears)."}},"required":["enabled"],"examples":[{"enabled":true},{"enabled":true,"config":{"labels":[{"labelId":"existing-label-id","name":"Pricing","prompt":"The visitor asks about pricing.","active":true,"notify":false}]}}]},"AgentSkillConfigInput":{"type":"object","properties":{"guidance":{"type":"string"},"recipientEmail":{"type":"string"},"candidateCriteria":{"type":"string"},"learningGoal":{"type":"string"},"avoid":{"type":"string"},"interviewDepth":{"type":"string"},"learningQuestions":{"type":"array","items":{"type":"string"}},"maxQuestions":{"type":"integer"},"notify":{"type":"boolean"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/AgentSkillLabelInput"}},"maxActiveLabels":{"type":"integer"}}},"AgentSkillLabelInput":{"type":"object","properties":{"labelId":{"type":["string","null"]},"name":{"type":"string","minLength":1,"maxLength":80,"pattern":"\\S"},"prompt":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"},"testPrompt":{"description":"Legacy prompt alias, used only when prompt is absent. Ignored when prompt is present, even if this alias is null or another JSON type."},"active":{"type":"boolean"},"notify":{"type":"boolean"}},"required":["name"],"if":{"required":["prompt"]},"then":{"required":["prompt"]},"else":{"required":["testPrompt"],"properties":{"testPrompt":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"}}}},"AvatarCandidates":{"type":"object","properties":{"candidates":{"type":"array","items":{"type":"object","properties":{"candidateId":{"type":"string"},"url":{"type":"string"}},"required":["candidateId","url"]}}},"required":["candidates"]},"StatsResponse":{"type":"object","properties":{"scope":{"type":"string"},"scopeId":{"type":"string"},"bucketType":{"type":"string"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/StatsBucket"}}},"required":["scope","scopeId","bucketType","buckets"]},"StatsBucket":{"type":"object","properties":{"bucketKey":{"type":"string"},"opportunity":{"type":"integer","format":"int64"},"show":{"type":"integer","format":"int64"},"activate":{"type":"integer","format":"int64"},"chatStart":{"type":"integer","format":"int64"},"sessionLengthSum":{"type":"integer","format":"int64"},"sessionLengthCount":{"type":"integer","format":"int64"}},"required":["bucketKey","opportunity","show","activate","chatStart","sessionLengthSum","sessionLengthCount"]},"LiveShowsResponse":{"type":"object","properties":{"shows":{"type":"integer","format":"int64"},"windowSeconds":{"type":"integer"},"coveredSiteCount":{"type":"integer"},"asOf":{"type":"string","format":"date-time"}},"required":["shows","windowSeconds","coveredSiteCount","asOf"]},"OrgUsage":{"type":"object","properties":{"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"chatCount":{"type":"integer"},"overageCount":{"type":"integer"},"chatsBalance":{"type":"integer"},"chatQuota":{"type":["integer","null"]},"periodType":{"type":["string","null"]},"accountBalanceCents":{"type":"integer","description":"Owner-only; omitted for members."}},"required":["periodStart","periodEnd","chatCount","overageCount","chatsBalance","chatQuota","periodType"]},"OrgPlan":{"type":"object","properties":{"planCode":{"type":"string"},"name":{"type":"string"},"planVersion":{"type":"integer"},"chatQuota":{"type":["integer","null"]},"periodType":{"type":["string","null"]},"priceCents":{"type":"integer"},"overageCents":{"type":"integer"},"promptCharacterLimit":{"type":"integer"},"billingCycle":{"type":"string"}},"required":["planCode","planVersion","name","chatQuota","periodType","promptCharacterLimit"]},"SiteUpdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"name":{"type":"string","maxLength":255},"defaultLanguageCode":{"type":["string","null"]},"embedOptions":{"$ref":"#/components/schemas/SiteEmbedOptionsUpdate","description":"Legacy compatibility input. On update, any supplied embedOptions object, including embedOptions: {}, merges supplied keys into the saved legacy options and then replaces behaviorConfig: advancedBehaviorEnabled and allowStandAdminBehavior become false, and all existing rules, including custom JavaScript rules, are replaced by zero or one legacy-default rule derived from the merged options. An explicit behaviorConfig in the same request is applied after this conversion and controls the final configuration. Owner-consent validation uses the committed configuration before any sibling mutation; all fields are validated before saving. For behavior edits, modern clients should read the Site and replace the complete behaviorConfig with both switches and every retained rule."},"behaviorConfig":{"$ref":"#/components/schemas/SiteBehaviorConfigInput"}},"anyOf":[{"required":["enabled"]},{"required":["name"]},{"required":["defaultLanguageCode"]},{"required":["embedOptions"]},{"required":["behaviorConfig"]}]},"SitePreferencesUpdate":{"type":"object","properties":{"siteIds":{"type":"array","items":{"type":"string"}}},"required":["siteIds"]},"DigestAiPreferencesUpdate":{"type":"object","properties":{"aiEnabled":{"type":"boolean"},"labels":{"type":["array","null"],"items":{"type":"object","properties":{"labelId":{"type":["string","null"]},"name":{"type":"string"},"testPrompt":{"type":"string"}},"required":["name","testPrompt"]},"maxItems":10,"description":"Complete replacement label set. Omission or null clears all labels unless the legacy tripwires field is used when labels is absent. [] explicitly clears. Preserve each current labelId, name and testPrompt to retain it."},"tripwires":{"description":"Legacy fallback used only when labels is absent; ignored when labels is present. Prefer labels."}},"required":["aiEnabled"],"if":{"not":{"required":["labels"]}},"then":{"properties":{"tripwires":{"type":["array","null"],"items":{"type":"object","properties":{"labelId":{"type":["string","null"]},"name":{"type":"string"},"testPrompt":{"type":"string"}},"required":["name","testPrompt"]},"maxItems":10}}},"examples":[{"aiEnabled":true,"labels":[{"labelId":"existing-label-id","name":"Pricing","testPrompt":"The visitor asks about pricing."}]}]},"KnowledgeBaseUpsert":{"type":"object","properties":{"name":{"type":"string","description":"Required nonblank name; at most 255 UTF-16 code units after stripping surrounding Java whitespace."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description, including on rename. Copy the current description to preserve it."}},"required":["name"],"examples":[{"name":"Help center renamed","description":"Copy the existing description here to retain it."}]},"IntegrationUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Required on create and update. Trimmed name is limited to 120 characters."},"description":{"type":["string","null"],"description":"Omission, null or blank clears the description; normalized content is truncated to 1,000 characters."},"baseUrl":{"type":"string","minLength":1,"pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^\\s/?#@]+(?:/[^\\s?#]*)?\\s*$","description":"Required public HTTP(S) base URL, without credentials, query or fragment. Public-address/DNS safety and port validity are checked by the server. Authenticated integrations require HTTPS."},"authType":{"type":["string","null"],"pattern":"^\\s*(?:[nN][oO][nN][eE]|[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC]|)\\s*$","description":"Supported values: none, bearer, api_key_header, basic (trimmed and case-insensitive). Omission, null or blank means none, including on update: this removes existing authentication."},"authHeaderName":{"type":["string","null"],"description":"Required for api_key_header. Valid non-reserved HTTP header token, at most 120 characters after trimming; ignored for other authentication types."},"authUsername":{"type":["string","null"],"description":"Required with a new basic-auth secret; nonblank, at most 512 UTF-16 code units, without colon or control characters. Omit when preserving stored credentials."},"authSecret":{"type":["string","null"],"writeOnly":true,"description":"Required for non-none authentication on create. On update, omit/null/blank preserves the stored secret only when authentication type, baseUrl and header are unchanged and no username is supplied; otherwise a replacement secret is required. Never log it."},"openApiDocument":{"type":["string","null"],"description":"OpenAPI JSON or YAML declaration as a string. Required and nonblank on create. On update, a nonblank value replaces the source and tools; omission/null/blank preserves them. Parser limits and operation validity are checked by the server."},"enabledToolKeys":{"type":["array","null"],"items":{"type":["string","null"]},"description":"Legacy selection fallback used only if selectedTools has no nonblank tool keys. At least one selected operation must exist in the declaration; at most 50 distinct tools. Omit or send [] when retaining tools on update."},"selectedTools":{"type":["array","null"],"items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"description":"Selected tool keys and optional read-only classifications. Nonblank keys take precedence over enabledToolKeys; null/blank entries are ignored. Keys must be returned by previewOpenApiIntegration. Omit or send [] when retaining tools on update."}},"required":["name","baseUrl"],"allOf":[{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},"then":{"properties":{"baseUrl":{"type":"string","pattern":"^\\s*[Hh][Tt][Tt][Pp][Ss]://"}}}},{"if":{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR])\\s*$"}}},"then":{"required":["authHeaderName"],"properties":{"authHeaderName":{"type":"string","minLength":1,"pattern":"^\\s*[A-Za-z0-9!#$%&'*+.^_`|~-]+\\s*$"}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"required":["authUsername"],"properties":{"authUsername":{"type":"string","minLength":1,"pattern":"^[^:\\u0000-\\u001f\\u007f-\\u009f]*[^\\s:\\u0000-\\u001f\\u007f-\\u009f][^:\\u0000-\\u001f\\u007f-\\u009f]*$"}}}},{"if":{"required":["openApiDocument"],"properties":{"openApiDocument":{"type":"string","minLength":1,"pattern":"\\S"}}},"then":{"anyOf":[{"required":["selectedTools"],"properties":{"selectedTools":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"toolKey":{"type":["string","null"]},"readOnly":{"type":["boolean","null"]}}},{"type":"null"}]},"contains":{"type":"object","properties":{"toolKey":{"type":"string","minLength":1,"pattern":"\\S"}},"required":["toolKey"]}}}},{"required":["enabledToolKeys"],"properties":{"enabledToolKeys":{"type":"array","items":{"type":["string","null"]},"contains":{"type":"string","minLength":1,"pattern":"\\S"}}}}]},"else":{"properties":{"selectedTools":{"type":["array","null"],"maxItems":0},"enabledToolKeys":{"type":["array","null"],"maxItems":0}}}},{"if":{"allOf":[{"required":["authType"],"properties":{"authType":{"type":"string","pattern":"^\\s*(?:[bB][eE][aA][rR][eE][rR]|[aA][pP][iI]_[kK][eE][yY]_[hH][eE][aA][dD][eE][rR]|[bB][aA][sS][iI][cC])\\s*$"}}},{"required":["authUsername"],"properties":{"authUsername":{"type":"string","minLength":1,"pattern":"\\S"}}}]},"then":{"required":["authSecret"],"properties":{"authSecret":{"type":"string","minLength":8,"pattern":"^[^\\u0000-\\u001f\\u007f-\\u009f]*[^\\s\\u0000-\\u001f\\u007f-\\u009f][^\\u0000-\\u001f\\u007f-\\u009f]*$","description":"New credential. At least 8 Unicode code points, at most 16,384 UTF-16 code units; control characters are rejected. Bearer/API-key values must fit ISO-8859-1. Never include this value in logs or diagnostics.","writeOnly":true}}}}],"examples":[{"name":"Orders renamed","description":"Read order information","baseUrl":"https://example.com","authType":"bearer"}]},"LapelPinInput":{"type":"object","properties":{"domain":{"type":["string","null"],"maxLength":255,"description":"Organization policy selector only: omission/null/blank selects the organization-wide default; a nonblank domain selects its own policy. Ignored for personal and Stand-in pins."},"pinType":{"type":["string","null"],"enum":["none","circle","pill","free",null],"description":"Omission or null resets to none, turning the pin off."},"color":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","maxLength":7},{"type":"null"}],"description":"Omission or null resets to #000000; blank is invalid."},"borderColor":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","maxLength":7},{"type":"string","pattern":"^[\\u0009-\\u000d\\u001c-\\u0020\\u1680\\u2000-\\u2006\\u2008-\\u200a\\u2028\\u2029\\u205f\\u3000]*$"},{"type":"null"}],"description":"Omission, null or a Java-blank string clears the color override; otherwise use #RRGGBB."},"fontFamily":{"type":["string","null"],"enum":["Arial","Verdana","Helvetica","Tahoma","Trebuchet MS","Times New Roman","Georgia","Garamond","Courier New","Brush Script MT","sans-serif","serif","monospace",null],"description":"Case-sensitive font name. Omission or null resets to sans-serif."},"fontColor":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","maxLength":7},{"type":"string","pattern":"^[\\u0009-\\u000d\\u001c-\\u0020\\u1680\\u2000-\\u2006\\u2008-\\u200a\\u2028\\u2029\\u205f\\u3000]*$"},{"type":"null"}],"description":"Omission, null or a Java-blank string clears the color override; otherwise use #RRGGBB."},"pillText":{"type":["string","null"],"maxLength":255,"description":"Omission or null clears the text."},"usePinAsBotAvatar":{"type":["boolean","null"],"description":"Omission or null resets to false."}},"examples":[{"pinType":"pill","color":"#000000","borderColor":null,"fontFamily":"sans-serif","fontColor":"#ffffff","pillText":"Ask me","usePinAsBotAvatar":false}]}}}}